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

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

 -- 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).