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) (*)