   This is Edition 1.2, last updated 8 September 2000, of `The librep
Manual', for librep, Version 0.13.

   Copyright 1999-2000 John Harper.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Local Variables
---------------

   A "local variable" is a variable which has a temporary value. For
example, when a function is called the variables which are the names of
its arguments are temporarily bound to the values of the arguments
passed to the function. When the function call exits its arguments are
unbound and the previous definitions of the variables come back into
view.

   A "binding" is a particular instance of a local variable. Even if a
variable has more than one binding currently in place, only the most
recent is available--there is no way the previous binding can be
accessed until the previous binding is removed.

   One way of visualising variable binding is to think of each variable
as a stack. When the variable is bound to, a new value is pushed onto
the stack, when it is unbound the top of the stack is popped. Similarly
when the stack is empty the value of the variable is void (see Void Variables).
Assigning a value to the variable (see Setting Variables)
overwrites the top value on the stack with a new value.
When the value of the variable is required it is simply read from the
top of the stack.

   Apart from function applications there are two special forms which
perform variable binding (i.e. creating local variables), `let' and
`let*'.

 - Macro: let bindings body-forms...
     `let' creates new variable bindings as specified by the BINDINGS
     argument, then evaluates the BODY-FORMS in order.  The bindings
     are then removed, returning all variables to their state before
     the `let' statement was entered. The value of the statement is the
     value of the implicit `progn'.

     The BINDINGS argument is a list of the bindings to perform. Each
     binding is either a symbol, in which case that variable is bound to
     `()', or a list whose car is a symbol. The cdr of this list is a
     list of forms which, when evaluated as a `progn', gives the value
     to bind to that variable.

          (setq foo 42)
              => 42
          (let
              ((foo (+ 1 2))
               bar)
            ;; Body forms
            (setq foo (1+ foo))   ;This sets the new binding
            (cons foo bar))
              => (4 . ())
          foo
              => 42        ;The original values is back

     No bindings are made until all new values have been computed. For
     example:

          (setq foo 42)
              => 42
          (let
              ((foo 100)
               (bar foo))
            (cons foo bar))
              => (100 . 42)

     Although `foo' is given a new binding this is not actually done
     until all the new values have been computed, hence `bar' is bound
     to the _old_ value of `foo'.

 - Macro: let* bindings body-forms...
     This special form is exactly the same as `let' except for one
     important difference: the new bindings are installed _as they are
     computed_.

     You can see the difference by comparing the following example with
     the last example in the `let' documentation (above),

          (setq foo 42)
              => 42
          (let*                   ;Using `let*' this time
              ((foo 100)
               (bar foo))
            (cons foo bar))
              => (100 . 100)

     By the time the new value of `bar' is computed the new binding of
     `foo' is already active.

 - Macro: letrec bindings body-forms...
     `letrec' is similar to `let' and `let*', with the differerence
     being that the values of bindings are evaluated with all other
     bindings in scope. This means that recursive functions may be
     defined with `letrec'. For example, a local factorial function
     (from SICP):

          (letrec ((fact
                    (lambda (n)
                      (if (= n 1)
                          1
                        (* n (fact (1- n)))))))
            (fact 10))

     Note also that letrec allows groups of mutually recursive
     functions to be defined, as in the following example (also from
     SICP):

          (defun f (x)
            (letrec ((evenp
                      (lambda (n)
                        (if (= n 0)
                            t
                          (oddp (1- n)))))
                     (oddp
                      (lambda (n)
                        (if (= n 0)
                            nil
                          (evenp (1- n))))))
              ...

Setting Variables
-----------------

   "Setting" a variable means to overwrite its current value (that is,
the value of its most recent active binding) with a new one. In the
variable-as-stack analogy, this is analogous to overwriting the top of
the stack. The old value is irretrievably lost (unlike when a new value
is bound to a variable, see Local Variables).

   The `setq' special form is the usual method of altering the value of
