Larceny Note #12: Procedure Documentation
Lars T Hansen / 25 November 1998
Compiled and interpreted code contains procedure documentation to aid in
debugging. This note documents the layout and location of the procedure
A procedure documentation datum is a vector; vectors are nice because
they are extensible. The vector contains the following fields, in
order. Any field can have the value #f, meaning "no
- Procedure-name: a symbol.
- Procedure-expression: a datum representing the source code.
- Arity: a nonnegative integer. If exact, then the procedure takes exactly
that many arguments. If inexact, then the procedure takes at least
that many arguments.
- File-name: a string denoting the originating file.
- File-position: an exact integer denoting the position of the source
code for the procedure within the file. If this field has the
value k, then k characters precede the opening
parenthesis of the source code.
Accessing the data
Procedure documentation data are most conveniently accessed with the procedure information accessors.
Additionally, the undocumented procedure
procedure-documentation can be used to retrieve documentation
from a procedure:
(procedure-documentation proc) => doc
(procedure-documentation proc offset) => doc
Returns procedure documentation for the procedure proc. If no
documentation is available, returns #f. The first form is
equivalent to the second form with offset=0.
If offset is supplied, then it must specify a valid instruction
address in the procedure's code vector, and the documentation structure
returned, if any, is the one appropriate for the given instruction.
The documentation slot is always slot 0 in the constant vector of a
procedure. Three values are legal for the documentation slot. If the
value is #f, then no information is available. If the value is a
vector, then that vector is the procedure documentation. If the value
is a list, then it must be a list of pairs. The pairs contain procedure
information for instruction-address ranges. The car of a pair is a
nonnegative exact fixnum: it is the first address for which the
documentation structure in the cdr is valid. The list is sorted on the
car of the pair.
The assembler sets up the procedure documentation structures from
information supplied by the compiler. The interface between the
compiler and assembler is insufficiently documented.
$Id: note12-procinfo.html 89 1998-11-25 14:46:38Z lth $