REF CONTROL                               Titch Le Bek, Rob Duncan, 1986

       COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<   LISP CONTROL PROCEDURES   >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file  briefly  describes  the functions,  variables  and  constants
documented in Chapter  7 of the  standard Common Lisp  guide, which  is:
Common Lisp: The Language (Guy L. Steele, Digital Press, 1984).


-------------------------------------------------
1  A Listing of Functions Variables and Constants
-------------------------------------------------

(apply fn arg &rest args)                                     [function]
        Returns the  result of  applying  fn to  the list  of  arguments
        (arg . args). fn may be  a symbol, function  object, or list  of
        the form (setf symbol).


call-arguments-limit                                          [constant]
        The upper exclusive bound on the number of arguments that may be
        passed to a function. Value in this implementation: 536870912.


(block name {form}*)                                      [special-form]
        Executes forms from left  to right returning  the result of  the
        last form evaluated as the value of the block named.


(boundp symbol)                                               [function]
        True if the dynamic  variable named by symbol  has a value;  nil
        otherwise.


(case keyform {({({key}*) | key} {form}*)}*)                     [macro]
        case is  similar  to  cond  in selecting  one  clause  and  then
        executing all its consequents. It  differs in its mechanism  for
        clause  selection:  the  keyform   is  evaluated  to   produce a
        key-object. If the key-object  is eql to one  of the given  keys
        then the  {form}*  of  the  clause in  which  the  matching  key
        occurred are evaluated, and  the value of the  last form is  the
        value of the whole case construct. The keys are not evaluated so
        must all be  literals and  no key can  appear in  more than  one
        clause. The symbols  t and  otherwise can  be used  in the  last
        clause of the case in place of a list of keys; that clause  will
        then match any key-object not  matched by a previous clause.  If
        no clause matches the key-object, case returns nil.


(catch tag {form}*)                                       [special-form]
        The {form}* are evaluated as an implicit progn. If the catch tag
        is matched by a throw tag  during the execution of {form}*  then
        the evaluation of  {form}* is  aborted and  the multiple  values
        resulting from  the throw  are  returned as  the result  of  the
        catch. Otherwise  the results  of the  last form  are  returned.
        catch tags are  compared with EQ,  so should not  be numbers  or
        characters.


(cond {(test {form}*)}*)                                         [macro]
        cond has a  number of  clauses which  are lists  of forms.  Each
        clause consists of a test followed by zero or more  consequents.
        The first  test  that  evaluates to  non-nil  is  selected,  its
        consequents are evaluated  and the  result of the  last form  is
        returned. All other  clauses are  ignored. If cond  runs out  of
        clauses it returns the value nil.


(define-modify-macro name lambda-list function [doc-string])     [macro]
        Defines a  read-modify-write  macro  called  name.  function  is
        applied to the old contents of a generalized variable (the first
        subform of  the  macro) to  get  the new  contents.  lambda-list
        describes the remaining arguments  for the function.  doc-string
        is documentation for the  macro name being  defined. incf is  an
        example of such a macro.


(define-setf-method function lambda-list                         [macro]
                    {declaration | doc-string}* {form}*)
        define-setf-method defines how  to setf  a generalized  variable
        reference that  is obtained  by  evaluating its  name  function.
        lambda-list describes the  subforms of function.  The result  of
        evaluating {form}*  is the  five  values representing  the  setf
        method.


(defsetf access-fn update-fn [doc-string])                       [macro]
(defsetf access-fn lambda-list
            ({var}*)
            {declaration | doc-string}* {form}*)
        defsetf defines  how to  setf a  generalized variable  which  is
        obtained  by  evaluating  the   function  or  macro   access-fn.
        update-fn names a  function that  takes one  more argument  than
        access-fn. When  setf  is  given  a place  that  is  a  call  on
        access-fn it expands into a call on update-fn that is given  all
        the arguments to access-fn and  also the new value.  lambda-list
        describes the arguments of access-fn. var describes the value to
        be stored  into  the  generalized variable  reference  which  is
        returned by setf.


