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.