[][src]Attribute Macro emacs_macros::defun

#[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.

Input Parameters

Each parameter must be one of the following:

  • An owned value of a type that implements FromLisp. This is for simple data types that have an equivalent in Lisp. Examples: i64, String, bool.

  • A shared/mutable reference. This gives access to data structures that other module functions have created and embedded in the Lisp runtime (through user-ptr objects).

  • A Lisp Value, or one of its "sub-types" (e.g. Vector). This allows holding off the conversion to Rust data structures until necessary, or working with values that don't have a meaningful representation in Rust, like Lisp lambdas.

  • An &Env. This enables interaction with the Lisp runtime. It does not appear in the function's Lisp signature. This is unnecessary if there is already another parameter with type Value, which allows accessing the runtime through Value.env.

Return Value

The return type must be Result<T>, where T is one of the following:

  • A type that implements IntoLisp. This is for simple data types that have an equivalent in Lisp. Example: i64, String, bool.

  • A type that implements Transfer. This allows embedding a native data structure in a user-ptr object, for read-only use cases. It requires user_ptr(direct) option to be specified.

  • An arbitrary type. This allows embedding a native data structure in a user-ptr object, for read-write use cases. It requires user_ptr option to be specified. If the data is to be shared with background Rust threads, user_ptr(rwlock) or user_ptr(mutex) must be used instead.

  • Value, or one of its "sub-types" (e.g. Vector). This is mostly useful for returning an input parameter unchanged.

Naming

By default, the function's Lisp name has the form <crate-prefix>[mod-prefix]<base-name>.

  • crate-prefix is the feature name followed by -. This can be customized by the name, defun_prefix, and separator options on #[module].

  • mod-prefix is constructed from the function's Rust mod path (with _ and :: replaced by -). This can be turned off crate-wide, or for individual function, using the option mod_in_name.

  • base-name is the function's Rust name (with _ replaced by -). This can be overridden with the option name, e.g. #[defun(name = "foo:bar")].