Crate emacs

This provides a high-level binding to emacs-module, Emacs’s support for dynamic modules.

Code for a minimal module looks like this:

use emacs::{defun, Env, Result, Value};

emacs::plugin_is_GPL_compatible!();

#[emacs::module(name = "greeting")]
fn init(_: &Env) -> Result<()> { Ok(()) }

#[defun]
fn say_hello(env: &Env, name: String) -> Result<Value<'_>> {
    env.message(&format!("Hello, {}!", name))
}

(require 'greeting)
(greeting-say-hello "Emacs")

See User Guide and examples.

Macros

define_errors

Defines new error signals.

plugin_is_GPL_compatible

Declares that this module is GPL-compatible. Emacs will not load it otherwise.

use_symbols

Defines static &OnceGlobalRef variables that point to corresponding Lisp symbols.

Structs

CallEnv

Like Env, but is available only in exported functions. This has additional methods to handle arguments passed from Lisp code.

Env

Main point of interaction with the Lisp runtime.

Error

The Error type, a wrapper around a dynamic error type.

GlobalRef

A “global reference” that can live outside the scope of an Env. This is useful for sharing an otherwise short-lived Lisp Value across multiple invocations of Rust functions defined with defun. Examples include efficient access to interned symbols or Lisp functions, and Rust-based multi-threading.

OnceGlobalRef

A GlobalRef that can be initialized once. This is useful for long-lived values that should be initialized when the dynamic module is loaded. A typical use case is specifying frequently-used symbols, which can be done with the help of the macro use_symbols!.

Value

A type that represents Lisp values. Values of this type can be copied around, but are lifetime-bound to the Env they come from.

Vector

A type that represents Lisp vectors. This is a wrapper around Value that provides vector-specific methods.

Enums

ErrorKind

Error types generic to all Rust dynamic modules.

Traits

FromLisp

Converting Lisp Value into a Rust type.

IntoLisp

Converting a Rust type into Lisp Value.

ResultExt

Emacs-specific extension methods for the standard library’s Result.

Transfer

Allowing a type to be exposed to Lisp, where its values appear as opaque objects, or “embedded user pointers” (printed as #<user-ptr ...>).

Type Aliases

Result

A specialized Result type for Emacs’s dynamic modules.

Attribute Macros

defun

Exports a function to the Lisp runtime. The function is bound when the module is loaded, even if it is defined inside another function which is never called.

module

Registers a function as the initializer, to be called when Emacs loads the module. Each dynamic module must have one and only one such function.