10.2 Basic Lisp Modules

lisp-disunion.h
lisp.h
lrecord.h
symsinit.h

These are the basic header files for all SXEmacs modules. Each module includes lisp.h, which brings the other header files in. lisp.h contains the definitions of the structures and extractor and constructor macros for the basic Lisp objects and various other basic definitions for the Lisp environment, as well as some general-purpose definitions (e.g. min() and max()). lisp.h includes lisp-disunion.h. These files define the typedef of the Lisp object itself (as described above) and the low-level macros that hide the actual implementation of the Lisp object. All extractor and constructor macros for particular types of Lisp objects are defined in terms of these low-level macros.

As a general rule, all typedefs should go into the typedefs section of lisp.h rather than into a module-specific header file even if the structure is defined elsewhere. This allows function prototypes that use the typedef to be placed into other header files. Forward structure declarations (i.e. a simple declaration like struct foo; where the structure itself is defined elsewhere) should be placed into the typedefs section as necessary.

lrecord.h contains the basic structures and macros that implement all record-type Lisp objects—i.e. all objects whose type is a field in their C structure, which includes all objects except the few most basic ones.

lisp.h contains prototypes for most of the exported functions in the various modules. Lisp primitives defined using DEFUN that need to be called by C code should be declared using EXFUN. Other function prototypes should be placed either into the appropriate section of lisp.h, or into a module-specific header file, depending on how general-purpose the function is and whether it has special-purpose argument types requiring definitions not in lisp.h.) All initialization functions are prototyped in symsinit.h.

alloc.c

The large module alloc.c implements all of the basic allocation and garbage collection for Lisp objects. The most commonly used Lisp objects are allocated in chunks, similar to the Blocktype data type described above; others are allocated in individually malloc()ed blocks. This module provides the foundation on which all other aspects of the Lisp environment sit, and is the first module initialized at startup.

Note that alloc.c provides a series of generic functions that are not dependent on any particular object type, and interfaces to particular types of objects using a standardized interface of type-specific methods. This scheme is a fundamental principle of object-oriented programming and is heavily used throughout SXEmacs. The great advantage of this is that it allows for a clean separation of functionality into different modules—new classes of Lisp objects, new event interfaces, new device types, new stream interfaces, etc. can be added transparently without affecting code anywhere else in SXEmacs. Because the different subsystems are divided into general and specific code, adding a new subtype within a subsystem will in general not require changes to the generic subsystem code or affect any of the other subtypes in the subsystem; this provides a great deal of robustness to the SXEmacs code.

eval.c
backtrace.h

This module contains all of the functions to handle the flow of control. This includes the mechanisms of defining functions, calling functions, traversing stack frames, and binding variables; the control primitives and other special forms such as while, if, eval, let, and, or, progn, etc.; handling of non-local exits, unwind-protects, and exception handlers; entering the debugger; methods for the subr Lisp object type; etc. It does not include the read function, the print function, or the handling of symbols and obarrays.

backtrace.h contains some structures related to stack frames and the flow of control.

lread.c

This module implements the Lisp reader and the read function, which converts text into Lisp objects, according to the read syntax of the objects, as described above. This is similar to the parser that is a part of all compilers.

print.c

This module implements the Lisp print mechanism and the print function and related functions. This is the inverse of the Lisp reader – it converts Lisp objects to a printed, textual representation. (Hopefully something that can be read back in using read to get an equivalent object.)

general.c
symbols.c
symeval.h

symbols.c implements the handling of symbols, obarrays, and retrieving the values of symbols. Much of the code is devoted to handling the special symbol-value-magic objects that define special types of variables—this includes buffer-local variables, variable aliases, variables that forward into C variables, etc. This module is initialized extremely early (right after alloc.c), because it is here that the basic symbols t and nil are created, and those symbols are used everywhere throughout SXEmacs.

symeval.h contains the definitions of symbol structures and the DEFVAR_LISP() and related macros for declaring variables.

data.c
floatfns.c
fns.c

These modules implement the methods and standard Lisp primitives for all the basic Lisp object types other than symbols (which are described above). data.c contains all the predicates (primitives that return whether an object is of a particular type); the integer arithmetic functions; and the basic accessor and mutator primitives for the various object types. fns.c contains all the standard predicates for working with sequences (where, abstractly speaking, a sequence is an ordered set of objects, and can be represented by a list, string, vector, or bit-vector); it also contains equal, perhaps on the grounds that bulk of the operation of equal is comparing sequences. floatfns.c contains methods and primitives for floats and floating-point arithmetic.

bytecode.c
bytecode.h

bytecode.c implements the byte-code interpreter and compiled-function objects, and bytecode.h contains associated structures. Note that the byte-code compiler is written in Lisp.