Allegro CL on the NeXT Welcome to Allegro CL, the implementation of Common Lisp on the NeXT machine. Allegro CL is a complete implementation of the Com- mon Lisp Language as specified in the book Common lisp: the Language by Guy Steele, Jr., and others. If you are familiar with Common Lisp, you may be familiar with Allegro CL from other machines. (The version on the NeXT is similar to versions available on other Unix workstations.) If you are new to Lisp, you may be surprised by how powerful the language is and how many features which you have to implement yourself in other languages are already implemented in Lisp - memory management, simple redefinition of functions, complex data types, the ability to read in and use compiled code written in other languages, and more. On the other hand, beginners will find Lisp takes some getting used to (all those parentheses!). If you are new to Lisp, please see the entry titled About Lisp: an Introduction. The documentation for Al- legro CL is partially online. The online portion consists of individual pages similar to Unix man pages. Most of the pages are titled by the symbol name which they describe. (A symbol is a fundamental data type in Lisp. It is the label used to identify functions, variables, constants, type specifier, etc.) For example, if you want to know how the LOAD function works, your would look at the page titled LOAD. We say the documentation is partial because only the extensions to standard Common lisp are documented online at this time. (A few standard Common Lisp symbols are also included if we have extended. LOAD and INSPECT are examples. Every symbol exists in a package. This package is specified in the manual page, but we are not wholly consistent in specifying the package whenever we use the symbol. Symbols in the LISP package (that is, the standard Common Lisp symbols) rarely have their package qualifier. Some- times we document specific keyword argument to functions. (We do this only for complicated functions. Most arguments are completely documented with the function. Even when we have a separate entry, we have a short description in the function definition entry. Keyword argument are all (of course) in the keyword package. We do identify the package of the function with the entry, however. Allegro CL has a wide range of top-level commands which are useful when running Lisp. These are identified with a colon prefix, just like key- words in Lisp. (Since keywords evaluate to themselves, nothing is gained by typing a keyword to the top-level. Therefore, the colon identifies a top- level command, not a keyword when typed to the top level. Entries on these commands are identified by the command name with the colon (indeed, both a single colon and a double colon are valid commands). Note that these are not symbols and are not in any package. There are other type of entries which are descriptive essays about Lisp concepts or facilities. All these entries are titled "about-<something>". For example, there is "about-advice", which describes the advice facility in Lisp. The entries similar to the online one discussed here for the standard Common Lisp functions and symbols are avail- able in printed form in the book Common Lisp: the Reference, published by Addison Wesley. The author is Franz Inc. (The book was written by the staff at Franz.) The book is generic for all Common Lisp implementations, but the examples (with minor exceptions) come from Allegro CL and show the behavior of Allegro CL. Common Lisp: the Reference should be available at any bookstore that stocks computer books. The online manual pages deal with the extensions to Common Lisp and they are not available in a printed form. Instead, there is a User Guide available from Franz Inc. (1995 University Ave., Berkeley, CA 94704) which presents the same material in a different form. The remainder of this entry contains a brief description of each extension to Common Lisp available in Allegro CL, followed by a list of symbols and About entries asso- ciated with the extension. We also provide a list of About entries dealing with standard Common Lisp, but not a list of Common Lisp symbols. (Such a list can be found in standard books on Common Lisp.) The extensions we discuss are: The advise facility The compiler The debugger The operating system/file system interface The foreign function interface The Objective C interface The inspector The Lisp system Memory management Miscellaneous extensions The multiprocessing facility The profiler The Top Level The advise facility The advise facility allows you to modify al- ready defined (even already compiled) functions without changing the function itself. Advice code can run before, after, or around the function itself. Before and around advice code can access and modify the arguments passed to the function. Around and after advice can access and modify the values re- turned by the function. The following entries relate to the advice facility. The starred entries are the most important. about-advice (*) advise (macro) (*) advise-1 (function) advised-functions (function) compile-advice (fspec) (*) *compile-advice* (variable) (*) defadvice (macro) describe-advice (func- tion) unadvise (macro) (*) unadvise-1 (function) The compiler Lisp code can be run either interpreted or compiled. Interpreted code is easier to debug while compiled code runs very much faster. As a general rule, correct code with proper input should have the same result whether interpreted or compiled. The code emitted by the compiler depends on the values of the Common Lisp optimi- zation qualities SAFETY, SPACE, and SPEED (note: these do not have individual entries - see the entry on OPTIMIZE). These values control what is returned by the compiler switches which in turn control what the compiler does. The entries relating to compiler are as follows. The starred entries are the most important. (Unqualified symbols are in the compiler package.) about-compiling (*) about-declarations (*) about-source-file-recording excl:compile-file-if- needed (function) :cf (top-level command) (*) :cload (top-level command) (*) excl:def-function-spec-handler (macro) :explain (declaration value) excl:*fasl-default-type* (variable) generate-call-count-code-switch (variable) generate-interrupt-checks-switch (variable) excl:get-function (function) save-local-names-switch (variable) tail-merge-switch (variable) target-fpp (function) trust-declarations-switch (variable) excl:uncompile (function) (*) verify-argument-count-switch (variable) verify-car-cdr-switch (variable) verify-non-generic-switch (variable) verify-symbol-value-is-bound-switch (variable) The debugger When you run Lisp, you do so within the Lisp environ- ment. When a piece of Lisp code breaks, you remain in Lisp and you may use the debugging tools provided by Lisp to figure out what went wrong with your code. Most of these tools are part of the Top Level (described below). Most are effected with top-level commands (an extension to standard Common Lisp) rather than Lisp functions. The entries relating to the debugger are as fol- lows. The starred entries are the most important. (Unqualified symbols are in the top-level package.) about-debugging (*) about-inspecting about-the- top-level (*) :all (argument to :zoom) (*) :arrest (top-level command) *auto- zoom* (variable) :bottom (top-level command) :break-after (argument to :trace) :break-all (argument to :trace) :break-before (argument to :trace) :condition (argument to :trace) :continue (top-level command) :current (top-level com- mand) :dn (top-level command) (*) :error (top-level command) :find (top-level command) (*) :focus (top-level command) (*) :hide (top-level command) :inside (argument to :trace) :inspect (top-level command) (*) :local (top-level com- mand) (*) :pop (top-level command) (*) :print-after (argument to :trace) :print-all (argument to :trace) :print-before (argument to :trace) :prt (top- level command) :reset (top-level command) (*) *reset-hook* (variable) :restart (top-level command) :return (top-level command) :scont (top-level command) :set-local (top-level command) :sover (top-level command) :step (top-level command) (*) excl:*step-print-length* (variable) excl:*step-print-level* (variable) :top (top-level command) :trace (top-level command) (*) excl:*trace-print-length* (variable) excl:*trace-print-level* (variable) :unhide (top-level command) :untrace (top-level command) (*) :up (top-level command) (*) :zoom (top-level command) (*) *zoom-display* (variable) *zoom- print-length* (variable) *zoom-print-level* (variable) *zoom-print-special- bindings* (variable) The Lisp system This covers customization of Lisp. Al- legro has some extensions not available in all other Common Lisp implementa- tions. One of the major one is control of case modes. Standard Common Lisp runs in a case-insensitive mode. All symbol names (unless specifically es- caped) are stored internal as upper-case strings. Allegro CL allows both case insensitive (standard) and case sensitive modes. The following entries relate to the Lisp system in general. The starred entries are the most important. about-autoloading (*) about-building-Lisp (*) about-case-modes (*) about- help-when-running-Lisp (*) about-initializing-Lisp (*) about-portability (*) about-the-top-level (*) excl:*current-case-mode* excl:set-case-mode The operating system/file system interface When you are running Lisp, you type to the Lisp system (not to a mach shell) and your commands are interpreted by Lisp. Allegro CL contains several functions which allow you to fork shell processes. Further, the Common Lisp datatype PATHNAME contains information about the location of files in the filesystem. The compiler and the loader are among the Lisp facilities which need to know about file location. The Com- mon Lisp functions OPEN and CLOSE also deal with files. The following are the entries (except standard Common Lisp entries) dealing with the operations sys- tem and the file system. The starred entries are the most important. (Un- qualified symbols are in the excl package.) about-file-types (*) about- pathnames about-search-lists (*) chdir (function) system:command-line-argument (function) system:command-line-argument-count (function) system:command-line- arguments (function) current-directory (function) discard-all-source-file-info (function) dumplisp (function) (*) exit (function) (*) file-older-p (function) generate-library-pathnames (function) getenv (function) load (standard Common Lisp function extended) (*) *load-search-list* (variable) (*) *open-rename- function* (variable) *open-rename-prefix* (variable) *open-rename-suffix* (variable) os-wait (function) *record-source-files* (variable) *restart- actions* (variable) run-shell-command (function) *redefinition-warnings* (variable) *require-search-list* (variable) shell (function) (*) source-file (function) *source-file-types* (variable) *source-pathname* (variable) username-to-home-directory (function) The foreign function interface The foreign function interface allows you to run compiled C and Fortran code from within Lisp. The foreign function interface thus allows Lisp to use already written C and Fortran code easily. It also permits you to write a user inter- face to any C or Fortran program in Lisp. (Lisp is very well suited to writ- ing user interfaces.) The following entries deal with the foreign function interface. The starred entires are the most important. (Unqualified symbols are in the foreign-functions package.) about-foreign-functions (*) about- passing-values :address (argument to DEFFOREIGN) :arg-checking (argument to DEFFOREIGN) :arguments (argument to DEFFOREIGN) :convert-symbol (argument to DEFFOREIGN) convert-to-lang (function) (*) defcstruct (macro) def-c-type (mac- ro) (*) def-c-typedef (macro) defforeign (function) (*) defforeign-list (func- tion) defun-c-callable (macro) :entry-point (argument to DEFFOREIGN) foreign- address (function) foreign-argument (function) :foreign-files (argument to LOAD) free-cstruct (function) get-entry-points (function) :language (argument to DEFFOREIGN) lisp-value (function) lisp:load (*) make-cstruct (function) malloc-cstruct (function) :pass-types (argument to DEFFOREIGN) :print (argu- ment to DEFFOREIGN) register-function (function) register-value (function) :remember-address (argument to DEFFOREIGN) remove-entry-point (function) reset-entry-point-table (function) :return-type (argument to DEFFOREIGN) :system-libraries (argument to LOAD) :unreferenced-library-names (argument to LOAD) The Objective C Interface There is an interface in Lisp to Objective C. Using the interface, you may create Objective C classes, methods, and in- stances from within Lisp. With the Objective C interface, you may access the Application Kit. The following entries deal with the objective C interface. The starred entries are the most important. about-objective-C (*) about-c- types (*) *all-classes* char*-to-string def-objc-class (*) def-objc-class- method (*) def-objc-method (*) _cmd (*) enable-[]-messages find-class isa (*) iv (*) make-application (*) objc-class-method objc-instance-p objc-method print-class print-class-ivars print-class-methods print-instance public-iv (*) self (*) send (*) send-super (*) simple-print-class simple-print-instance string-to-char* method-name-to-number (*) method-number-to-name (*) The in- spector The inspector allows you to look at the internals of Lisp objects. The Common Lisp standard calls for an inspector of some sort. In Allegro CL, the inspector is implemented with top-level commands. (The Common Lisp func- tion INSPECT is also supported, of course). The following entries deal with the inspector. The starred entries are the most important. about-inspecting (*) :inspect (*) lisp:inspect Memory management Lisp does its own memory management, normally in the background. If your application has special re- quirements, however, you may have to tune the memory management system using the functions and variables whose entries follow. The starred entries are the most important. (Unqualified symbols are in the system package.) about- garbage-collection (*) about-memory-management (*) :auto-step (gsgc switch) (*) :current-generation (gsgc parameter) :expansion-free-percent-new (gsgc parameter) :expansion-free-percent-old (gsgc parameter) :free-bytes-new-other (gsgc parameter) :free-bytes-new-pages (gsgc parameter) :free-percent-new (gsgc parameter) excl:gc (function) (*) excl:*gc-after-hook* (variable) (*) :generation-spread (gsgc parameter) excl:*global-gc-behavior* (variable) (*) gsgc-parameter (function) gsgc-parameters (function) gsgc-step-generation (function) gsgc-switch (function) (*) :hook-after-gc (gsgc switch) (*) :next- gc-is-global (gsgc switch) :print (gsgc switch) (*) :quantum (gsgc parameter) :stats (gsgc switch) :tenure-limit (gsgc parameter) excl:*tenured-bytes-limit* (variable) (*) Miscellaneous extensions Allegro CL includes a number of exten- sions which are not part of any specific facility but rather fill in holes in the Common Lisp standard or have proved themselves useful internally at Franz Inc. The following entries deal with these extensions. The starred entries are of particular note or usefulness. (Unqualified symbols are in the excl package.) arglist (function) bignump (function) *clear-input-on-error* (vari- able) *compiler-package* (variable) *current-case-mode* (variable) dribble-bug (function) errorset (macro) *excl-package* (variable) fixnump (function) if* (macro) *intern-allows-symbol* (variable) *ignore-package-name-case* (vari- able) interpreted-function-p (function) *keyword-package* (variable) *lisp- package* (variable) pp (macro) *print-nickname* (variable) *print-structure* (variable) ratiop (function) set-case-mode (function) single-float-p (func- tion) *system-package* (variable) *user-package* (variable) The multiprocess- ing facility The multiprocessing extension in Allegro CL allows you to have several processes running simultaneously within the same Lisp world. Note that these all run on the same processor - this is multiprocessing, not paral- lel processing. The following entries deal with the multiprocessing facility. The starred entries are the most important. (Unqualified symbols are in the multiprocessing package.) about-multiprocessing (*) about-process-dynamic- environments about-process-locks about-stack-groups about-the-scheduler (*) *all-processes* (variable) (*) excl:*cl-default-special-bindings* (variable) *current-process* (variable) system:*current-stack-group* (variable) system:*current-stack-group-resumer* (variable) excl:*default-lisp-listener- bindings* (variable) global-symbol-value (function) (*) excl:*initial- terminal-io* (variable) excl:lisp-sleep (function) (*) make-process (function) (*) make-process-lock (function) (*) make-stack-group (function) (*) process- active-p (function) process-add-arrest-reason (function) process-add-run- reason (function) process-allow-schedule (function) process-arrest-reasons (function) process-disable (function) process-enable (function) process-flush (function) process-initial-bindings (function) process-initial-form (function) process-interrupt (function) process-kill (function) process-lock (function) process-lock-locker (function) process-lock-p (function) process-name (func- tion) process-p (function) process-preset (function) process-priority (func- tion) process-property-list (function) process-quantum (function) process- reset (function) process-resume-hook (function) process-revoke-arrest-reason (function) process-revoke-run-reason (function) process-run-function (func- tion) process-run-reasons (function) process-run-restartable-function (func- tion) process-runnable-p (function) process-sleep (functions) (*) process- stack-group (function) process-suspend-hook (function) process-unlock (func- tion) process-wait (function) process-wait-args (function) process-wait- function (function) process-wait-with-timeout (function) process-whostate (function) tpl:set-default-lisp-listener-binding (macro) tpl:setq-default (macro) (*) stack-group-funcall (function) stack-group-name (function) stack- group-p (function) stack-group-preset (function) stack-group-resume (function) stack-group-resumer (function) stack-group-return (function) stack-group-state (function) tpl:start-interactive-top-level (function) start-scheduler (func- tion) (*) symeval-in-stack-group (function) tpl:top-level-read-eval-print-loop (function) tpl:*top-level-read-eval-print-loop-wrapper* (variable) with- process-lock (macro) with-timeout (macro) without-scheduling (macro) The pro- filer Allegro CL includes a call-counting profiler. The system will keep a record of all calls to a compiled function which was compiled so that they in- clude code to update the call counter (including most standard Common Lisp functions). The following functions retrieve such profiling data. The most important entries are starred. (Unqualified symbols are in the excl package.) about-profiling (*) function-call-clear (function) function-call-count (func- tion) function-call-list (function) function-call-report (function) function- call-run (macro) comp:generate-call-count-code-switch (variable) get-and- zero-call-count (function) The Top Level You communicate with Lisp through the top level. When you type to Lisp, the top level reader reads your input, the evaluator evaluates it, and the printer prints the results. You may enter Lisp forms to the top level. These are evaluated and the result returned by Lisp. There are also many top-level commands (these are not standard Lisp forms) which allow you to easily accomplish routine tasks, including compiling and loading files, printing a list of previous commands, retrying an earlier command, etc. The following entries deal with the top level. (We do not in- clude the debugger commands, strictly speaking part of the top level. They are described in the section on the debugger above.) The starred entries are the most important. (Unqualified symbols are in the top-level package.) about-debugging (*) about-the-top-level (*) alias (macro) :cf (top-level com- mand) (*) :cload (top-level command) (*) *command-char* (variable) do-command (function) (*) *eval* (variable) :exit (top-level command) (*) *exit-on-eof* (variable) *file-ignore-case* (variable) :help (top-level command) (*) :histo- ry (top-level command) (*) *history* (variable) :kill (top-level command) :ld (top-level command) (*) :macroexpand (top-level command) :optimize (top-level command) (*) :package (top-level command) *print* (variable) :printer- variables (top-level command) *print-length* (variable) *print-level* (vari- able) *prompt* (variable) :processes (top-level command) *read* (variable) remove-alias (function) :unarrest (top-level command) :: (top-level command) (*) : (top-level command) (*)