(do ({(var [init [step]])}*)                                     [macro]
    (end-test {result-form}*)
    {declaration}*
    {tag | statement}*)
        do provides a generalized  iteration facility with an  arbitrary
        number of "index variables"  each of which  may have an  initial
        value init and a stepping form step. Before the first iteration,
        all the initial vars are bound in parallel to their init values;
        before subsequent  iterations,  the  vars  are  assigned  to  in
        parallel with their  step values  (vars without  steps are  left
        unchanged). Each iteration proceeds  by evaluating end-test;  if
        this is  nil,  execution continues  with  the body  of  the  do,
        otherwise {result-form}* is evaluated and the result of the last
        form is returned as the result of the whole do construct.


(do* ({(var [init [step]])}*)                                    [macro]
     (end-test {result-form}*)
     {declaration}*
     {tag | statement}*)
        do* is exactly like do except that the initial bindings of  vars
        to init values and the updating  of vars with their step  values
        is done sequentially  rather than in  parallel. This means  that
        the init or step form for a  variable var-j can make use of  the
        new value of any variable var-i which precedes it in the list of
        index variables.


(dolist (var list [form]) {declaration}* {tag | statement}*)     [macro]
        dolist provides straightforward iteration  over the elements  of
        the evaluated  form list.  The body  is executed  once for  each
        element of the list with the variable var bound to it, then form
        is evaluated and the result is the value of dolist. var is bound
        in form to nil.


(dotimes (var count [form]) {declaration}* {tag | statement}*)   [macro]
        dotimes provides straightforward  iteration over  a sequence  of
        integers. count must be  a form which  evaluates to an  integer;
        the body of the loop is evaluated exactly once for each  integer
        from 0 (inclusive) to  count (exclusive) with  var bound to  the
        integer, then form is evaluated and  the result is the value  of
        dotimes. var is bound  in form to the  number of times the  loop
        body was executed.


(fboundp fname)                                               [function]
        If fname is a symbol, returns  true if that symbol has a  global
        function  definition.  If   fname  is   a  list   of  the   form
        (setf symbol), returns true  if a setf  method has been  defined
        for symbol. In either case returns nil if fname is undefined.


(fdefinition fname)                                           [function]
        Returns the global  function definition of  fname, which may  be
        either a symbol or list of  the form (setf symbol). An error  is
        signaled if fname is not defined.


(flet ({(name lambda-list [decs-and-doc] body)}*)         [special-form]
    {declaration}*
    {form}*)
        Establishes local function definitions  for each name, and  then
        executes {form}*, returning  the value  of the  last form.  Each
        local  function  definition  is  similar  in  form  to  a  defun
        statement.

        The scope of the local  function bindings is just {form}*.  Thus
        flet cannot be used to define recursive (or mutually  recursive)
        local functions. (For this, use labels).


(fmakunbound fname)                                           [function]
        Removes the global function  definition of fname. Returns  fname
        as the result value. fname may be a symbol or a list of the form
        (setf symbol).


(funcall fn &rest args)                                       [function]
        Returns the result of  fn applied to args.  fn may be a  symbol,
        function object, or list of the form (setf symbol).


(function fn)                                             [special-form]
        Returns the function object denoted by fn in the current lexical
        environment. fn may be a  symbol, lambda expression, or list  of
        the  form  (setf symbol).   The  form  (function   fn)  may   be
        abbreviated to #'fn.


(get-setf-method form &optional env)                          [function]
        Returns five values constituting the  setf method for form.  env
        specifies the lexical environment. It defaults to nil (the  null
        lexical environment).


(get-setf-method-multiple-value form &optional env)           [function]
        Returns five values constituting the setf method for form.  This
        is the same as get-setf-method except that it does not check the
        number of  store  variables. It  is  used in  cases  that  allow
        storing multiple into a generalized variable.


