17.6 Closure Function Objects

Byte-compiled functions use a special data type: they are closures. Closures are used both for byte-compiled Lisp functions as well as for interpreted Lisp functions. Whenever such an object appears as a function to be called, Emacs uses the appropriate interpreter to execute either the byte-code or the non-compiled Lisp code.

Internally, a closure is much like a vector; its elements can be accessed using aref. Its printed representation is like that for a vector, with an additional ‘#’ before the opening ‘[’. It must have at least three elements; there is no maximum number, but only the first six elements have any normal use. They are:

argdesc

The descriptor of the arguments. This can either be a list of arguments, as described in Features of Argument Lists, or an integer encoding the required number of arguments. In the latter case, the value of the descriptor specifies the minimum number of arguments in the bits zero to 6, and the maximum number of arguments in bits 8 to 14. If the argument list uses &rest, then bit 7 is set; otherwise it’s cleared.

When the closure is a byte-code function, if argdesc is a list, the arguments will be dynamically bound before executing the byte code. If argdesc is an integer, the arguments will be instead pushed onto the stack of the byte-code interpreter, before executing the code.

code

For interpreted functions, this element is the (non-empty) list of Lisp forms that make up the function’s body. For byte-compiled functions, it is the string containing the byte-code instructions.

constants

For byte-compiled functions, this holds the vector of Lisp objects referenced by the byte code. These include symbols used as function names and variable names. For interpreted functions, this is nil if the function is using the old dynamically scoped dialect of Emacs Lisp, and otherwise it holds the function’s lexical environment.

stacksize

The maximum stack size this function needs. This element is left unused for interpreted functions.

docstring

The documentation string (if any); otherwise, nil. The value may be a number or a list, in case the documentation string is stored in a file. Use the function documentation to get the real documentation string (see Access to Documentation Strings).

interactive

The interactive spec (if any). This can be a string or a Lisp expression. It is nil for a function that isn’t interactive.

Here’s an example of a byte-code function object, in printed representation. It is the definition of the command backward-sexp.

#[256
  "\211\204^G^@\300\262^A\301^A[!\207"
  [1 forward-sexp]
  3
  1793299
  "^p"]

The primitive way to create a byte-code object is with make-byte-code:

Function: make-byte-code &rest elements ¶

This function constructs and returns a closure which represents the byte-code function object with elements as its elements.

You should not try to come up with the elements for a byte-code function yourself, because if they are inconsistent, Emacs may crash when you call the function. Always leave it to the byte compiler to create these objects; it makes the elements consistent (we hope).

The primitive way to create an interpreted function is with make-interpreted-closure:

Function: make-interpreted-closure args body env &optional docstring iform ¶

This function constructs and returns a closure representing the interpreted function with arguments args and whose body is made of body which must be a non-nil list of Lisp forms. env is the lexical environment in the same form as used with eval (see Eval). The documentation docstring if non-nil should be a string, and the interactive form iform if non-nil should be of the form (interactive arg-descriptor) (see Using interactive).