   This is a Texinfo GCL SYSTEM INTERNALS Manual

   Copyright 1994 William F. Schelter

Special Forms and Functions
***************************

 - Constant: LAMBDA-LIST-KEYWORDS
     Package:LISP List of all the lambda-list keywords used in GCL.

 - Function: GET-SETF-METHOD (FORM)
     Package:LISP

     Returns the five values (or five 'gangs') constituting the SETF
     method for FORM.  See the doc of DEFINE-SETF-METHOD for the
     meanings of the gangs.  It is an error if the third value (i.e.,
     the list of store variables) is not a one-element list.  See the
     doc of GET-SETF-METHOD-MULTIPLE-VALUE for comparison.

 - Special Form: THE
     Package:LISP

     Syntax:
          (the value-type form)

     Declares that the value of FORM must be of VALUE-TYPE.  Signals an
     error if this is not the case.

 - Special Form: SETF
     Package:LISP

     Syntax:
          (setf {place newvalue}*)

     Replaces the value in PLACE with the value of NEWVALUE, from left
     to right.  Returns the value of the last NEWVALUE.  Each PLACE may
     be any one of the following:
        * A symbol that names a variable.

        * A function call form whose first element is the name of the
          following     functions:
               nth	elt	subseq	rest	first ... tenth
               c?r	c??r	c???r	c????r
               aref	svref	char	schar	bit	sbit	fill-poiter
               get	getf	documentation	symbol-value	symbol-function
               symbol-plist	macro-function	gethash
               char-bit	ldb	mask-field
               apply
              where '?' stands for either 'a' or 'd'.

        * the form (THE type place) with PLACE being a place recognized
          by SETF.

        * a macro call which expands to a place recognized by SETF.

        * any form for which a DEFSETF or DEFINE-SETF-METHOD
          declaration has been     made.

 - Special Form: WHEN
     Package:LISP

     Syntax:
          (when test {form}*)

     If TEST evaluates to non-NIL, then evaluates FORMs as a PROGN.  If
     not, simply returns NIL.

 - Macro: CCASE
     Package:LISP

     Syntax:
          (ccase keyplace {({key | ({key}*)} {form}*)}*)

     Evaluates KEYPLACE and tries to find the KEY that is EQL to the
     value of KEYPLACE.  If one is found, then evaluates FORMs that
     follow the KEY and returns the value(s) of the last FORM.  If not,
     signals a correctable error.

 - Function: MACROEXPAND (FORM &optional (ENV NIL))
     Package:LISP

     If FORM is a macro form, then expands it repeatedly until it is
     not a macro any more.  Returns two values: the expanded form and a
     T-or-NIL flag indicating whether the original form was a macro.

 - Special Form: MULTIPLE-VALUE-CALL
     Package:LISP

     Syntax:
          (multiple-value-call function {form}*)

     Calls FUNCTION with all the values of FORMs as arguments.

 - Macro: DEFSETF
     Package:LISP

     Syntax:
          (defsetf access-fun {update-fun [doc] |
                                       lambda-list (store-var) {decl | doc}*
          {form}*)

     Defines how to SETF a generalized-variable reference of the form
     (ACCESS-FUN ...).  The doc-string DOC, if supplied, is saved as a
     SETF doc and can be retrieved by (documentation 'NAME 'setf).

          (defsetf access-fun update-fun) defines an expansion from
          (setf (ACCESS-FUN arg1 ... argn) value) to (UPDATE-FUN arg1 ... argn value).

          (defsetf access-fun lambda-list (store-var) . body) defines a macro which
     expands

          (setf (ACCESS-FUN arg1 ... argn) value) into the form
          	(let* ((temp1 ARG1) ... (tempn ARGn) (temp0 value)) rest)
     where REST is the value of BODY with parameters in LAMBDA-LIST
     bound to the symbols TEMP1 ... TEMPn and with STORE-VAR bound to
     the symbol TEMP0.

 - Special Form: TAGBODY
     Package:LISP

     Syntax:
          (tagbody {tag | statement}*)

     Executes STATEMENTs and returns NIL if it falls off the end.

 - Macro: ETYPECASE
     Package:LISP

     Syntax:
          (etypecase keyform {(type {form}*)}*)

     Evaluates KEYFORM and tries to find the TYPE in which the value of
     KEYFORM belongs.  If one is found, then evaluates FORMs that
     follow the KEY and returns the value(s) of the last FORM.  If not,
     signals an error.

 - Special Form: LET*
     Package:LISP

     Syntax:
          (let* ({var | (var [value])}*) {decl}* {form}*)

     Initializes VARs, binding them to the values of VALUEs (which
     defaults to NIL) from left to right, then evaluates FORMs as a
     PROGN.

 - Special Form: PROG1
     Package:LISP

     Syntax:
          (prog1 first {form}*)

     Evaluates FIRST and FORMs in order, and returns the (single) value
     of FIRST.

 - Special Form: DEFUN
     Package:LISP

     Syntax:
          (defun name lambda-list {decl | doc}* {form}*)

     Defines a function as the global function definition of the symbol
     NAME.  The complete syntax of a lambda-list is: 	({var}*
     [&optional {var | (var [initform [svar]])}*] 	 [&rest var]
     [&key {var | ({var | (keyword var)} [initform [svar]])}*
         [&allow-other-keys]] 	 [&aux {var | (var
     [initform])}*]) The doc-string DOC, if supplied, is saved as a
     FUNCTION doc and can be retrieved by (documentation 'NAME
     'function).

 - Special Form: MULTIPLE-VALUE-BIND
     Package:LISP

     Syntax:
          (multiple-value-bind ({var}*) values-form {decl}* {form}*)

     Binds the VARiables to the results of VALUES-FORM, in order
     (defaulting to NIL) and evaluates FORMs in order.

 - Special Form: DECLARE
     Package:LISP

     Syntax:
          (declare {decl-spec}*)

     Gives a declaration.  Possible DECL-SPECs are:   (SPECIAL {var}*)
     (TYPE type {var}*)      where 'TYPE' is one of the following
     symbols
          array		fixnum		package		simple-bit-vector
          atom		float		pathname	simple-string
          bignum		function	random-state	simple-vector
          bit		hash-table	ratio		single-float
          bit-vector	integer		rational	standard-char
          character	keyword		readtable	stream
          common		list		sequence	string
          compiled-function  long-float	short-float	string-char
          complex		nil		signed-byte	symbol
          cons		null		unsigned-byte	t
          double-float	number		simple-array	vector
         'TYPE' may also be a list containing one of the above symbols
     as its first element and more specific information later in the
     list.  For example
          (vector long-float 80) ; vector of 80 long-floats.
          (array long-float *)   ; array of long-floats
          (array fixnum)         ; array of fixnums
          (array * 30)           ; an array of length 30 but unspecified type

     A list of 1 element may be replaced by the symbol alone, and a
     list ending       in '*' may drop the the final  '*'.
          (OBJECT {var}*)
          (FTYPE type {function-name}*)
              eg: ;; function of two required args and optional args and one value:
               (ftype (function (t t *) t) sort reduce)
                  ;; function with 1 arg of general type returning 1 fixnum as value.
               (ftype (function (t) fixnum) length)
          (FUNCTION function-name ({arg-type}*) {return-type}*)
          (INLINE {function-name}*)
          (NOTINLINE {function-name}*)
          (IGNORE {var}*)
          (OPTIMIZE {({SPEED | SPACE | SAFETY | COMPILATION-SPEED} {0 | 1 | 2 | 3})}*)
          (DECLARATION {non-standard-decl-name}*)
          (:DYNAMIC-EXTENT {var}*) ;GCL-specific.

 - Special Form: DEFMACRO
     Package:LISP

     Syntax:
          (defmacro name defmacro-lambda-list {decl | doc}* {form}*)

     Defines a macro as the global macro definition of the symbol NAME.
     The complete syntax of a defmacro-lambda-list is:

     ( [&whole var]   [&environment var]   {pseudo-var}*   [&optional
     {var | (pseudo-var [initform [pseudo-var]])}*]   {[{&rest | &body}
     pseudo-var]    [&key {var | ({var | (keyword pseudo-var)}
     [initform [pseudo-var]])}*          [&allow-other-keys]]    [&aux
     {var | (pseudo-var [initform])}*]   |  . var})

     where pseudo-var is either a symbol or a list of the following
     form:

     ( {pseudo-var}*   [&optional {var | (pseudo-var [initform
     [pseudo-var]])}*]   {[{&rest | &body} pseudo-var]    [&key {var |
     ({var | (keyword pseudo-var)} [initform [pseudo-var]])}*
     [ &allow-other-keys ] ]    [&aux {var | (pseudo-var [initform])}*]
      |  . var})

     As a special case, a non-NIL symbol is accepcted as a
     defmacro-lambda-list: (DEFMACRO <name> <symbol> ...) is equivalent
     to (DEFMACRO <name> (&REST <symbol>) ...).       The doc-string
     DOC, if supplied, is saved as a FUNCTION doc and can be retrieved
     by (documentation 'NAME 'function).  See the type doc of LIST for
     the backquote macro useful for defining macros.  Also, see the
     function doc of PPRINT for the output-formatting.

 - Variable: *EVALHOOK*
     Package:LISP If *EVALHOOK* is not NIL, its value must be a
     function that can receive two arguments: a form to evaluate and an
     environment.  This function does the evaluation instead of EVAL.

 - Function: FUNCTIONP (X)
     Package:LISP

     Returns T if X is a function, suitable for use by FUNCALL or
     APPLY.  Returns NIL otherwise.

 - Constant: LAMBDA-PARAMETERS-LIMIT
     Package:LISP The exclusive upper bound on the number of distinct
     parameter names that may appear in a single lambda-list.
     Actually, however, there is no such upper bound in GCL.

 - Special Form: FLET
     Package:LISP

     Syntax:
          (flet ({(name lambda-list {decl | doc}* {form}*)}*) . body)

     Evaluates BODY as a PROGN, with local function definitions in
     effect.  BODY is the scope of each local function definition.
     Since the scope does not include the function definitions
     themselves, the local function can reference externally defined
     functions of the same name.  See the doc of DEFUN for the complete
     syntax of a lambda-list.  Doc-strings for local functions are
     simply ignored.

 - Macro: ECASE
     Package:LISP

     Syntax:
          (ecase keyform {({key | ({key}*)} {form}*)}*)

     Evaluates KEYFORM and tries to find the KEY that is EQL to the
     value of KEYFORM.  If one is found, then evaluates FORMs that
     follow the KEY and returns the value(s) of the last FORM.  If not,
     signals an error.

 - Special Form: PROG2
     Package:LISP

     Syntax:
          (prog2 first second {forms}*)

     Evaluates FIRST, SECOND, and FORMs in order, and returns the
     (single) value of SECOND.

 - Special Form: PROGV
     Package:LISP

     Syntax:
          (progv symbols values {form}*)

     SYMBOLS must evaluate to a list of variables.  VALUES must
     evaluate to a list of initial values.  Evaluates FORMs as a PROGN,
     with each variable bound (as special) to the corresponding value.

 - Special Form: QUOTE
     Package:LISP

     Syntax:
          (quote x)
     or 'x Simply returns X without evaluating it.

 - Special Form: DOTIMES
     Package:LISP

     Syntax:
          (dotimes (var countform [result]) {decl}* {tag | statement}*)

     Executes STATEMENTs, with VAR bound to each number between 0
     (inclusive) and the value of COUNTFORM (exclusive).  Then returns
     the value(s) of RESULT (which defaults to NIL).

 - Function: SPECIAL-FORM-P (SYMBOL)
     Package:LISP

     Returns T if SYMBOL globally names a special form; NIL otherwise.
     The special forms defined in Steele's manual are:
          block		if			progv
          catch		labels			quote
          compiler-let	let			return-from
          declare		let*			setq
          eval-when	macrolet		tagbody
          flet		multiple-value-call	the
          function	multiple-value-prog1	throw
          go		progn			unwind-protect

     In addition, GCL implements the following macros as special forms,
     though of course macro-expanding functions such as MACROEXPAND
     work correctly for these macros.

          and		incf			prog1
          case		locally			prog2
          cond		loop			psetq
          decf		multiple-value-bind	push
          defmacro	multiple-value-list	return
          defun		multiple-value-set	setf
          do		or			unless
          do*		pop			when
          dolist		prog
          dotimes		prog*

 - Special Form: FUNCTION
     Package:LISP

     Syntax:
          (function x)
     or #'x If X is a lambda expression, creates and returns a lexical
     closure of X in the current lexical environment.  If X is a symbol
     that names a function, returns that function.

 - Constant: MULTIPLE-VALUES-LIMIT
     Package:LISP The exclusive upper bound on the number of values
     that may be returned from a function.  Actually, however, there is
     no such upper bound in GCL.

 - Function: APPLYHOOK (FUNCTION ARGS EVALHOOKFN APPLYHOOKFN &optional
          (ENV NIL))
     Package:LISP

     Applies FUNCTION to ARGS, with *EVALHOOK* bound to EVALHOOKFN and
     with *APPLYHOOK* bound to APPLYHOOKFN.  Ignores the hook function
     once, for the top-level application of FUNCTION to ARGS.

 - Variable: *MACROEXPAND-HOOK*
     Package:LISP Holds a function that can take two arguments (a macro
     expansion function and the macro form to be expanded) and returns
     the expanded form.  This function is whenever a macro-expansion
     takes place.  Initially this is set to #'FUNCALL.

 - Special Form: PROG*
     Package:LISP

     Syntax:
          (prog* ({var | (var [init])}*) {decl}* {tag | statement}*)

     Creates a NIL block, binds VARs sequentially, and then executes
     STATEMENTs.

 - Special Form: BLOCK
     Package:LISP

     Syntax:
          (block name {form}*)

     The FORMs are evaluated in order, but it is possible to exit the
     block using (RETURN-FROM name value).  The RETURN-FROM must be
     lexically contained within the block.

 - Special Form: PROGN
     Package:LISP

     Syntax:
          (progn {form}*)

     Evaluates FORMs in order, and returns whatever the last FORM
     returns.

 - Function: APPLY (FUNCTION ARG &rest MORE-ARGS)
     Package:LISP

     Applies FUNCTION.  The arguments to the function consist of all
     ARGs except for the last, and all elements of the last ARG.

 - Special Form: LABELS
     Package:LISP

     Syntax:
          (labels ({(name lambda-list {decl | doc}* {form}*)}*) . body)

     Evaluates BODY as a PROGN, with the local function definitions in
     effect.  The scope of the locally defined functions include the
     function definitions themselves, so their definitions may include
     recursive references.  See the doc of DEFUN for the complete
     syntax of a lambda-list.  Doc-strings for local functions are
     simply ignored.

 - Special Form: RETURN
     Package:LISP

     Syntax:
          (return [result])

     Returns from the lexically surrounding NIL block.  The value of
     RESULT, which defaults to NIL, is returned as the value of the
     block.

 - Macro: TYPECASE
     Package:LISP

     Syntax:
          (typecase keyform {(type {form}*)}*)

     Evaluates KEYFORM and tries to find the TYPE in which the value of
     KEYFORM belongs.  If one is found, then evaluates FORMs that
     follow the KEY and returns the value of the last FORM.  If not,
     simply returns NIL.

 - Special Form: AND
     Package:LISP

     Syntax:
          (and {form}*)

     Evaluates FORMs in order from left to right.  If any FORM
     evaluates to NIL, returns immediately with the value NIL.  Else,
     returns the value(s) of the last FORM.

 - Special Form: LET
     Package:LISP

     Syntax:
          (let ({var | (var [value])}*) {decl}* {form}*)

     Initializes VARs, binding them to the values of VALUEs (which
     defaults to NIL) all at once, then evaluates FORMs as a PROGN.

 - Special Form: COND
     Package:LISP

     Syntax:
          (cond {(test {form}*)}*)
     Evaluates each TEST in order until one evaluates to a non-NIL
     value.  Then evaluates the associated FORMs in order and returns
     the value(s) of the last FORM.  If no forms follow the TEST, then
     returns the value of the TEST.  Returns NIL, if all TESTs evaluate
     to NIL.

 - Function: GET-SETF-METHOD-MULTIPLE-VALUE (FORM)
     Package:LISP  Returns the five values (or five 'gangs')
     constituting the SETF method for FORM.  See the doc of
     DEFINE-SETF-METHOD for the meanings of the gangs.  The third value
     (i.e., the list of store variables) may consist of any number of
     elements.  See the doc of GET-SETF-METHOD for comparison.

 - Special Form: CATCH
     Package:LISP

     Syntax:
          (catch tag {form}*)

     Sets up a catcher with that value TAG.  Then evaluates FORMs as a
     PROGN, but may possibly abort the evaluation by a THROW form that
     specifies the value EQ to the catcher tag.

 - Macro: DEFINE-MODIFY-MACRO
     Package:LISP

     Syntax:
          (define-modify-macro name lambda-list fun [doc])

     Defines a read-modify-write macro, like PUSH and INCF.  The
     defined macro will expand a form (NAME place val1 ... valn) into a
     form that in effect SETFs the value of the call (FUN PLACE arg1
     ... argm) into PLACE, where arg1 ... argm are parameters in
     LAMBDA-LIST which are bound to the forms VAL1 ... VALn.  The
     doc-string DOC, if supplied, is saved as a FUNCTION doc and can be
     retrieved by (documentation 'NAME 'function).

 - Function: MACROEXPAND-1 (FORM &optional (ENV NIL))
     Package:LISP

     If FORM is a macro form, then expands it once.  Returns two
     values: the expanded form and a T-or-NIL flag indicating whether
     the original form was a macro.

 - Function: FUNCALL (FUNCTION &rest ARGUMENTS)
     Package:LISP

     Applies FUNCTION to the ARGUMENTs

 - Constant: CALL-ARGUMENTS-LIMIT
     Package:LISP The upper exclusive bound on the number of arguments
     that may be passed to a function.  Actually, however, there is no
     such upper bound in GCL.

 - Special Form: CASE
     Package:LISP

     Syntax:
          (case keyform {({key | ({key}*)} {form}*)}*)

     Evaluates KEYFORM and tries to find the KEY that is EQL to the
     value of KEYFORM.  If one is found, then evaluates FORMs that
     follow the KEY and returns the value(s) of the last FORM.  If not,
     simply returns NIL.

 - Macro: DEFINE-SETF-METHOD
     Package:LISP

     Syntax:
          (define-setf-method access-fun defmacro-lambda-list {decl | doc}*
                    {form}*)

     Defines how to SETF a generalized-variable reference of the form
     (ACCESS-FUN ...).  When a form (setf (ACCESS-FUN arg1 ... argn)
     value) is being evaluated, the FORMs are first evaluated as a
     PROGN with the parameters in DEFMACRO-LAMBDA-LIST bound to ARG1
     ... ARGn.  Assuming that the last FORM returns five values
     (temp-var-1 ... temp-var-k) 	(value-from-1 ... value-form-k)
     (store-var) 	storing-form 	access-form in order, the whole
     SETF is then expanded into 	(let* ((temp-var-1 value-from-1) ...
     (temp-k value-form-k) 	       (store-var VALUE))
     storing-from) Incidentally, the five values are called the five
     gangs of a SETF method.  The doc-string DOC, if supplied, is saved
     as a SETF doc and can be retrieved by (documentation 'NAME 'setf).

 - Special Form: COMPILER-LET
     Package:LISP

     Syntax:
          (compiler-let ({var | (var [value])}*) {form}*)

     When interpreted, this form works just like a LET form with all
     VARs declared special.  When compiled, FORMs are processed with
     the VARs bound at compile time, but no bindings occur when the
     compiled code is executed.

 - Function: VALUES (&rest ARGS)
     Package:LISP

     Returns ARGs in order, as values.

 - Special Form: MULTIPLE-VALUE-LIST
     Package:LISP

     Syntax:
          (multiple-value-list form)

     Evaluates FORM, and returns a list of multiple values it returned.

 - Special Form: MULTIPLE-VALUE-PROG1
     Package:LISP

     Syntax:
          (multiple-value-prog1 form {form}*)

     Evaluates the first FORM, saves all the values produced, then
     evaluates the other FORMs.  Returns the saved values.

 - Special Form: MACROLET
     Package:LISP

     Syntax:
          (macrolet ({(name defmacro-lambda-list {decl | doc}* . body)}*)
                    {form}*)

     Evaluates FORMs as a PROGN, with the local macro definitions in
     effect.  See the doc of DEFMACRO for the complete syntax of a
     defmacro-lambda-list.  Doc-strings for local macros are simply
     ignored.

 - Special Form: GO
     Package:LISP

     Syntax:
          (go tag)

     Jumps to the specified TAG established by a lexically surrounding
     TAGBODY.

 - Special Form: PROG
     Package:LISP

     Syntax:
          (prog ({var | (var [init])}*) {decl}* {tag | statement}*)

     Creates a NIL block, binds VARs in parallel, and then executes
     STATEMENTs.

 - Variable: *APPLYHOOK*
     Package:LISP Used to substitute another function for the implicit
     APPLY normally done within EVAL.  If *APPLYHOOK* is not NIL, its
     value must be a function which takes three arguments: a function
     to be applied, a list of arguments, and an environment.  This
     function does the application instead of APPLY.

 - Special Form: RETURN-FROM
     Package:LISP

     Syntax:
          (return-from name [result])

     Returns from the lexically surrounding block whose name is NAME.
     The value of RESULT, which defaults to NIL, is returned as the
     value of the block.

 - Special Form: UNLESS
     Package:LISP

     Syntax:
          (unless test {form}*)

     If TEST evaluates to NIL, then evaluates FORMs as a PROGN.  If not,
     simply returns NIL.

 - Special Form: MULTIPLE-VALUE-SETQ
     Package:LISP

     Syntax:
          (multiple-value-setq variables form)

     Sets each variable in the list VARIABLES to the corresponding
     value of FORM.  Returns the value assigned to the first variable.

 - Special Form: LOCALLY
     Package:LISP

     Syntax:
          (locally {decl}* {form}*)

     Gives local pervasive declarations.

 - Function: IDENTITY (X)
     Package:LISP

     Simply returns X.

 - Function: NOT (X)
     Package:LISP

     Returns T if X is NIL; NIL otherwise.

 - Macro: DEFCONSTANT
     Package:LISP

     Syntax:
          (defconstant name initial-value [doc])

     Declares that the variable NAME is a constant whose value is the
     value of INITIAL-VALUE.  The doc-string DOC, if supplied, is saved
     as a VARIABLE doc and can be retrieved by (documentation 'NAME
     'variable).

 - Function: VALUES-LIST (LIST)
     Package:LISP

     Returns all of the elements of LIST in order, as values.

 - Function: ERROR (CONTROL-STRING &rest ARGS)
     Package:LISP

     Signals a fatal error.

 - Special Form: IF
     Package:LISP

     Syntax:
          (if test then [else])

     If TEST evaluates to non-NIL, then evaluates THEN and returns the
     result.  If not, evaluates ELSE (which defaults to NIL) and
     returns the result.

 - Special Form: UNWIND-PROTECT
     Package:LISP

     Syntax:
          (unwind-protect protected-form {cleanup-form}*)

     Evaluates PROTECTED-FORM and returns whatever it returned.
     Guarantees that CLEANUP-FORMs be always evaluated before exiting
     from the UNWIND-PROTECT form.

 - Function: EVALHOOK (FORM EVALHOOKFN APPLYHOOKFN &optional (ENV NIL))
     Package:LISP

     Evaluates FORM with *EVALHOOK* bound to EVALHOOKFN and *APPLYHOOK*
     bound to APPLYHOOKFN.  Ignores these hooks once, for the top-level
     evaluation of FORM.

 - Special Form: OR
     Package:LISP

     Syntax:
          (or {form}*)

     Evaluates FORMs in order from left to right.  If any FORM
     evaluates to non-NIL, quits and returns that (single) value.  If
     the last FORM is reached, returns whatever values it returns.

 - Macro: CTYPECASE
     Package:LISP

     Syntax:
          (ctypecase keyplace {(type {form}*)}*)

     Evaluates KEYPLACE and tries to find the TYPE in which the value
     of KEYPLACE belongs.  If one is found, then evaluates FORMs that
     follow the KEY and returns the value(s) of the last FORM.  If not,
     signals a correctable error.

 - Function: EVAL (EXP)
     Package:LISP

     Evaluates EXP and returns the result(s).

 - Macro: PSETF
     Package:LISP

     Syntax:
          (psetf {place newvalue}*)

     Similar to SETF, but evaluates all NEWVALUEs first, and then
     replaces the value in each PLACE with the value of the
     corresponding NEWVALUE.  Returns NIL always.

 - Special Form: THROW
     Package:LISP

     Syntax:
          (throw tag result)

     Evaluates TAG and aborts the execution of the most recent CATCH
     form that sets up a catcher with the same tag value.  The CATCH
     form returns whatever RESULT returned.

 - Macro: DEFPARAMETER
     Package:LISP

     Syntax:
          (defparameter name initial-value [doc])

     Declares the variable NAME as a special variable and initializes
     the value.  The doc-string DOC, if supplied, is saved as a
     VARIABLE doc and can be retrieved by (documentation 'NAME
     'variable).

 - Macro: DEFVAR
     Package:LISP

     Syntax:
          (defvar name [initial-value [doc]])

     Declares the variable NAME as a special variable and, optionally,
     initializes it.  The doc-string DOC, if supplied, is saved as a
     VARIABLE doc and can be retrieved by (documentation 'NAME
     'variable).

Compilation
***********

 - Function: COMPILE (NAME &optional (DEFINITION NIL))
     Package:LISP

     If DEFINITION is NIL, NAME must be the name of a not-yet-compiled
     function.  In this case, COMPILE compiles the function, installs
     the compiled function as the global function definition of NAME,
     and returns NAME.  If DEFINITION is non-NIL, it must be a lambda
     expression and NAME must be a symbol.  COMPILE compiles the lambda
     expression, installs the compiled function as the function
     definition of NAME, and returns NAME.  There is only one exception
     for this:  If NAME is NIL, then the compiled function is not
     installed but is simply returned as the value of COMPILE.       In
     any case, COMPILE creates temporary files whose filenames are
     "gazonk***".  By default, i.e. if :LEAVE-GAZONK is not supplied or
     is NIL, these files are automatically deleted after compilation.

 - Special Form: EVAL-WHEN
     Package:LISP

     Syntax:
          (eval-when ({situation}*) {form}*)

     A situation must be either COMPILE, LOAD, or EVAL.  The
     interpreter evaluates only when EVAL is specified.  If COMPILE is
     specified, FORMs are evaluated at compile time.  If LOAD is
     specified, the compiler arranges so that FORMs be evaluated when
     the compiled code is loaded.

 - Function: COMPILE-FILE (INPUT-PATHNAME
     &key output-file (load nil) (message-file nil)        ;GCL
     specific keywords:        system-p c-debug c-file h-file data-file)
     Package:LISP

     Compiles the file specified by INPUT-PATHNAME and generates a fasl
     file specified by OUTPUT-FILE.  If the filetype is not specified
     in INPUT-PATHNAME, then ".lsp" is used as the default file type
     for the source file.  :LOAD specifies whether to load the
     generated fasl file after compilation.  :MESSAGE-FILE specifies
     the log file for the compiler messages.  It defaults to the value
     of the variable COMPILER:*DEFAULT-MESSAGE-FILE*.  A non-NIL value
     of COMPILER::*COMPILE-PRINT* forces the compiler to indicate the
     form currently being compiled.  More keyword parameters are
     accepted, depending on the version.  Most versions of GCL can
     receive :O-FILE, :C-FILE, :H-FILE, and :DATA-FILE keyword
     parameters, with which you can control the intermediate files
     generated by the GCL compiler.  Also :C-DEBUG will pass the -g
     flag to the C compiler.

     By top level forms in a file, we mean the value of
     *top-level-forms* after doing (TF form) for each form read from a
     file.  We define TF as follows:

     (defun TF (x)  (when (consp x)   (setq x (macroexpand x))   (when
     (consp x)      (cond ((member (car x) '(progn  eval-when))
        (mapcar 'tf (cdr x)))            (t  (push x
     *top-level-forms*))))))

     Among the common lisp special forms only DEFUN and DEFMACRO will
     cause actual native machine code to be generated.  The rest will
     be specially treated in an init section of the .data file.  This
     is done so that things like putprop,setq, and many other forms
     would use up space which could not be usefully freed, if we were
     to compile to native machine code.  If you have other `ordinary'
     top level forms which you need to have compiled fully to machine
     code you may either set compiler::*COMPILE-ORDINARIES* to t, or
     put them inside a

     (PROGN 'COMPILE ...forms-which-need-to-be-compiled)

     The compiler will take each of them and make a temporary function
     which will be compiled and invoked once.  It is permissible to
     wrap a (PROGN 'COMPILE ..) around the whole file.  Currently this
     construction binds the compiler::*COMPILE-ORDINARIES* flag to t.
     Setting this flag globally to a non nil value to cause all top
     level forms to generate machine code.  This might be useful in a
     system such as PCL, where a number of top level lambda expressions
     are given.  Note that most common lisps will simply ignore the top
     level atom 'compile, since it has no side effects.

     Defentry, clines, and defcfun also result in machine code being
     generated.

subsection Evaluation at Compile time
*************************************

     In GCL the eval-when behaviour was changed in order to allow more
efficient init code, and also to bring it into line with the resolution
passed by the X3j13 committee.  Evaluation at compile time is
controlled by placing eval-when special forms in the code, or by the
value of the variable compiler::*eval-when-defaults* [default value
:defaults].  If that variable has value :defaults, then the following
hold:

     Eval at Compile       Type of Top Level Form
    Partial:
          defstructs, defvar, defparameter

    Full:
          defmacro, defconstant, defsetf, define-setf-method,
          deftype, package ops, proclaim

    None:
          defun, others

     By `partial' we mean (see the X3J13 Common Lisp document
(doc/compile-file-handling-of-top-level-forms) for more detail), that
functions will not be defined, values will not be set, but other
miscellaneous compiler properties will be set: eg properties to inline
expand defstruct accessors and testers, defstruct properties allowing
subsequent defstructs to include this one, any type hierarch
information, special variable information will be set up.

     Example:
          (defun foo () 3)
          (defstruct jo a b)

     As a side effect of compiling these two forms, foo would not have
its function cell changed.  Neither would jo-a, although it would gain
a property which allows it to expand inline to a structure access.
Thus if it had a previous definition (as commonly happens from
previously loading the file), this previous definition would not be
touched, and could well be inconsistent with the compiler properties.
Unfortunately this is what the CL standard says to do, and I am just
trying to follow it.

     If you prefer a more intuitive scheme, of evaling all forms in the
file, so that there are no inconsistencies, (previous behaviour of
AKCL) you may set compiler::*eval-when-defaults* to '(compile eval
load).

     The variable compiler::*FASD-DATA* [default t] controls whether an
ascii output is used for the data section of the object file.  The data
section will be in ascii if *fasd-data* is nil or if the system-p
keyword is supplied to compile-file and *fasd-data* is not eq to
:system-p.

     The old GCL variable *compile-time-too* has disappeared.

     See OPTIMIZE on how to enable warnings of slow constructs.

 - Function: PROCLAIM (DECL-SPEC)
     Package:LISP

     Puts the declaration given by DECL-SPEC into effect globally.  See
     the doc of DECLARE for possible DECL-SPECs.

 - Function: PROVIDE (MODULE-NAME)
     Package:LISP

     Adds the specified module to the list of modules maintained in
     *MODULES*.

 - Function: COMPILED-FUNCTION-P (X)
     Package:LISP

     Returns T if X is a compiled function; NIL otherwise.

 - Variable: *FEATURES*
     Package:LISP List of symbols that name features of the current
     version of GCL.  These features are used to decide the read-time
     conditionalization facility provided by '#+' and '#-' read macros.
     When the GCL reader encounters
          	#+ feature-description form
     it reads FORM in the usual manner if FEATURE-DESCRIPTION is true.
     Otherwise, the reader just skips FORM.
          	#- feature-description form
     is equivalent to
          	#- (not feature-description) form
     A feature-description may be a symbol, which is true only when it
     is an element of *FEATURES*.  Or else, it must be one of the
     following:
          (and feature-desciption-1 ... feature-desciption-n)
          (or  feature-desciption-1 ... feature-desciption-n)
          (not feature-desciption)
     The AND description is true only when all of its sub-descriptions
     are true.  The OR description is true only when at least one of
     its sub-descriptions is true.  The NOT description is true only
     when its sub-description is false.

Symbols
*******

 - Function: GENSYM (&optional (X NIL))
     Package:LISP

     Creates and returns a new uninterned symbol whose name is a prefix
     string (defaults to "G"), followed by a decimal number.  The
     number is incremented by each call to GENSYM.  X, if an integer,
     resets the counter.  If X is a string, it becomes the new prefix.

 - Function: KEYWORDP (X)
     Package:LISP

     Returns T if X is a symbol and it belongs to the KEYWORD package;
     NIL otherwise.

 - Function: REMPROP (SYMBOL INDICATOR)
     Package:LISP

     Look on property list of SYMBOL for property with specified
     INDICATOR.  If found, splice this indicator and its value out of
     the plist, and return T. If not found, returns NIL with no side
     effects.

 - Function: SYMBOL-PACKAGE (SYMBOL)
     Package:LISP

     Returns the contents of the package cell of the symbol SYMBOL.

 - Variable: *PACKAGE*
     Package:LISP The current package.

 - Function: SHADOWING-IMPORT (SYMBOLS &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Imports SYMBOLS into PACKAGE, disregarding any name conflict.  If
     a symbol of the same name is already present, then it is
     uninterned.  SYMBOLS must be a list of symbols or a symbol.

 - Macro: REMF
     Package:LISP

     Syntax:
          (remf place indicator)

     PLACE may be any place expression acceptable to SETF, and is
     expected to hold a property list or NIL.  This list is
     destructively altered to remove the property specified by
     INDICATOR.  Returns T if such a property was present; NIL
     otherwise.

 - Function: MAKUNBOUND (SYMBOL)
     Package:LISP

     Makes empty the value slot of SYMBOL.  Returns SYMBOL.

 - Function: USE-PACKAGE (PACKAGES-TO-USE &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Adds all packages in PACKAGE-TO-USE list to the use list for
     PACKAGE so that the external symbols of the used packages are
     available as internal symbols in PACKAGE.

 - Function: MAKE-SYMBOL (STRING)
     Package:LISP

     Creates and returns a new uninterned symbol whose print name is
     STRING.

 - Special Form: PSETQ
     Package:LISP

     Syntax:
          (psetq {var form}*)

     Similar to SETQ, but evaluates all FORMs first, and then assigns
     each value to the corresponding VAR.  Returns NIL always.

 - Function: PACKAGE-USED-BY-LIST (PACKAGE)
     Package:LISP

     Returns the list of packages that use PACKAGE.

 - Function: SYMBOLP (X)
     Package:LISP

     Returns T if X is a symbol; NIL otherwise.

 - Constant: NIL
     Package:LISP Holds NIL.

 - Function: SET (SYMBOL VALUE)
     Package:LISP

     Assigns the value of VALUE to the dynamic variable named by
     SYMBOL, and returns the value assigned.

 - Special Form: SETQ
     Package:LISP

     Syntax:
          (setq {var form}*)

     VARs are not evaluated and must be symbols.  Assigns the value of
     the first FORM to the first VAR, then assigns the value of the
     second FORM to the second VAR, and so on.  Returns the last value
     assigned.

 - Function: UNUSE-PACKAGE (PACKAGES-TO-UNUSE &optional (PACKAGE
          *PACKAGE*))
     Package:LISP

     Removes PACKAGES-TO-UNUSE from the use list for PACKAGE.

 - Constant: T
     Package:LISP Holds T.

 - Function: PACKAGE-USE-LIST (PACKAGE)
     Package:LISP

     Returns the list of packages used by PACKAGE.

 - Function: LIST-ALL-PACKAGES ()
     Package:LISP

     Returns a list of all existing packages.

 - Function: COPY-SYMBOL (SYMBOL &optional (COPY-PROPS NIL))
     Package:LISP

     Returns a new uninterned symbol with the same print name as SYMBOL.
     If COPY-PROPS is NIL, the function, the variable, and the property
     slots of the new symbol have no value.  Otherwise, these slots are
     given the values of the corresponding slots of SYMBOL.

 - Function: SYMBOL-PLIST (SYMBOL)
     Package:LISP

     Returns the property list of SYMBOL.

 - Function: SYMBOL-NAME (SYMBOL)
     Package:LISP

     Returns the print name of the symbol SYMBOL.

 - Function: FIND-SYMBOL (NAME &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Returns the symbol named NAME in PACKAGE.  If such a symbol is
     found, then the second value is :INTERN, :EXTERNAL, or :INHERITED
     to indicate how the symbol is accessible.  If no symbol is found
     then both values are NIL.

 - Function: SHADOW (SYMBOLS &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Creates an internal symbol in PACKAGE with the same name as each
     of the specified SYMBOLS.  SYMBOLS must be a list of symbols or a
     symbol.

 - Function: FBOUNDP (SYMBOL)
     Package:LISP

     Returns T if SYMBOL has a global function definition or if SYMBOL
     names a special form or a macro; NIL otherwise.

 - Function: MACRO-FUNCTION (SYMBOL)
     Package:LISP

     If SYMBOL globally names a macro, then returns the expansion
     function.  Returns NIL otherwise.

 - Function: IN-PACKAGE (PACKAGE-NAME &key (NICKNAMES NIL) (USE
          '(LISP)))
     Package:LISP

     Sets *PACKAGE* to the package with PACKAGE-NAME, creating the
     package if it does not exist.  If the package already exists then
     it is modified to agree with USE and NICKNAMES arguments.  Any new
     nicknames are added without removing any old ones not specified.
     If any package in the USE list is not currently used, then it is
     added to the use list.

 - Function: MAKE-PACKAGE (PACKAGE-NAME &key (NICKNAMES NIL) (USE
          '(LISP)))
     Package:LISP

     Makes a new package having the specified PACKAGE-NAME and
     NICKNAMES.  The package will inherit all external symbols from
     each package in the USE list.

 - Function: PACKAGE-SHADOWING-SYMBOLS (PACKAGE)
     Package:LISP

     Returns the list of symbols that have been declared as shadowing
     symbols in PACKAGE.

 - Function: INTERN (NAME &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Returns a symbol having the specified name, creating it if
     necessary.  Returns as the second value one of the symbols
     :INTERNAL, :EXTERNAL, :INHERITED, and NIL.

 - Function: EXPORT (SYMBOLS &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Makes SYMBOLS external symbols of PACKAGE.  SYMBOLS must be a list
     of symbols or a symbol.

 - Function: PACKAGEP (X)
     Package:LISP

     Returns T if X is a package; NIL otherwise.

 - Function: SYMBOL-FUNCTION (SYMBOL)
     Package:LISP

     Returns the current global function definition named by SYMBOL.

 - Function: SYMBOL-VALUE (SYMBOL)
     Package:LISP

     Returns the current value of the dynamic (special) variable named
     by SYMBOL.

 - Function: BOUNDP (SYMBOL)
     Package:LISP

     Returns T if the global variable named by SYMBOL has a value; NIL
     otherwise.

 - Function: DOCUMENTATION (SYMBOL DOC-TYPE)
     Package:LISP

     Returns the doc-string of DOC-TYPE for SYMBOL; NIL if none exists.
     Possible doc-types are: 	FUNCTION  (special forms, macros,
     and functions) 	VARIABLE  (dynamic variables, including constants)
     TYPE      (types defined by DEFTYPE) 	STRUCTURE (structures
     defined by DEFSTRUCT) 	SETF      (SETF methods defined by
     DEFSETF, DEFINE-SETF-METHOD, and 	           DEFINE-MODIFY-MACRO)
     All built-in special forms, macros, functions, and variables have
     their doc-strings.

 - Function: GENTEMP (&optional (PREFIX "T") (PACKAGE *PACKAGE*))
     Package:LISP

     Creates a new symbol interned in the package PACKAGE with the
     given PREFIX.

 - Function: RENAME-PACKAGE (PACKAGE NEW-NAME &optional (NEW-NICKNAMES
          NIL))
     Package:LISP

     Replaces the old name and nicknames of PACKAGE with NEW-NAME and
     NEW-NICKNAMES.

 - Function: UNINTERN (SYMBOL &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Makes SYMBOL no longer present in PACKAGE.  Returns T if SYMBOL
     was present; NIL otherwise.  If PACKAGE is the home package of
     SYMBOL, then makes SYMBOL uninterned.

 - Function: UNEXPORT (SYMBOLS &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Makes SYMBOLS no longer accessible as external symbols in PACKAGE.
     SYMBOLS must be a list of symbols or a symbol.

 - Function: PACKAGE-NICKNAMES (PACKAGE)
     Package:LISP

     Returns as a list the nickname strings for the specified PACKAGE.

 - Function: IMPORT (SYMBOLS &optional (PACKAGE *PACKAGE*))
     Package:LISP

     Makes SYMBOLS internal symbols of PACKAGE.  SYMBOLS must be a list
     of symbols or a symbol.

 - Function: GET (SYMBOL INDICATOR &optional (DEFAULT NIL))
     Package:LISP

     Looks on the property list of SYMBOL for the specified INDICATOR.
     If this is found, returns the associated value.  Otherwise,
     returns DEFAULT.

 - Function: FIND-ALL-SYMBOLS (STRING-OR-SYMBOL)
     Package:LISP

     Returns a list of all symbols that have the specified name.

 - Function: FMAKUNBOUND (SYMBOL)
     Package:LISP

     Discards the global function definition named by SYMBOL.  Returns
     SYMBOL.

 - Function: PACKAGE-NAME (PACKAGE)
     Package:LISP

     Returns the string that names the specified PACKAGE.

 - Function: FIND-PACKAGE (NAME)
     Package:LISP

     Returns the specified package if it already exists; NIL otherwise.
     NAME may be a string that is the name or nickname of the package.
     NAME may also be a symbol, in which case the symbol's print name
     is used.

 - Function: APROPOS-LIST (STRING &optional (PACKAGE NIL))
     Package:LISP

     Returns, as a list, all symbols whose print-names contain STRING
     as substring.  If PACKAGE is non-NIL, then only the specified
     package is searched.

Operating System
****************

Command Line
============

   The variable si::*command-args* is set to the list of strings passed
in when gcl is invoked.

   Various flags are understood.
`-eval'
     Call read and then eval on the command argument following `-eval'

`-load'
     Load the file whose pathname is specified after `-load'.

`-f'
     Replace si::*command-args* by the the list starting after `-f'.
     Open the file following `-f' for input, skip the first line, and
     then read and eval the rest of the forms in the file.   This can
     be used as with the shells to write small shell programs:
          #!/usr/local/bin/gcl.exe -f
          (format t "hello world ~a~%" (nth 1 si::*command-args*))
     The value si::*command-args* will have the appropriate value.
     Thus if the above 2 line file is made executable and called `foo'
     then
          tutorial% foo billy
          hello world billy

     NOTE:  On many systems (eg SunOs) the first line of an executable
     script file such as:
          #!/usr/local/bin/gcl.exe -f
     only reads the first 32 characters!   So if your pathname where
     the executable together with the '-f' amount to more than 32
     characters the file will not be recognized.   Also the executable
     must be the actual large binary file, [or a link to it], and not
     just a `/bin/sh' script.   In latter case the `/bin/sh'
     interpreter would get invoked on the file.

     Alternately one could invoke the file `foo' without making it
     executable:
          tutorial% gcl -f foo "from bill"
          hello world from bill

`-batch'
     Do not enter the command print loop.  Useful if the other command
     line arguments do something.  Do not print the License and
     acknowledgement information.  Note if your program does print any
     License information, it must print the GCL header information also.

`-dir'
     Directory where the executable binary that is running is located.
     Needed by save and friends.  This gets set as
     si::*system-directory*

`-libdir'
             -libdir `/d/wfs/gcl-2.0/'
     would mean that the files like gcl-tk/tk.o would be found by
     concatting the path to the libdir path, ie in
          `/d/wfs/gcl-2.0/gcl-tk/tk.o'

`-compile'
     Invoke the compiler on the filename following `-compile'.  Other
     flags affect compilation.

`-o-file'
     If nil follows `-o-file' then do not produce an `.o' file.

`-c-file'
     If `-c-file' is specified, leave the intermediate `.c' file there.

`-h-file'
     If `-h-file' is specified, leave the intermediate `.h' file there.

`-data-file'
     If `-data-file' is specified, leave the intermediate `.data' file
     there.

`-system-p'
     If `-system-p' is specified then invoke `compile-file' with the
     `:system-p t' keyword argument, meaning that the C init function
     will bear a name based on the name of the file, so that it may be
     invoked by name by C code.