Crate zsh_module

Zsh Module

This is a high level crate that allows you to define your own zsh module.

Getting started

To get started, first, you need to create library, not an executable. Then, change your crate type to "cdylib" on your Cargo.toml:

[lib]
crate-type = ["cdylib"]

Boilerplate

On your lib.rs, you need to put a export_module! macro call, alongside a setup function (can be called whatever you want):

use zsh_module::{ Module, ModuleBuilder };

zsh_module::export_module!(my_module, setup);

fn setup() -> Result<Module, Box<dyn std::error::Error>> {
   todo!()
}

The setup function

A proper setup function must return a Result<Module, E> where E implements Error. E.g:

fn setup() -> Result<Module, Box<dyn std::error::Error>> { .. }

fn setup() -> Result<Module, anyhow::Error> { .. }

fn setup() -> Result<Module, std::io::Error> { .. }

Storing User Data

You can store user data inside a module and have it accessible from any callbacks. Here’s an example module, located at that defines a new greet builtin command:

use zsh_module::{Builtin, MaybeError, Module, ModuleBuilder, Opts};

// Notice how this module gets installed as `rgreeter`
zsh_module::export_module!(rgreeter, setup);

struct Greeter;

impl Greeter {
    fn greet_cmd(&mut self, _name: &str, _args: &[&str], _opts: Opts) -> MaybeError {
        println!("Hello, world!");
        Ok(())
    }
}

fn setup() -> Result<Module, Box<dyn std::error::Error>> {
    let module = ModuleBuilder::new(Greeter)
        .builtin(Greeter::greet_cmd, Builtin::new("greet"))
        .build();
    Ok(module)
}

Installing

When your module is ready, copy your shared library to your distribution’s zsh module folder and name it whatever you want, the only requirement is that it ends with your platforms’s dynamic loadable library extension.

On my machine, the zsh module folder is /usr/lib/zsh/<zsh-version>/.

If everything went fine, you can load it in zsh using the following command:

zmodload <module-name>

That is it!

Modules

log

Zsh native log functions. This module contains high level interfaces to the zsh log functions.

zsh

A collection of functions used to interact directly with Zsh

Macros

error

Prints out an error message, like println!

error_named

Prints out an error message with a command name, like println!

export_module

Exports a setup function to be called when the module needs to be set up. You need to specify your module’s loadable name

warn

Prints out a warning message, like println!

warn_named

Prints out a warning message with a command name, like println!

Structs

Builtin

Properties of a zsh builtin command.

HashTable

A wrapper around Zsh’s hashtable implementation

Module

Hooks into the Zsh module system and connects it to your User Data.

ModuleBuilder

Allows you to build a Module

Opts

Represents all the options passed to a command.

Traits

ToCString

Represents any type that can be represented as a C String. You shouldn’t need to implement this yourself as the most commonly used string-y types already have this implemented.

Type Definitions

AnyError

A box error type for easier error handling.

MaybeError

Represents the possibility of an error E. It is basically a Result that only cares for its Err variant.

Trait Aliases

Cmd

This trait corresponds to the function signature of a zsh builtin command handler.