Next: , Previous: Eval During Compile, Up: Byte Compilation

21.7 Compiled-Function Objects

Byte-compiled functions have a special data type: they are compiled-function objects. The evaluator handles this data type specially when it appears as a function to be called.

The printed representation for a compiled-function object normally begins with ‘#<compiled-function’ and ends with ‘>’. However, if the variable print-readably is non-nil, the object is printed beginning with ‘#[’ and ending with ‘]’. This representation can be read directly by the Lisp reader, and is used in byte-compiled files (those ending in ‘.elc’).

In Emacs version 18, there was no compiled-function object data type; compiled functions used the function byte-code to run the byte code.

A compiled-function object has a number of different attributes. They are:

arglist
The list of argument symbols.
instructions
The string containing the byte-code instructions.
constants
The vector of Lisp objects referenced by the byte code. These include symbols used as function names and variable names.
stack-depth
The maximum stack size this function needs.
doc-string
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 Accessing Documentation).
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.
domain
The domain (if any). This is only meaningful if I18N3 (message-translation) support was compiled into SXEmacs. This is a string defining which domain to find the translation for the documentation string and interactive prompt. See Domain Specification.

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

     (symbol-function 'backward-sexp)
     ⇒ #<compiled-function
     (&optional arg)
     "...(15)" [arg 1 forward-sexp] 2 854740 "_p">

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

— Function: make-byte-code arglist instructions constants stack-depth &optional doc-string interactive

This function constructs and returns a compiled-function object with the specified attributes.

Please note: Unlike all other elisp functions, calling this with five arguments is not the same as calling it with six arguments, the last of which is nil. If the interactive arg is specified as nil, then that means that this function was defined with (interactive). If the arg is not specified, then that means the function is not interactive. This is terrible behavior which is retained for compatibility with old ‘.elc’ files which expected these semantics.

You should not try to come up with the elements for a compiled-function object yourself, because if they are inconsistent, SXEmacs 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 following primitives are provided for accessing the elements of a compiled-function object.

— Function: compiled-function-arglist function

This function returns the argument list of compiled-function object function.

— Function: compiled-function-instructions function

This function returns a string describing the byte-code instructions of compiled-function object function.

— Function: compiled-function-constants function

This function returns the vector of Lisp objects referenced by compiled-function object function.

— Function: compiled-function-stack-depth function

This function returns the maximum stack size needed by compiled-function object function.

— Function: compiled-function-doc-string function

This function returns the doc string of compiled-function object function, if available.

— Function: compiled-function-interactive function

This function returns the interactive spec of compiled-function object function, if any. The return value is nil or a two-element list, the first element of which is the symbol interactive and the second element is the interactive spec (a string or Lisp form).

— Function: compiled-function-domain function

This function returns the domain of compiled-function object function, if any. The result will be a string or nil. See Domain Specification.