(go tag)                                                  [special-form]
        Used to do a "go to" within a tagbody construct. The tag must be
        a symbol  or  an integer;  it  is not  evaluated.  go  transfers
        control to the point in  the body labelled by  a tag eql to  the
        one given. An error is signaled if no such tag can be found.  go
        does not return a value.


(if test then [else])                                     [special-form]
        Corresponds to the "if-then-else"  construct of most  languages.
        test is evaluated. If the result  is non nil then the form  then
        is selected,otherwise the  form else  is selected.  else may  be
        ommited, in which case if returns nil if test is nil.


(labels ({(name lambda-list [decs-and-doc] body)}*)       [special-form]
    {declaration}*
    {form}*)
        Establishes local function definitions  for each name, and  then
        executes {form}*, returning  the value  of the  last form.  Each
        local  function  definition  is  similar  in  form  to  a  defun
        statement.

        labels, unlike flet, can be used to define recursive or mutually
        recursive local functions. This is because the scope of the  new
        function bindings encompasses  not only {form}*  but also  their
        definitions.


(let ({var | (var [value])}*)                             [special-form]
    {declaration}*
    {form}*)
        Used to execute a series of forms with specified variables bound
        to specified  values. The  variable  bindings are  performed  in
        parallel. The bindings are  lexical with indefinite extent.  let
        evaluates all the {form}* returning the result of the last form.


(let* ({var | (var [value])}*)                            [special-form]
    {declaration}*
    {form}*)
        let* is  similar  to  let  but the  bindings  of  variables  are
        performed sequentially.  This allows  value  forms to  refer  to
        variables previously bound in the let* form.


(loop {form}*)                                                   [macro]
        See REF * LOOP.


(loop-finish)                                                    [macro]
        Causes control to be returned  from a loop. Only legal  inside a
        loop form.


(macrolet ({(name lambda-list [decs-and-doc] body)}*)     [special-form]
    {declaration}*
    {form}*)
        Similar to flet: establishes  local macro definitions which  are
        valid within the lexical  scope of the  main body {form}*.  Each
        local  macro  definition  is  similar  in  form  to  a  defmacro
        statement.


(makunbound symbol)                                           [function]
        makunbound causes the dynamic variable symbol to become  unbound
        (have no value).


(mapc function list &rest lists)                              [function]
        mapc works like mapcar  but does not  accumulate the results  of
        the calling function:  it is  used for its  side effects  rather
        than its returned values. Returns list.


(mapcan function list &rest lists)                            [function]
        mapcan is like  mapcar except  that it combines  the results  of
        function using nconc  instead of  list. This  allows the  mapped
        function to return a variable number of items to be put into the
        output list.


(mapcar function list &rest lists)                            [function]
        mapcar operates  on successive  elements  of lists.  It  applies
        function first to the car of each list, then to the cadr and  so
        on; function must take as many  arguments as there are lists  in
        lists. It terminates as soon  as the shortest argument list  has
        been exhausted,  and  returns  a  list of  the  results  of  the
        successive function calls.


(mapcon function list &rest lists)                            [function]
        mapcon is like maplist  except that it  combines the results  of
        function using nconc  instead of  list. It  allows the  mapped
        function to return a variable number of items to be put into the
        output list.


(mapl function list &rest lists)                              [function]
        mapl is like maplist but does not accumulate the results of  the
        calling function: it is used  when the function is being  called
        for its side  effects rather than  its returned values.  Returns
        list.


(maplist function list &rest lists)                           [function]
        maplist is like mapcar except that function is first applied  to
        the complete lists and successive cdr's of the lists rather than
        successive elements.


(multiple-value-bind ({var}*) {values-form}*                     [macro]
                     {declaration}*
                     {form}*)
        Each  var  is  bound  to   the  respective  value  returned   by
        values-form. The {form}* are  executed with the bound  variables
        and the results are returned.


(multiple-value-call function {form}*)                    [special-form]
        function is  evaluated to  obtain a  function and  then all  the
        forms are evaluated and  their results (which  may be more  than
        one for each) are saved. The  result is whatever is returned  by
        applying function to all of the results.