a variable.

 - Special Form: setq variable form ...
     Each VARIABLE is set to the result of evaluating its corresponding
     FORM. The last value assigned becomes the value of the `setq' form.

          (setq x 20 y (+ 2 3))
              => 5

     In the above example the variable `x' is set to `20' and `y' is
     set to the value of the form `(+ 2 3)' (5).

 - Function: set variable new-value
     The value of the variable VARIABLE (a symbol) is set to NEW-VALUE
     and the NEW-VALUE is returned.

     This function is used when the VARIABLE is unknown until run-time,
     and therefore has to be computed from a form.

          (set 'foo 20)
          ==
          (setq foo 20)           ;`setq' means `set-quoted'
              => 20

     _Note:_ currently the `set' function may be used to set any type
     of variable (i.e. lexical or special). However this likely to
     change in the future, such that only special variables will be
     allowed to be modified using the `set' function. It is strongly
     advised to avoid using this function on lexical bindings!
     (Moreover the compiler may generate incorrect code in certain
     circumstances.)

Scope and Extent
----------------

   In the `librep' dialect of Lisp by default variables have "lexical
scope". This means that bindings are associated with textual regions of
programs, and may be accessed by any forms within this associated
textual region. Moreover, the bindings are persistent, even when the
flow of control is currently outside the associated region.

   Consider the following example:

     (let
         ((counter 0))
       (defun count ()
         (setq counter (1+ counter))
         counter))

the value of the `counter' variable persists, and is incremented each
time the `count' function is called. The `counter' variable is
accessible from nowhere but the forms written inside the `let'
statement declaring it.

     (count)
       => 1
     (count)
       => 2

   An alternative method of scoping variables is also available. Any
variables declared using the `defvar' special form are said to be
"special" variables, they have "indefinite scope" and "dynamic extent",
often simplified to "dynamic scope". What this means is that references
to these variables may occur anywhere in a program (i.e. bindings
established in one function are visible within functions called from
the original function) and that references may occur at any point in
time between the binding being created and it being unbound.

   Dynamic scoping is easy to abuse, making programs hard to understand
and debug. A quick example of the use of dynamic scope,

     (defvar *foo-var* nil)

     (defun foo (x)
       (let
           ;; a dynamically-scoped binding
           ((*foo-var* (* x 20)))
         (bar x)
         ...

     (defun bar (y)
       ;; Since this function is called from
       ;; the function `foo' it can refer
       ;; to `*foo-var*'
       (setq y (+ y *foo-var*))
       ...

As shown in the previous example, a common convention is to mark
special variables by enclosing their names within asterisks.

Void Variables
--------------

   A variable which has no value is said to be "void", attempting to
reference the value of such a symbol will result in an error. It is
possible for the most recent binding of a variable to be void even
though the inactive bindings may have values.

 - Function: boundp variable
     Returns true if the symbol VARIABLE has a value.

 - Function: makunbound variable
     This function makes the current binding of the symbol VARIABLE be
     void, then returns VARIABLE.

          (setq foo 42)
              => 42
          foo
              => 42
          (boundp 'foo)
              => t
          (makunbound 'foo)
              => foo
          (boundp 'foo)
              => ()
          foo
              error--> Value as variable is void: foo

Defining Variables
------------------

   The special forms `define', `defvar' and `defconst' allow you to
define the global variables that will be used by a program.

 - Macro: define variable form
     Defines a lexically scoped global variable called VARIABLE. It
     will have the result of evaluating FORM assigned to it.

     Note that the `define' special form may also be used to declare
     block-structured functions, see Definitions.

 - Special Form: defvar variable [form [doc-string]]
     This special form defines a special (i.e. dynamically scoped)
     variable, the symbol VARIABLE. If the value of VARIABLE is void the
     FORM is evaluated and its value is stored as the value of VARIABLE
     (note that only the default value is modified, never a
     buffer-local value). If no FORM is given the assigned value
     defaults to false.

     If the DOC-STRING argument is defined it is a string documenting
     VARIABLE. This string is then stored as the symbol's
     `variable-documentation' property and can be accessed by the
     `describe-variable' function.

          (defvar *my-variable* '(x y)
            "This variable is an example showing the usage of the `defvar'
          special form.")
              => *my-variable*

 - Macro: defconst constant form [doc-string]
     `defconst' defines a global constant, the symbol CONSTANT.  Its
     value is set to the result of evaluating FORM. Note that unlike
     `defvar' the value of the symbol is _always_ set, even if it
     already has a value.

     The DOC-STRING argument, if defined, is the documentation string
     for the constant.

          (defconst the-answer 42
            "An example constant.")
              => the-answer

Fluid Variables
---------------

   Special variables have a number of drawbacks, especially when used in
conjunction with the module system (see Modules and Special Variables).
As a consequence of these drawbacks, `rep' provides a
second method of implementing dynamically scoped variables, known as
"fluid variables", or just "fluids".

   A fluid is a first class Lisp object that may be passed around like
any other Lisp object. Its sole function is to provide a location from
which dynamic bindings may be created. Fluids are anonymous objects,
they are usually named by being stored in lexically scoped variables.

 - Function: make-fluid #!optional value
     Create and return a new fluid, it will have an initial binding of
     VALUE (or false if VALUE is undefined).

 - Function: fluid fluid
     Return the value of the most recently created binding of the fluid
     variable object FLUID.

 - Function: fluid-set fluid value
     Set the value of the most recently created binding of the fluid
     variable object FLUID to VALUE.

 - Function: with-fluids fluids values thunk
     Call the zero parameter function THUNK (and return the value that
     it returns) with new bindings created for each of the fluid
     variables specified in the list FLUIDS.

     For each member of FLUIDS the corresponding member of the VALUES
     list provides the initial value of the new binding.

     If the lists FLUIDS and VALUES are not of the same length, an
     error is signalled.

 - Macro: let-fluids bindings body ...
     A convenient wrapper around `with-fluids', similar to the `let'
     syntax.

     The list BINDINGS associates the names of lexical variables
     containing fluid objects, with the values to bind to those fluid
     objects. Once the bindings have been installed, the BODY ...
     forms are evaluated, and the bindings removed. The value of the
     last of the BODY ... forms is returned.

   Here is an example code fragment using fluid variables and
`let-fluids':

     (define a (make-fluid))
     (define b (make-fluid))

     (let-fluids ((a 1)
                  (b 2))
       (+ (fluid a) (fluid b))) => 3

Functions
=========

   A "function" is a Lisp object which, when applied to a sequence of
argument values, produces another value--the function's "result". It
may also induce side-effects (e.g. changing the environment of the
calling function). All Lisp functions return results -- there is
nothing like a procedure in Pascal.

   Note that special forms (see Special Forms) and macros (see
Macros) are _not_ functions since they do not guarantee to evaluate
all of their arguments.

   Functions are the main building-block in Lisp programs, each program
is usually a system of interrelated functions.

   There are two types of function: "primitive functions" are functions
written in the C language, these are sometimes called built-in
functions, the object containing the C code itself is called a "subr".
All other functions are defined in Lisp.

 - Function: functionp object
     Returns true if OBJECT is a function (i.e. it can be used as the
     function argument of `funcall'.

          (functionp set)
              => t

          (functionp setq)
              => ()

          (functionp (lambda (x) (+ x 2)))
             => t

 - Function: subrp arg
     Returns true is ARG is a primitive subroutine object.

 - Function: subr-name subr
     Returns a string naming the primitive subroutine SUBR.

Lambda Expressions
------------------

   "Lambda expressions" are used to create functions from other Lisp
objects. A lambda expression is a list whose first element is the
symbol `lambda'. All functions written in Lisp (as opposed to the
primitive functions in C) are defined using lambda expressions.

   The general format of a lambda expression is:

     (lambda LAMBDA-LIST [DOC] [INTERACTIVE-DECLARATION] BODY-FORMS... )

Where LAMBDA-LIST is a list defining the formal parameters of the
function, DOC is an optional documentation string,
INTERACTIVE-DECLARATION is only required by interactive commands (1)
and BODY-FORMS is the sequence of forms making up the function body,
evaluated using an implicit `progn'.

   The LAMBDA-LIST is a list, it defines how the values applied to the
function are bound to local variables which represent the parameters of
the function. At its simplest it is simply a list of symbols, each
symbol will have the corresponding argument value bound to it. For
example, the lambda list `(x y)' defines two parameters, `x' and `y'.
When called with two arguments the first will be bound to the variable
`x', the second to `y'.  When used in a full lambda expression this
looks like:

     (lambda (x y) (+ x y))

this evaluates to an anonymous function with two parameters, `x' and
`y', which when called evaluates to their sum.

   Note that a lambda expression itself is _not_ a function, it must be
associated with a lexical environment, this conjunction is usually
called a closure; it is the closure that may be called as a function.

   However, to confuse matters, a lambda expression _evaluates_ to the
closure of itself and the current environment. Consider the following
example:

     (lambda (x) (1+ x))
         => #<closure>

     (functionp (lambda (x) (1+ x)))
         => t

     (functionp '(lambda (x) (1+ x)))
         => ()

   There are several "lambda-list keywords" which modify the meaning of
symbols in the lambda-list. The syntax of the lambda list is:

     ([REQUIRED-PARAMETERS...]
      [#!optional OPTIONAL-PARAMETERS...]
      [#!key KEYWORD-PARAMETERS...]
      [#!rest REST-PARAMETER | . REST-PARAMETER])

Each lambda list keyword is a symbol whose name begins `#!', they are
interpreted as follows:

`#!optional'
     All variables following this keyword are considered "optional" (all
     variables before the first keyword are "required": an error will be
     signalled if a required argument is undefined in a function call).

     OPTIONAL-PARAMETERS may either be of the form `SYMBOL' or of the
     form `(SYMBOL DEFAULT)'. If no argument is supplied for this
     parameter the DEFAULT form is evaluated to give the bound
     value(2). If no DEFAULT form is given, then the variable is bound
     to a false value.

     Note that optional parameters must be specified if a later
     parameter is also specified.

          ((lambda (#!optional a b) (list a b)))
              => (() ())
          ((lambda (#!optional a b) (list a b)) 1)
              => (1 ())
          ((lambda (#!optional a b) (list a b)) nil 1)
              => (() 1)
          ((lambda (#!optional (a 1)) (list a)))
              => (1)
          ((lambda (#!optional (a 1)) (list a)) 2)
              => (2)

`#!key'
     This object marks that the parameters up to the next lambda list
     keyword are keyword parameters. The values bound to these
     parameters when the function is called are determined not by
     position (as with normal parameters), but by being marked by a
     preceding keyword symbol.  Keyword symbols have the syntax
     `#:SYMBOL'.

     As with optional parameters, default values may be supplied
     through the use of the `(SYMBOL DEFAULT)' syntax. If no default
     value is given and no keyword argument of the specified kind is
     available, the variable is bound to a false value.

     For example, the lambda list `(a #!key b c)' accepts one required
     argument, and two optional keyword arguments. The variable `a'
     would be bound to the first supplied argument; the variable `b'
     would be bound to the argument preceded by the keyword `#:b', or
     `()' if no such argument exists. (After extracting required and
     optional arguments, each remaining pair of values is checked for
     associating a value with each keyword.)

          ((lambda (a #!key b c) (list a b c)) 1 2 3)
              => (1 () ())
          ((lambda (a #!key b c) (list a b c)) 1 #:b 2 3)
              => (1 2 ())
          ((lambda (a #!key b c) (list a b c)) 1 #:b 2 #:c 3)
              => (1 2 3)
          ((lambda (a #!key b c) (list a b c)) 1 #:c 3 #:b 2)
              => (1 2 3)

`#!rest'
     The `#!rest' keyword allows a variable number of arguments to be
     applied to a function, all the argument values which have not been
     bound to argument variables (or used to mark keyword arguments) are
     made into a list and bound to the variable following the `#!rest'
     keyword. For example, in

          (lambda (x #!rest y) ...)

     the first argument, `x', is required. Any other arguments applied
     to this function are made into a list and this list is bound to the
     variable `y'.

     Variable argument functions may also be defined through the Scheme
     method of using an improper lambda-list. The previous example is
     exactly equivalent to:

          (lambda (x . y) ...)

   When a function represented by a lambda-list is called the first
action is to bind the argument values to the formal parameters. The
LAMBDA-LIST and the list of argument values applied to the function are
worked through in parallel. Any required arguments which are left
undefined when the end of the argument values has been reached causes
an error.

   After the arguments have been processed the BODY-FORMS are evaluated
by an implicit progn, the value of which becomes the value of the
function call. Finally, all parameters are unbound and control passes
back to the caller.

   ---------- Footnotes ----------

   (1) Only used when `librep' is embedded within another application.

   (2) The DEFAULT form is evaluated in the environment of the closure
being called, but without any of the bindings created by the lambda
expression.

Defining Functions
------------------

   Globally accessible functions are usually defined by the `defun'
special form.

 - Macro: defun name lambda-list body-forms...
     `defun' initialises the function definition of the symbol NAME to
     the lambda expression resulting from the concatenation of the
     symbol `lambda', LAMBDA-LIST and the BODY-FORMS.

     The BODY-FORMS may contain a documentation string for the function
     as its first form and an interactive calling specification as its
     first (if there is no doc-string) or second form if the function
     may be called interactively by the user (see Lambda Expressions).

   An example function definition taken from the `librep' source code
is:

     (defun load-all (file)
       "Try to load files called FILE (or FILE.jl, etc) from all
     directories in the Lisp load path."
       (mapc (lambda (dir)
               (let
                   ((full-name (expand-file-name file dir)))
                 (when (or (file-exists-p full-name)
                           (file-exists-p (concat full-name ".jl"))
                           (file-exists-p (concat full-name ".jlc")))
                   (load full-name nil t))))
             load-path))

Anonymous Functions
-------------------

   When supplying functions as arguments to other functions it is often
useful to give an actual function _definition_ (i.e. an enclosed lambda
expression) instead of the name of a function.

   In Lisp, unlike most other programming languages, functions have no
inherent name. As seen in the last section named-functions are created
by storing a function object in a variable, if you want, a function can
have many different names: simply store the function in many different
variables!

   So, when you want to pass a function as an argument there is the
option of just writing down its definition. This is especially useful
with functions like `mapc' and `delete-if'. For example, the following
form removes all elements from the LIST which are even and greater than
20.

     (setq LIST (delete-if (lambda (x)
                             (and (zerop (% x 2)) (> x 20)))
                           LIST))

   The above lambda expression combines two predicates applied to its
argument.

   In certain cases it may be necessary to create a non-constant
function, for example by using backquoting (see Backquoting). In
these cases the `make-closure' function may be used to create a function
object from a lambda expression.

 - Function: make-closure arg
     Return the closure of ARG and the current lexical environment.

 - Function: closurep arg
     Returns true if ARG is a closure.

 - Function: closure-function closure
     Returns the function object associated with the lexical closure
     CLOSURE.

Predicate Functions
-------------------

   In Lisp, a function which returns a boolean `true' or boolean `false'
value is called a "predicate". As is the convention in Lisp a value of
`()' means false, anything else means true. The symbols `nil' and `t'
are often used to represent constant false and true values (see nil and t).

   Another Lisp convention is that the names of predicate functions
should name the quality that the predicate is testing followed by
either a `p' or `-p' string. The `p' variant is used when the first
string does not contain any hyphens.

   For example, the predicate to test for the quality "const-variable"
(a variable which has a constant value, see Defining Variables) is
called `const-variable-p'. On the other hand the predicate to test for
the quality "cons" (a Cons cell) is called `consp'.

Local Functions
---------------

   The `defun' special form allows globally-accessible functions to be
defined. It is often desirable to declare functions local to the
current lexical environment. The `let' and `let*' special form that
were introduced earlier allow this since named functions are simply
functional values stored in variables.

   For example,

     (let
         ((temporary-function (lambda (x)
                                (+ x 42))))
       ...
       (temporary-function 20)
       ...

Calling Functions
-----------------

   Most of the time function applications are made by the evaluator when
it finds a functional value after evaluating the first element of a
list form. However two functions are available for manually calling
functions.

 - Function: funcall function #!rest args
     Applies the argument values ARGS to the function FUNCTION, then
     returns its result.

 - Function: apply function #!rest args
     Similar to `funcall' except that the last of its arguments is a
     _list_ of arguments which are appended to the other members of
     ARGS to form the list of argument values to apply to the function
     FUNCTION.

          (apply + 1 '(2 3))
              => 6

          (apply + (make-list 1000000 1))
              => 1000000

Mapping Functions
-----------------

   A "mapping function" applies a function to each of a collection of
objects. `librep' currently has two mapping functions, `mapcar' and
`mapc'.

 - Function: mapcar function list
     Each element of LIST is individually applied to the function
     FUNCTION. The values returned are made into a new list which is
     returned.

     The FUNCTION must accept a single argument value.

          (mapcar 1+ '(1 2 3 4 5))
              => (2 3 4 5 6)

 - Function: mapc function list
     Similar to `mapcar' except that the values returned when each
     element is applied to the function FUNCTION are discarded. The
     value returned is undefined.

     This function is generally used where the side effects of calling
     the function are the important thing, not the results. It is often
     the most efficient way of traversing all items in a list, for
     example:

          (mapc (lambda (x)
                  (print x standard-error)) list)

   The two following functions are also mapping functions of a sort.
They are variants of the `delete' function (see Modifying Lists)
and use predicate functions to classify the elements of the list which
are to be deleted.

 - Function: delete-if predicate list
     This function is a variant of the `delete' function. Instead of
     comparing each element of LIST with a specified object, each
     element of LIST is applied to the predicate function PREDICATE. If
     it returns true then the element is destructively removed from
     LIST.

          (delete-if stringp '(1 "foo" 2 "bar" 3 "baz"))
              => (1 2 3)

 - Function: delete-if-not predicate list
     This function does the inverse of `delete-if'. It applies
     PREDICATE to each element of LIST, if it returns false then the
     element is destructively removed from the list.

          (delete-if-not stringp '(1 "foo" 2 "bar" 3 "baz"))
              => ("foo" "bar" "baz")

   The `filter' function is similar to `delete-if-not', except that the
original list isn't modified, a new list is created.

 - Function: filter predicate list
     Return a new list, consisting of the elements in LIST which the
     function PREDICATE returns true when applied to. This function is
     equivalent to:

          (mapcar nconc (mapcar (lambda (x)
                                  (and (PREDICATE x) (list x)))
                                LIST))

Macros
======

   "Macros" are used to extend the Lisp language. They consist of a
function which instead of returning a computed value, transform their
unevaluated arguments into a new form that, when evaluated, produces
the actual value of the original form.

   For example, the `when' macro (see Conditional Structures)
implements a new conditional operation by transforming its arguments
into a `cond' statement. That is,

     (when CONDITION FORM ...)
         ==> (cond (CONDITION FORM ...))

   Since macros do not evaluate their arguments, instead just
transforming them, they may be expanded at _compile-time_. The
resulting form is then compiled as usual.

 - Function: macrop arg
     Returns true if ARG is a macro object.

Defining Macros
---------------

   Macros are defined in the same style as functions, the only
difference is the name of the special form used to define them.

   A macro object is a list whose car is the symbol `macro', its cdr is
the function which creates the expansion of the macro when applied to
the macro calls unevaluated arguments.

 - Macro: defmacro name lambda-list body-forms...
     Defines the macro stored in the function cell of the symbol NAME.
     LAMBDA-LIST is the lambda-list specifying the arguments to the
     macro (see Lambda Expressions) and BODY-FORMS are the forms
     evaluated when the macro is expanded. The first of BODY-FORMS may
     be a documentation string describing the macro's use.

   Here is a simple macro definition, it is the definition of the
`when' macro shown in the previous section.

     (defmacro when (condition #!rest body)
       "Evaluates CONDITION, if it's true evaluates the BODY
     forms."
       (list 'cond (list* condition body)))

When a form of the type `(when C B ...)' is evaluated the macro
definition of `when' expands to the form `(cond (C (progn B ...)))'
which is then evaluated to perform the `when'-construct.

   When you define a macro ensure that the forms which produce the
expansion have no side effects; otherwise undefined effects will occur
when programs using the macro are compiled.

Backquoting
-----------

   As seen in the previous sections, macros are a very powerful
mechanism of defining new control structures. However due to the need
to create the expansion, i.e. the form that will be actually evaluated,
they can often be complex to write and understand.

   We have already seen that constants may be produced through the use
of the quote-mark (see Quoting), here another form of quoting is
described, where only some of the quoted object is actually constant.
This is known as "backquoting", since it is introduced by the backquote
character ``', a shortcut for the `backquote' macro.

 - Macro: backquote arg
     Constructs a new version of ARG (a list). All parts of LIST are
     preserved except for expressions introduced by comma (`,')
     characters, which are evaluated and spliced into the list. For
     example:

          `(1 2 ,(+ 1 2))
              => (1 2 3)

     Also, the `,@' prefix will splice the following _list_ into the
     output list, at the same level:

          `(1 2 ,@(list 3))
              => (1 2 3)

   Backquoting allows macros expansions to be created from static
templates. For example the `when' macro shown in the previous sections
can be rewritten as:

     (defmacro when (condition #!rest body)
       `(cond (,condition ,@body)))

which is easier to read, since it is a lot closer to the actual
expansion.

Macro Expansion
---------------

   When a macro call is detected (see List Forms) the function which
is the cdr of the macro's definition (see Defining Macros) is
applied to the macro call's arguments. Unlike in a function call, the
arguments are _not evaluated_, the actual forms are the arguments to
the macro's expansion function. This is to allow these forms to be
rearranged by the macro's expansion function, creating the form that
will finally be evaluated.

   There is a function which performs macro expansion, its main use is
to let the Lisp compiler expand macro calls at compile time.

 - Function: macroexpand form #!optional environment
     If FORM is a macro call `macroexpand' will expand that call by
     calling the macro's expansion function (the cdr of the macro
     definition).  If this expansion is another macro call the process
     is repeated until an expansion is obtained which is not a macro
     call, this form is then returned.

     The optional ENVIRONMENT argument is a function to call to do the
     actual expansion.

          (defmacro when (condition #!rest body)
            "Evaluates CONDITION, if it's true evaluates the BODY
          forms."
            (list 'if condition (cons 'progn body)))
              => when

          (macroexpand '(when x (setq foo bar)))
              => (cond (x (progn (setq foo bar))))

     While a macro is being expanded, the special variable
     `macro-environment' is bound to value of the ENVIRONMENT parameter
     in the containing call to `macroexpand'. This allows macros to
     expand inner macros correctly.

 - Function: macroexpand-1 form #!optional environment
     Similar to `macroexpand', but only a single macro expansion is
     ever performed, i.e. if FORM is a macro call the result of
     expanding that call will be returned, otherwise FORM is returned.

          (macroexpand-1 '(when x (setq foo bar)))
              => (if x (progn (setq foo bar)))

Compiling Macros
----------------

   Although it may seem odd that macros return a form to produce a
result and not simply the result itself, this is actually their most
important feature. It allows the expansion and the evaluation of the
expansion to occur at different times.

   The Lisp compiler makes use of this; when it comes across a macro
call in a form it is compiling it uses the `macroexpand' function to
produce the expansion of that form. This expansion is then compiled
straight into the object code. Obviously this is good for performance
(why evaluate the expansion every time it is needed when once will do?).

   Some rules do need to be observed to make this work properly:

   * The macro expansion function (i.e. the definition of the macro)
     should not have any side effects or evaluate its arguments (the
     value of a symbol at compile-time probably won't be the same as
     its value at run-time).

   * Macros which are defined by another file must be loaded so they
     can be recognised. Use the `require' function, the compiler will
     evaluate any `require' forms it sees loading any macro definitions
     used.

   Note however, that the `librep' compiler does allow macros to be
used before they are defined (two passes are made through the source
file).

Block-Structured Definitions
============================

   Previous sections of this document have described several special
forms and macros for defining top-level functions and variables.
`librep' also provides a higher-level method of creating these
definitions, the `define' statement. `define' originates in the Scheme
dialect of Lisp, it allows block-structured programs to be defined
intuitively.

   The most basic use of `define' is very similar to `defun', e.g. the
two following forms have exactly the same effect:

     (defun foo (x) (1+ x))

     (define (foo x) (1+ x))

But note the different position of the parentheses. This is because
`define' may also be used to define (lexical) variables. Hence the
following is also equivalent:

     (define foo (lambda (x) (1+ x)))

   However this is the most uninteresting aspect of `define'. More
interesting is that it allows "internal definitions".

   Within a `define' form, any inner calls to `define' (that occur in a
contiguous block at the start of the body of a `let', `let*', `letrec',
`lambda', or `define' form) are also used to create definitions, but
definitions that are local to the containing scope. For example:

     (define (foo x)
       (define (bar)
         (* x 42))
       (1+ (bar)))

This defines a top-level function called `foo'. However it also
contains an inner function named `bar', that is only accessible within
`foo'. Since `bar' is defined inside `foo', and librep uses lexical
scope by default, the variable `x' defined by `foo' may also be
accessed by `bar'.

 - Macro: define name form
 - Macro: define (name . args) body-forms...
     Define a global lexical variable called NAME, whose value will be
     set to FORM.

     If the first argument to the macro is a list, then a function is
     defined whose name is NAME and whose formal parameters are
     specified by ARGS. The body of the function is defined by the
     BODY-FORMS. The body forms have any macros expanded, and are
     scanned for internal definitions (at the start of the body of
     `let', `let*', `lambda' special forms)

 - Macro: define-macro name form
 - Macro: define-macro (name . args) body-forms...
     Similar to `define', except that it creates a macro definition
     (see Macros).

 - Macro: with-internal-definitions body-forms
     Recursively expand macros in BODY-FORMS, while scanning out any
     internal definitions into `letrec' statements.

Modules
=======

   When creating large programs from many separate components, it is
important to be able to encapsulate these components, such that the
interfaces they present to other components are well defined, and the
implementations of these interfaces may be modified without affecting
any other components. To this end `rep' provides a "module system" for
managing the scope of global definitions. This module system was
inspired by the Scheme48, Xerox Scheme and Standard ML module systems.

   Modules are known as "structures" and may be anonymous or named.
Each structure specifies and implements an "interface", essentially a
list of names listing the definitions within that module that may be
accessed by other modules. Each structure is a separate global
namespace, with a number of variable bindings. Each closure contains a
reference to the structure it was instantiated in, for accessing the
bindings of any free variables referenced by that closure.

   As well as specifying its name and interface, each module also lists
the other modules whose bindings it may reference. Structures may
either "open" or "access" other structures; when opening a structure
all its exported bindings are immediately referenceable from the
importing module. Exported bindings from accessed structures are
referenced using the `structure-ref' form.

Module Interfaces
-----------------

   Each module implements an interface--the set of bindings (i.e.
functions, macros or variables) that it exports to other modules.
Interfaces may either be defined and then referenced by name, written
literally, or combined from a number of sources.

   The syntax of interface definitions is as follows:

     INTERFACE -> (export ID ...)
               |  NAME
               |  (compound-interface INTERFACE ...)
               |  (structure-interface MODULE-NAME)

where each ID is the name of a binding to export, and each NAME is the
name of an interface previously defined using `define-interface'.

 - Macro: define-interface name interface
     Associate the symbol NAME with the module interface INTERFACE
     (using one of the forms listed above.

   Here is an example defining an interface called `foo':

     (define-interface foo (compound-interface bar (export baz quux)))

It includes the interface called `bar' and adds two extra exported
symbols: `baz' and `quux'.

Module Definition
-----------------

   Two special forms are used to define modules, one for anonymous
modules, one for named modules. When storing modules in files, each
file often contains a single instance of one of these forms.

 - Macro: structure interface config body...
 - Macro: define-structure name interface config body...
     These special forms each create a new module with interface
     INTERFACE (using the syntax described in the previous section),
     and configuration CONFIG.

     After configuring the module as specified, the sequence of forms
     BODY... is evaluated; it should include the definitions required
     by the interface that the module has promised to implement.

     The CONFIG form is either a list of configuration clauses, or a
     single configuration clause. Each such clause must be of the
     following syntax:

          CLAUSE -> (open NAME ...)
                 |  (access NAME ...)

     Each NAME specifies the name of a module, in the case of `open'
     clauses, the named module(s) will be loaded such that their
     exported bindings may be referenced from within the current module
     with no qualification (i.e. as if they had been defined within the
     module itself).

     Alternatively, if an `access' clause was used, the named module(s)
     will be loaded, but their exported bindings will only be accessible
     from within the current module using the `structure-ref' form.
     E.g. if a module `foo' has been accessed and it exports a binding
     named `bar', then the following form could be used to access its
     value:

          (structure-ref foo bar)

     Since this form is used so often, the reader allows the
     abbreviation `foo#bar' to be used instead, it is expanded to the
     form above when read. Note that no whitespace is allowed between
     the three tokens.

   Note that to access the standard features of the `rep' language
described in this manual, modules need to import the `rep' module.
Alternatively, they may import the `scheme' module to load a minimal
R4RS Scheme environment.

   Here is an example module definition, defining a module named `test'
that exports two functions `foo' and `bar'.

     (define-structure test (export foo bar)
         (open rep)
       (define (foo x) (* x 42))
       (define (bar x y) (+ (foo x) (1+ y))))

   It is also possible to export multiple views of a single underlying
set of bindings, by using the `define-structures' form to create a
number of modules.

 - Macro: define-structures ((name interface) ...) config body...
     Create a module for each `(NAME INTERFACE)' pair. The module is
     called NAME and exports the interface defined by INTERFACE.

     The CONFIG and BODY... forms are as in `define-structure'.

     Here is a trivial example:

          (define-structures ((foo (export foo both))
                              (bar (export bar both)))
              (open rep)
            (define both 1)
            (define foo 2)
            (define bar 3))

     the underlying environment has three bindings. Each created module
     exports two of these.

Module Loading
--------------

   As described above, the common way of loading modules is to use the
`open' and `access' clauses of the configuration language.

   If the modules named by these clauses are not currently loaded into
the interpreter, then the system will attempt to load them from the
filing system, using the standard `load-path' variable to define the
directories to search.

   To allow modules names to be hierarchical, any dot characters in a
module's name are replaced by the operating system's directory
separator string (i.e. on unix, all `.' characters are simply replaced
by `/' characters).

   When searching for files to load, the standard filename suffixes are
used to differentiate Lisp files from other types of files (see Load Function).
This file should contain a `define-structure' form (as
described in the previous section) as the last top-level form in the
file.

   For backwards compatibility, the `require' function can also be used
to import modules. If a module of the same name as the requested
feature has already been loaded, then it is imported into the current
module. Otherwise if a file is loaded that contains a module definition
as its last top-level form, this module is imported into the current
module. See Features.

Modules and Special Variables
-----------------------------

   As described earlier, the `defvar' special form may be used to
create variables that are scoped dynamically, known as special
variables, see Defining Variables. Due to their dynamic scope,
special variables do not fit well with the lexically scoped module
system described here.

   As a result of this mismatch, special variables are stored in a
separate namespace. This means that modules defining special variables
must take the necessary steps to avoid the names of these variables
clashing with those declared in other modules(1).

   In fact, it is often advisable to avoid using special variables as
much as possible, especially when writing modules of Lisp code. An
alternative method of creating dynamically scoped variables is to use
fluid variable objects. These use first class Lisp objects to represent
anonymous dynamically scoped variables. Since they are just Lisp
objects, they may be stored in lexically scoped variables--this gives
the benefits of both lexical (i.e. encapsulation) and dynamic scoping.
See Fluid Variables.

   ---------- Footnotes ----------

   (1) The usual convention is to prefix the variable name with a
unique string derived from the module name.

Control Structures
==================

   Control structures are special forms or macros that control _which_
forms get evaluated, _when_ they get evaluated and the _number_ of
times to evaluate them. This includes conditional structures, loops,
etc...

   The simplest control structures are the sequencing structures; they
are used to evaluate a list of forms in left to right order.