(multiple-value-list form)                                       [macro]
        multiple-value-list evaluates  form and  returns a  list of  the
        multiple values it returned. It is the inverse of values-list.


(multiple-value-prog1 form {form}*)                       [special-form]
        Evaluates the first form and saves all the values produced.  The
        other forms  are  evaluated  and their  results  discarded.  The
        values of the first form are returned.


(multiple-value-setq ({var}*) form)                              [macro]
        form is evaluated  and the variables  of {var}* are  set to  the
        values returned. nil is assigned to variables without values and
        if there are more values than variables they are discarded.  The
        first value returned by form is  returned. This is nil if  there
        are zero values.


multiple-values-limit                                         [constant]
        The upper exclusive bound  on the number of  values that may  be
        returned  from  a  function.   Value  in  this   implementation:
        536870912.


(nth-value n form)                                               [macro]
        Returns the n'th value  produced by evaulating  form. n is  also
        evaluated.


(prog ({var | (var                                               [macro]
      {declaration}*
      {tag | statement}*)
        prog is a synthesis of let, block, and tagbody. It allows  bound
        variables and the  use of return  and go. The  variable list  is
        processed exactly as the list in a let statement. The prog  body
        is executed as a tagbody construct.  go may be used to  transfer
        control to  a  tag. return  may  be used  to  exit from  a  prog
        construct.


(prog* ({var | (var [init])}*)                                   [macro]
       {declaration}*
       {tag |  statement}*)
        prog*  is  the  same  as  prog  except  that  the  binding   and
        initialization of the temporary variables is sequential so  that
        the init form for each one can use the values of previous ones.


(prog1 {form}*)                                                  [macro]
        prog1 is similar to progn but it returns the value of the  first
        form after  evaluating the  others. It  is used  to evaluate  an
        expression with side  effects and  return a value  that must  be
        computed before the side effects happen.


(prog2 {form}*)                                                  [macro]
        prog2 is similar to prog1 but it returns the value of its second
        form.


(progn {form}*)                                           [special-form]
        Evaluates the  forms sequentially  discarding all  their  values
        except that of the last form whose value(s) are returned.


(progv {var}* {values}* {form}*)                          [special-form]
        Allows  binding  of  dynamic   variables  whose  names  may   be
        determined at run time. The sequence of forms is evaluated  with
        the dynamic  variables named  in {var}*  bound to  corresponding
        values in {values}*. The results are  those of the last form  in
        {form}*. The bindings  of the  dynamic variables  are undone  on
        exit from the progv form.


(psetf {place value}*)                                           [macro]
        psetf is like setf except that if there is more than one  <place
        value> pair the assignments are  done in parallel. psetf  always
        returns nil.


(psetq {var form}*)                                              [macro]
        psetq is like  setq except the  assignments happen in  parallel.
        All the forms  are evaluated and  the variables are  set to  the
        resulting values. The value of psetq is nil.


(quote object)                                            [special-form]
        object may be any Lisp object. quote ensures that object is  not
        evaluated. object is written as a constant value in the program.


(return [result])                                                [macro]
        return is  identical to  (return-from  nil). It  returns  from a
        block named  nil.  Blocks  estalished  implicitly  by  iteration
        constructs such as do  are named nil, so  that return will  exit
        properly.


(return-from name [form])                                 [special-form]
        return-from is  used  to  return  from  a  block.  name  is  not
        evaluated and must be a symbol. A block construct with the  same
        name must  lexically  enclose  the  occurrance  of  return-from.
        Whatever  the  evaluation  of  result  produces  is  immediately
        returned from the block.


(rotatef {place}*)                                               [macro]
        place is a generalized variable  acceptable to setf. The  values
        in place1  through  placen  are  accessed  and  saved.  Values 2
        through n and value 1 are then stored into place1 through placen
        : It is as if all  the places form an end-around shift  register
        that is rotated one place to  the left with the value of  place1
        being shifted around the end to placen.


(set symbol value)                                            [function]
        Returns the dynamic variable symbol with value as its value.


(setf {place value}*)                                            [macro]
        place evaluates  to an  access function.  setf expands  into  an
        update form that stores the result of evaluating the form  value
        into the place referred to by the access-form. If there is  more
        than one place value pair they are processed sequentially.


(setq {var form}*)                                        [special-form]
        setq is the "simple variable assignment statement" of Lisp.  Its
        arguments are in variable value pairs. Corresponding values  are
        assigned sequentially so later  forms may use earlier  evaluated
        variable values. setq may be used for assignment of both lexical
        and special variables.


(shiftf {place}+ value)                                          [macro]
        Each place is any form  acceptable as a generalized variable  to
        setf. The values in  place1 through to  placen are accessed  and
        saved. value is evaluated  for a total  of n+1 values.  Values 2
        through n+1 are stored into place1 through placen and the  value
        of place1 is returned.


(special-form-p symbol)                                       [function]
        Returns a  non-nil  value  if  symbol is  a  special  form,  and
        otherwise nil.


(symbol-function symbol)                                      [function]
        Returns the current global function definition named by symbol.


(symbol-macrolet ({(var expansion)}*)                     [special-form]
                 {declaration}*
                 {form}*)
        For defining symbol  macros. During the  processing of  {form}*,
        each occurence of a var is replaced by the associated expansion.


(symbol-value symbol)                                         [function]
        Returns the  current  value of  the  dynamic variable  named  by
        symbol.


(tagbody {tag | form}*)                                   [special-form]
        Each element of the body is processed from left to right. A  tag
        is ignored; a form  is evaluated and  its results discarded.  If
        the end of  the body  is reached  the tagbody  returns nil.  The
        scope of the  tag is lexical  and the extent  is dynamic. It  is
        permissible for  a go  to jump  to  a tagbody  that is  not  the
        innermost tagbody construct containing that go.


(throw tag result-form)                                   [special-form]
        The  throw  tag   is  evaluated.  The   results  of   evaluating
        result-form are saved.  If the  throw tag matches  the tag  of a
        catch  then  control  is  transferred  to  the  matching   catch
        construct whose value(s) are those of result-form


(typecase keyform {(type {form}*)}*)                             [macro]
          (typecase keyform
            (type-1 consequent-1-1 consequent-1-2 ...)
            (type-2 consequent-2-1 consequent-2-2 ...)
            (...)
        Structurally typecase is similar to cond and case. It  evaluates
        keyform to  produce a  key-object. typecase  selects the  clause
        whose type matches  key-object. The consequents  of that  clause
        are evaluated and the value of the last form returned.  typecase
        returns nil  if  no  clause  is satisfied.  It  may  contain  an
        explicit t or Otherwise default clause.


(unless test {form}*)                                            [macro]
        unless first  evaluates  test. If  the  result is  not  nil  the
        {form}* is not  evaluated, and  nil is  returned. Otherwise  the
        forms are evaluated sequentially and  the value of the last  one
        is returned.


(unwind-protect form {form}*)                             [special-form]
        Guarantees to  execute {form}*  after evaluating  form, even  if
        form terminates abnormally  (by a throw,  for example).  Returns
        whatever results from  form and  discards all  the results  from
        {form}*.


(values &rest args)                                           [function]
        All of the args are returned in order as values. The  expression
        (values) is the standard idiom for returning zero values  from a
        function.


(values-list list)                                            [function]
        All of the elements of list are returned as multiple values.


(when test {form}*)                                              [macro]
        when first evaluates test. If the result is nil then {form}*  is
        not evaluated  and nil  is returned.  Otherwise the  {form}*  is
        evaluated  sequentially  and  the  value  of  the  last  one  is
        returned.



--- C.all/lisp/ref/control
--- Copyright University of Sussex 1993. All rights reserved.
