@c The Programmer's Manual -*-Texinfo-*-

@chapter The language
@cindex The language
@cindex rep, the Lisp dialect

This chapter is a Lisp guide to the librep.  This manual is still far
from complete.

@menu
* Rep's Lisp Introduction::           Introduction and Lisp conventions
* Crash course for Elisp users:: How does it differ from Elisp?

Fundamental data types.

* Data Types::                  Data types and values in Lisp
* Numbers::                     Numeric representations and functions
* Sequences::                   Ordered sequences of data values
* Symbols::                     Symbols are uniquely named objects

The core language.

* Evaluation::                  Evaluating expressions
* Variables::                   Symbols represent named variables
* Functions::                   The building blocks of Lisp programs
* Macros::                      User-defined control structures
* Definitions::                 Block-structured definitions
* Modules::                     Scoping for "global" definitions
* Control Structures::          Conditionals, loops, etc@dots{}
* Threads::                     Multi-threaded programs
* Loading::                     Programs are stored in files
* Compiled Lisp::               Making programs run faster
* Docstrings::                  Documentation of variable and function

Data structures and I/O.

* Datums::                      Low-level data type definition
* Queues::                      FIFO queue type
* Records::                     Defining structured data types
* Hash Tables::                 Efficient table lookups
* Guardians::                   Protecting objects from GC
* Streams::                     Data sinks and sources; character streams
* Hooks::                       Hooks promote extensibility
* Files::                       Manipulating files in the filing system
* Processes::                   launch and control subprocesses when
                                 running under Unix

Miscellaneous features.
* String Functions::            Misc string manipulation
* utf-8::                       utf-8 functions
* Regular Expressions::         Matching regular expressions

* Time and Date::               Manipulating time and date
* System Information::          Getting details about the host
* User Information::            The name of the user
* Environment Variables::       Reading and writing the environment
* Command Line Options::        Retrieving command line arguments

* Timers::                      Asynchronous timers
* Sleeping::                    Waiting for a period of time
* Beeping::                     Making a ding! sound

* i18n::                        Internationalisation
* Messages::                    Writing to the console

* Debugging::                   How to debug Lisp programs
* Tips::                        General ideas for Librep programming
@end menu

Some functions remain not documented. Get the source, and read

@table @asis
@item Sockets
@file{src/sockets.c}.
@item Dbms
@file{src/repgdbm.c} and @file{src/repsdbm.c}.
@item @code{dynamic-wind}
@file{lisp/rep/lang/interpreter.jl}.
@end table

@node Rep's Lisp Introduction, Crash course for Elisp users, , The language
@section Rep's Lisp Introduction
@cindex Introduction, Lisp

The following sections explain some of the most important Lisp concepts
and the conventions I've used in this manual. If you know Emacs lisp,
see also @xref{Crash course for Elisp users}.

@menu
* Features as Lisp::
* nil and t::                   Boolean values in Lisp
* The Lisp Reader::             Basic program structure
* Notation::                    Special glyphs used
* Descriptions::                How functions and variables are documented
@end menu

@node Features as Lisp, nil and t, , Rep's Lisp Introduction
@subsection Features as Lisp

Librep was originally inspired by Emacs Lisp, but later included many
features from Scheme.

Some of the features of Librep are:

@itemize @bullet
@item Lexically scoped (with special variables from CL)

@item Clean module system

@item Tail-call elimination

@item Compiles to byte-code

@item First-class continuations

@item Uses GNU MP (optionally) for fast bignums/rationals

@item Most Emacs Lisp functions, with others inspired by
Common Lisp and various Scheme implementations

@item Mostly-Perl-like regular expressions

@item Spawn and control subprocesses

@item Dynamically loads shared libraries (a.k.a. ``plugins'')

@item Extensible type, I/O, and file handling
@end itemize

@node nil and t, The Lisp Reader, Features as Lisp, Rep's Lisp Introduction
@subsection nil and t
@cindex nil and t
@cindex t
@cindex Boolean values

In librep there is a single data value representing boolean
``false''---the empty list, written as @code{()}. All other values are
considered ``not-false'', i.e. ``true''.

By convention the constants @code{nil} and @code{t} are used to
represent the canonical boolean values. The constant variable
@code{nil} evaluates to the empty list (i.e. ``false''), while @code{t}
evaluates to itself (i.e. not-``false'', therefore ``true'').

Reiterating, all of the conditional operations regard @emph{anything}
which is not @code{()} as being true (i.e. non-false). The actual
symbol @code{t} should be used where a true boolean value is explicitly
stated, to increase the clarity of the code.

So, @code{()}, and its alias @code{nil}, represent both the empty list
and boolean falsehood. Most Lisp programmers write @code{()} where its
value as a list should be emphasized, and @code{nil} where its value as
boolean false is intended. Although neither of these values need be
quoted (@pxref{Quoting}), most programmers will quote the empty list to
emphasize that it is a constant value. However @code{nil} should not be
quoted, doing so would produce the @emph{symbol} @code{nil}, not
boolean falsehood. For example:

@lisp
(append '() '()) @result{} ()          ;Emphasize use of empty lists

(not nil) @result{} t                  ;Emphasize use as boolean false

(get 'nil 'color)               ;Use the symbol @code{nil}
@end lisp

When a function is said to ``return false'', it means that it returns
the false boolean value, i.e. the empty list. When a function is said
to ``return true'', this means that any non-false value is returned.

@node The Lisp Reader, Notation, nil and t, Rep's Lisp Introduction
@subsection The Lisp Reader
@cindex The Lisp reader
@cindex Reader, the Lisp

Lisp programs and functions are stored internally as Lisp data objects,
the Lisp Reader is the mechanism that translates from textual
descriptions of Lisp objects to the internal data structures
representing them.

@findex read
The Lisp Reader is the collection of internal functions accessed by the
@code{read} Lisp function. It reads a character at a time from an input
stream until a whole Lisp object has been parsed.

@xref{Data Types}.

@node Notation, Descriptions, The Lisp Reader, Rep's Lisp Introduction
@subsection Notation
@cindex Notation
@cindex Manual notation

Wherever an example of evaluating a Lisp form is shown it will be
formatted like this,

@lisp
(+ 1 2)
    @result{} 3
@end lisp

@noindent
The glyph @samp{@result{}} is used to show the computed value of a
form. @footnote{In this case the list @samp{(+ 1 2)} (i.e. the list
containing three elements, the symbol @code{+} and, the numbers 1 and
2), represents a function application. The first element in the list is
the name of the function to be called, all other elements are the
arguments to apply to it. Since the @code{+} function adds a series of
numbers, the above function call is actually performing the computation
@samp{1 + 2}.}

When two forms are shown as being exactly equivalent to one another the
glyph @samp{@equiv{}} is used, for example,

@lisp
(car some-variable) @equiv{} (nth 0 some-variable)
@end lisp

Evaluating some forms result in an error being signalled, this is denoted
by the @samp{@error{}} glyph.

@lisp
(open-file "/tmp/foo" 'read)
    @error{} File error: No such file or directory, /tmp/foo
@end lisp

@node Descriptions, , Notation, Rep's Lisp Introduction
@subsection Descriptions
@cindex Descriptions
@cindex Functions, descriptions of
@cindex Variables, descriptions of

In this document the simplest type of descriptions are those defining
variables (@pxref{Variables}), they look something like:

@defvar grains-of-sand
This imaginary variable contains the number of grains of sand in a
one-mile long stretch of an averagely sandy beach.
@end defvar

Hooks (@pxref{Hooks}) are also described in this format, the only
difference is that @samp{Variable:} is replaced by @samp{Hook:}.

Functions (@pxref{Functions}) and macros (@pxref{Macros}) have more
complex descriptions; as well as the name of the object being
described, they also have a list of parameters which the object will
accept. Each parameter in the list is named and may be referred to in
the body of the description.

Three keyword parameters may also be used: @code{#!optional},
@code{#!key} and @code{#!rest}. They have the same meaning as when used
in the lambda-list of a function definition (@pxref{Lambda
Expressions}). That is, @code{#!optional} means that all further
parameters are optional, and @code{#!rest} means that the following
parameter actually receives a list of any unused argument values.

An example function definition follows.

@defun useless-function first @code{#!optional} second @code{#!rest} tail
This function returns a list consisting of the values @var{second} (when
undefined the number 42 is used), all the items in the list @var{tail}
and @var{first}.

@lisp
(useless-function 'foo 'bar 'xyz 20)
    @result{} (bar xyz 20 foo)

(useless-function '50)
    @result{} (42 50)
@end lisp
@end defun

Macros and interactive commands are defined in the same way with
@samp{Macro:} or @samp{Command:} replacing @samp{Function:}.

Special forms (@pxref{Special Forms}) are described similarly to
functions except that the argument list is formatted differently, since
special forms are, by definition, more flexible in how they treat their
arguments. Optional values are enclosed in square brackets
(@samp{[@var{optional-arg}]}) and three dots
(@samp{@var{repeated-arg}@dots{}}) indicate where zero or more
arguments are allowed.

@node Crash course for Elisp users, Data Types, Rep's Lisp Introduction, The language
@section Crash course for Elisp users
This short course explains how Librep differs from Emacs lisp. It is a
good way to go, because librep can be seen as Elisp + some good parts
of Scheme.  The author is NOT lisp-headed, so you may find it rather
slack.

@subheading Interactive evaluation
To evaluate Lisp expressions interactively, or to enter ``REPL'' --
read, eval, print loop -- then call @code{rep} or
@code{sawfish-client}:

@example
$ rep # or
$ sawfish-client
@end example

These two look similar, but there's a striking difference. The
@code{rep} program starts a clean, new REPL, but in @code{sawfish-client},
each expression is sent to the Sawfish window manager, and evaluated
therein. In this way you can change the Sawfish's options on the fly:

@example
$ sawfish-client
...
user> (setq reboot-command "my/reboot/command --no-broadcast")
@end example

But if you enter an infinite loop by mistake, it makes the window
manager freeze.

If you're an Emacs user, then you can use ``sawfish-mode'', too.
If you type @kbd{C-x C-e} like ``Lisp interaction'' mode, it works
as a wrapper to @code{sawfish-client}, and the expression is sent
to it. For more on Sawfish, read Sawfish manual.

@subheading Scope
The biggest difference from Elisp is that Librep has modules and
lexical scope.  Module will be explained later, so for the time being
just remember that the module system exists.

Variables and functions always live in a module, unless it's global,
or ``special'', or ``dynamically scoped''. In Elisp all variables are
global, but not in Rep. You can declare a global variable with
@code{defvar}:

@lisp
(defvar my-var 'a-value "An example variable")
@end lisp

Do NOT use @code{defvar} unless it's necessary. One common use in
Sawfish of @code{defvar} is to declare a user option. If you need a
variable inside of a module, use @code{define}:

@lisp
;; A variable, not global.
(define var-2 'value-2)
@end lisp

You can make visible this variable to other modules. This will
be explained later in the section on modules.

Like Elisp, @code{defvar} does not override an existing value. (But
@code{define} does.) Function @code{defvar-setq} is @code{defvar} +
@code{setq}, so it declares a global variable, and sets the value.
(It was previously called @code{define-special-variable}, but
a new, better name is provided now.)

Now, an important point. It's a common technique to change the value
of a variable temporarily with @code{let} in Elisp. This works too
in Rep, but ONLY with global variable. Please see the next example:

@lisp
(define a 'outer) ;; Declares a variable.
(define (foo) a)  ;; In elisp, (defun foo () a) Use `define' for both
                  ;; variable and function declaration.

(define (bar)
   (let ((a 'inner)) (foo)))

(bar)
   @result{} outer
;; The let binding is newly established @emph{inside} of bar,
;; and foo doesn't see it.

;; Difference to defvar.
(defvar a 'outer)
(bar)
   @result{} inner ;; The scope of @code{a} is now dynamic.
@end lisp

This is the lexical scope.

There's also the notion of ``fluid'' variables in Rep which is an
intermediate between lexical and dynamic. In my personal opinion,
fluids are not so much useful because Rep's grammar is poor. But it is
used in Sawfish, too. See @xref{Fluid Variables}.

@subheading Functions

You may be shocked by the following example:

@lisp
(define (foo x)
  "Returns X."
  x)
;; In Elisp, (defun foo (x) x)

(define bar foo)
(bar 'baz)
  @result{} baz

bar
  @result{} <#closure foo @@ my-module>

;; More straight example
((lambda (a b c)
   (list c b a))
 1 100 10000)
  @result{} (10000 100 1)
@end lisp

So not only variables and functions live in the same namespace in Rep,
but also functions can easily be passed to variables, and called. This
is called ``Lisp-1'', like Scheme, while Elisp and Common lisp are
``Lisp-2''. It can be a mnemonic that that's why you use @code{define}
for both variable and function definition.

In Rep, a lambda does not evaluate to itself, but to a ``closure''.
A closure can be considered as a function itself, written in lisp,
and associated to the module it belongs to. (And a ``subr'' is a
function in C.) That's why the above example worked.

For function definitions, use @code{define}, like the above example.
The grammar is intuitive, where the definition looks the same as
invocation. Definitions with @code{define} can be nested, so
you can easily write helper functions which are only visible to
the wrapping function.

Use @code{#!optional} and @code{#!rest}, instead of @code{&}. You can
also use named argument passing with @code{#!key}. See @xref{Lambda
Expressions}.

In Rep, you can't @code{funcall} symbols. It's of frequent use for
hooks in Elisp. Instead, you can just pass a function to
@code{add-hook}:

@lisp
(define (viewport-window-uniconified w) ...)
(add-hook 'uniconify-window-hook viewport-window-uniconified)
@end lisp

This works by the same logic as the previous example where a function
is set to a variable.

@subheading Modules
See @xref{Informal Module Introduction}. (In fact, it was originally
written as a part of this section, but a good tutorial on modules
was lacking, so I promoted it to the entire document's tutorial.)

@subheading Misc
Many differences of Rep from Elisp are there, but in this section
let us see only some of them.

The symbol @code{nil} is bound to () in Rep. So (eq nil 'nil) is
t in Elisp, but nil in Rep. () evaluates to itself in both, but not
in Scheme.

@code{#f} evaluates to @code{()}, and @code{#t} to @code{t}. These two
come from Scheme.

Rep does not have the notion of ``command'', but Sawfish does.
See @xref{Commands, , Commands, sawfish, The Sawfish Manual}.

If you loop over list elements, then @code{mapc} and @code{mapcar} are
fast, like Emacs. But ``tail-recursion'' is better than a @code{while}
loop if byte-compiled (@pxref{Compilation Tips}.)

@node Data Types, Numbers, Crash course for Elisp users, The language
@section Data Types
@cindex Data types

The way that data is represented in Lisp is fundamentally different to
languages such as C or Fortran. In Lisp each piece of data (or
@dfn{value}) has two basic attributes: the data and the @emph{type} of
the data. This means that type checking is performed at run-time on the
actual data itself, not at compile-time on the ``variable'' holding the
data.

Also, there are no ``pointers'' in Lisp. As in the Java programming
language, all values are references to data structures, with each
actual data structure (or @dfn{Lisp Object}) being able to have as many
values referring to it concurrently as necessary. Because of this lack
of pointers, there can be no memory-leakage in Lisp---when an object
has no more extant references, it is automatically deallocated
(@pxref{Garbage Collection}).

Most Lisp objects are a member of one of the primitive types; these are
types built into the Lisp system and can represent things like strings,
numbers, cons cells, vectors, etc@dots{} Other primitive types may be
defined at run-time.

More complex objects may be constructed from these primitive types, for
example a vector of three elements could be regarded as a type
@code{triple} if necessary. In general, each separate type provides a
predicate function which returns true when applied to an object of
its own type.

Finally, one of the most important differences between Lisp and other
languages is that there is no distinction between programs and data.
But this will be explained later.

@menu
* Types Summary::               List of the most common types
* Read Syntax::                 Some types can be made from source code
* Printed Representation::      All types can be printed
* Equality Predicates::         How to test two objects for equality
* Comparison Predicates::       Comparing two objects as scalars
* Type Predicates::             Each type has a predicate defining it
* Garbage Collection::          Reusing memory from stale objects
@end menu

@node Types Summary, Read Syntax, , Data Types
@subsection Types Summary
@cindex Types summary
@cindex Data types, summary of

Each separate data type is documented in its own section, this is a just a
summary of the more common types.

@table @dfn
@item Numbers
Numbers: fixnums, bignums, rationals and floats. @xref{Numbers}.

@item Cons cell
An object referring to two other Lisp objects. @xref{Cons Cells}.

@item List
A sequence of objects, in Lisp lists are not primitive types, instead they
are made by chaining together Cons cells. @xref{Lists}.

@item Vector
A one-dimensional array of objects. @xref{Vectors}.

@item String
A vector of characters. @xref{Strings}.

@item Array
An ordered sequence of objects which can be accessed in constant time,
either a vector or a string. @xref{Sequences}.

@item Sequence
An ordered sequence of objects, either a list or an array.
@xref{Sequences}.

@item Symbol
A symbol is a named object; they are used to provide named variables and
functions. @xref{Symbols}.

@item File
A link to a notional file in the filing system. This file may be in the
local filing system, or on a FTP server, or wherever. @xref{Files}.

@item Process
An object through which processes may be created and controlled.
@xref{Processes}.

@item Stream
Serial data sinks and sources. These may include files, functions, and
processes. @xref{Streams}.

@item Void
The empty type, only used in symbols to represent an undefined value.
Note that this is not the same as @code{()}, which is the empty list,
or false truth value.
@end table


@node Read Syntax, Printed Representation, Types Summary, Data Types
@subsection Read Syntax
@cindex Read syntax
@cindex Syntax of objects

As previously noted the Lisp reader translates textual descriptions of
Lisp objects into the object they describe (source files are simply
descriptions of objects). However, not all data types can be created
in this way: in fact the only types which can are numbers, strings,
symbols, cons cells (or lists) and vectors, all others have to be
created by calling functions.

@cindex Comments
Single line comments are introduced by a semi-colon character
(@samp{;}). Whenever the Lisp reader encounters a semi-colon where it's
looking for the read syntax of a new Lisp object it will discard the
rest of the line of input. Block comments are also supported,
introduced by the string @samp{#|} and terminated by @samp{|#}.
@xref{Comment Styles}.

The @dfn{read syntax} of an object is the string which when given to the
reader as input will produce the object. The read syntax of each type
of object is documented in that type's main section of this manual but
here is a small summary of how to write each type.

@table @asis
@item Numbers
A number is number written as an integer---decimal, octal (when the
number is preceded by @samp{#o}) or hexadecimal (when the number is
preceded by @samp{#x})---or a decimal rational or floating point value.
An optional minus sign may be the first character in a number. Some
examples are,

@lisp
42
    @result{} 42

#o177
    @result{} 127

#x-ff
    @result{} -255

3/2
    @result{} 3/2

1.23
    @result{} 1.23
@end lisp

For full documentation, read @xref{Number Read Syntax}.

@item Strings
The read syntax of a string is simply the string with a double-quote
character (@samp{"}) at each end, for more details see @ref{Strings}.

@lisp
"This is a string"
@end lisp

@item Character
In Librep, a character is an unsigend 8-bit integer. It read syntax
is a question mark(@samp{?}) and the character itself. For the
details, see @xref{Characters}.

@lisp
?a
    @result{} 97
@end lisp

@item Cons cells
A cons cell is written in what is known as @dfn{dotted pair notation},
an opening left-parenthesis, followed by the read syntax of the first
object, followed by a dot, then the second object, and finally a
closing right-parenthesis. For example:

@lisp
("car" . "cdr")
@end lisp

@item Lists
The syntax of a list is similar to a cons cell, but the dot is removed
and zero or more objects may be written:

@lisp
(0 1 2 3)

("foo" ("bar" "baz") 100)
@end lisp

@noindent
The second example is a list of three elements, a string, an inner list
and a number.

@item Vectors
The read syntax of a vector is similar to that of a list, but with
square brackets instead of parentheses,

@lisp
[0 1 2 3]
@end lisp

@item Symbols
The read syntax of a symbol is its name, for example the read syntax of
the symbol called @samp{my-symbol} is,

@lisp
my-symbol
@end lisp
For more, read @xref{Symbol Syntax}.
@end table


@node Printed Representation, Equality Predicates, Read Syntax, Data Types
@subsection Printed Representation
@cindex Printed representation

As well as translating textual descriptions to Lisp objects, the
process may be reversed, converting a value back to a textual
description. The resulting text is known as the @dfn{printed
representation} of the object, and will usually be very similar to the
read syntax of the object (@pxref{Read Syntax}).

Objects which do not have a read syntax @emph{do} have a printed
representation, it will normally be of the form,

@lisp
#<@var{relevant-text}>
@end lisp

@noindent
where the @var{relevant-text} is object-dependent and usually describes
the object and its contents. The reader will signal an error if it
encounters a description of an object in the format @samp{#<@dots{}>}.


@node Equality Predicates, Comparison Predicates, Printed Representation, Data Types
@subsection Equality Predicates
@cindex Equality predicates
@cindex Predicates, equality

@defun eq arg1 arg2
Returns true when @var{arg1} and @var{arg2} refer to the same object.
Two objects are the same when they occupy the same place in memory and
hence modifying one object would alter the other. The following Lisp
fragments may illustrate this,

@lisp
(eq "foo" "foo")        ;the objects are distinct
    @result{} ()

(eq t t)                ;the same object -- the symbol @code{t}
    @result{} t
@end lisp

Note that the result of @code{eq} is @emph{undefined} when called on
two integer objects with the same value, see @code{eql}.
@end defun

@defun equal arg1 arg2
The function @code{equal} compares the structure of the two objects
@var{arg1} and @var{arg2}. If they are considered to be equivalent then
returns true, otherwise returns false.

@lisp
(equal "foo" "foo")
    @result{} t

(equal 42 42)
    @result{} t

(equal 42 0)
    @result{} ()

(equal '(x . y) '(x . y))
    @result{} t
@end lisp
@end defun

@defun eql arg1 arg2
This function is a cross between @code{eq} and @code{equal}: if
@var{arg1} and @var{arg2} are both numbers then the value of these
numbers are compared. Otherwise it behaves in exactly the same manner
as @code{eq} does. See also the document of @code{=}. (@pxref{Comparison Predicates}.)

@lisp
(eql 3 3)
    @result{} t

(eql 1 2)
    @result{} ()

(eql "foo" "foo")
    @result{} ()

(eql 'x 'x)
    @result{} t
@end lisp
@end defun


@node Comparison Predicates, Type Predicates, Equality Predicates, Data Types
@subsection Comparison Predicates
@cindex Comparison predicates
@cindex Predicates, comparison

These functions compare their two arguments in a scalar fashion, the
arguments may be of any type but the results are only meaningful for
numbers, strings (ASCII values of each byte compared until a
non-matching pair is found then those two values are compared as
numbers) and cons cells (cars compared before cdrs).

Unlike the @code{eql} function, inexact and exact numbers will be
compared by first coercing the exact number to be inexact.

@defun = arg1 arg2 arg3 @dots{} argn
Returns true if all arguments represent the same value.
@end defun

@defun /= arg1 arg2 arg3 @dots{} argn
Returns true if no two arguments represent the same value.
@end defun

@defun > arg1 arg2 arg3 @dots{} argn
Returns true when @var{arg1} is `greater than' @var{arg2}, and
@var{arg2} is greater than @var{arg3}, and so on, upto @var{argn}.
@end defun

@defun >= arg1 arg2 arg3 @dots{} argn
Similar to @code{>}, but for the ``greater than or equal to'' relation.
@end defun

@defun < arg1 arg2 arg3 @dots{} argn
Similar to @code{>}, but for the ``less than'' relation.
@end defun

@defun <= arg1 arg2 arg3 @dots{} argn
Similar to @code{>}, but for the ``less than or equal to'' relation.
@end defun

There are two related functions for finding the maximum or minimum of a
sequence of values.

@defun max @t{#!rest} args
Return the maximum value from the list of @var{args}. When comparing
numbers, any inexact arguments cause the result to be inexact.
@end defun

@defun min @t{#!rest} args
Return the minimum value from the list of @var{args}. When comparing
numbers, any inexact arguments cause the result to be inexact.
@end defun


@node Type Predicates, Garbage Collection, Comparison Predicates, Data Types
@subsection Type Predicates
@cindex Type predicates
@cindex Predicates, type

Each type has a corresponding predicate which defines the objects which
are members of that type. Each predicate function has a single
parameter, if that parameter is of the correct type it returns
true.

@noindent
@code{integerp}, @code{numberp}, @code{null}, @code{consp},
@code{listp}, @code{vectorp}, @code{subrp}, @code{functionp},
@code{sequencep}, @code{stringp}, @code{symbolp}, @code{processp},
@code{filep}.

The documentation for these functions is with the documentation for the
relevant type.


@node Garbage Collection, , Type Predicates, Data Types
@subsection Garbage Collection
@cindex Garbage collection

In Lisp, data objects are used very freely; a side effect of this is
that it is not possible to (easily) know when an object is @dfn{stale},
that is, no references to it exist and it can therefore be reused.

The @dfn{garbage collector} is used to overcome this problem; whenever
enough memory has been allocated to make it worthwhile, evaluation
stops and the garbage collector works its way through memory deciding
which objects may still be referenced, and which are stale. The stale
objects are then recorded as being available for reuse and evaluation
continues. (But @pxref{Guardians})

@defun garbage-collect
Runs the garbage collector, usually this function doesn't need to
be called manually.
@end defun

@defvar garbage-threshold
The number of bytes of data that must have been allocated since the
last garbage collection before evaluation pauses and the garbage
collector is invoked. Its default value is about 100K.
@end defvar

@defvar idle-garbage-threshold
When the input loop is idle (due to a lack of input), this is the
number of bytes of data that must have been allocated since the garbage
collection, for another collection to be triggered.

This is usually set to a lot less than @code{garbage-threshold} since
the small delay caused by garbage collection is unnoticeable if the
system is already idle.
@end defvar

@defvar after-gc-hook
A hook (@pxref{Normal Hooks}) called immediately after each invocation
of the garbage collector.
@end defvar


@node Numbers, Sequences, Data Types, The language
@section Numbers
@cindex Numbers
@cindex Integers

Librep lacks exact number specification. The behavior depends
on if it is compiled with gmp support or not. Of course, some
feautures are not available without gmp@footnote{GMP, or GNU MP is a
library which supports arbitrary precision arithmetic.}.

If it is compiled without gmp, then the size of integer type also
depends on the platform. Size of integer is 30-bit signed at minimum.

If portability is important, like sawfish, then you should expect the
minimum. For more information, @xref{Types of Numbers}.

For conversion of number from / to string, see @xref{String Functions}.

@defun numberp object
Returns true if @var{object} is a number.
@end defun

@menu
* Types of Numbers::
* Numeric Predicates::
* Number Read Syntax::
* Arithmetic Functions::
* Integer Functions::
* Rational Functions::
* Real Number Functions::
* Mathematical Functions::
* Bitwise Functions::
* Random Numbers::
* Characters::
@end menu

@node Types of Numbers, Numeric Predicates, , Numbers
@subsection Types of Numbers
@cindex Types of Numbers
@cindex Numbers, types
@cindex Portability in Number

First understand that librep distinguishes @code{exact} and
@code{inexact} numbers. This is similar to Scheme. Quoting from the
Scheme standard:

@quotation
@dots{} numbers are either @emph{exact} or @emph{inexact}. A number is
exact if it was written as an exact constant or was derived from exact
numbers using only exact operations. A number is inexact if it was
written as an inexact constant, if it was derived using inexact
ingredients, or if it was derived using inexact operations. Thus
inexactness is a contagious property of a number.
@end quotation

Librep has three types of numbers: integer, rational, and
float.

With gmp, exact numbers include both integers and rational numbers.
There is no theoretical limit to the range of the values that may be
represented @footnote{However, depending on implementation
restrictions, very large integers may be coerced to an inexact
representation.}.

Without gmp, only integer is exact. Rational numbers get approximated
with float. On 32-bit system, integer is signed 30-bit (@emph{not} 32
bits), and 62-bit on 64-bit system.@footnote{Internally, unsigned 64-bit
integer is supported too, and used in some cases. But this is not
available to Lisp programmers.}

Inexact numbers are currently implemented using double precision
floating point values.

When exact arguments are passed to functions which take float arguments,
then they are automatically converted to float.

Note that Rep often handles integer overflow by converting the result
from integer to float.

@node Numeric Predicates, Number Read Syntax, Types of Numbers, Numbers
@subsection Numeric Predicates
@cindex Numeric predicates
@cindex Numbers, predicates on
@cindex Predicates on numbers

Don't use @code{eq} for equality test of numbers. Instead, use
@code{eql} or @code{equal}. See @ref{Equality Predicates}.

For the documentation of the functions @code{=}, @code{/=}, @code{>},
@code{<}, @code{>=}, @code{<=}, @code{max} and @code{min}, see
@ref{Comparison Predicates}.

@defun exactp object
Returns true when @var{object} is an exact number.
@end defun

@defun inexactp object
Returns true when @var{object} is an inexact number.
@end defun

@defun integerp object
Returns true when @var{object} is an integer.
@end defun

@defun rationalp object
Returns true when @var{object} is a rational number (including
integers).
@end defun

@defun realp object
Returns true when @var{object} is a real number.
@end defun

@defun oddp x
Return true if @var{x} is an odd number.
@end defun

@defun evenp x
Return true if @var{x} is an even number.
@end defun

@defun positivep x
Return true if @var{x} is a number greater than zero.
@end defun

@defun negativep x
Return true if @var{x} is a number less than zero.
@end defun

@defun zerop x
Returns true if @var{x} is equal to zero.
@end defun

@node Number Read Syntax, Arithmetic Functions, Numeric Predicates, Numbers
@subsection Number Read Syntax
@cindex Number, Read Syntax
@cindex Read Syntax of Numbers

The read syntax of any number is:
@code{[@var{prefix}@dots{}][@var{sgn}]@var{data}@dots{}}, where the
optional @var{sgn} is one of the characters @samp{-} or @samp{+},
@var{data} is the representation of the number, and @var{prefix} is zero
or more of the following prefix strings:

@table @code
@item #b
@itemx #B
Integers are described in binary,

@item #o
@itemx #O
Integers are in octal,

@item #d
@itemx #D
Integers are in decimal (the default),

@item #x
@itemx #X
Integers are in hexadecimal,

@item #e
@itemx #E
Coerce the number to an exact representation after parsing it,

@item #i
@itemx #I
Coerce to an inexact representation.
@end table

@noindent

The representation of an integer is simply the digits representing that
integer, in the radix chosen by any given prefix (defaults to decimal).
Examples of valid integer read syntaxes for the number 42 could be
@samp{42}, @samp{#x2a}, @samp{#o52}, @samp{#o+52}, @dots{}

The representation of a rational number is two sequences of digits,
separated by a @samp{/} character. For example, @samp{3/2} represents
the rational number three divided by two. It is supported without gmp too,
but the read value is converted to float.

Inexact numbers are parsed from one of two representations: decimal
point form, which is simply a decimal number containing a decimal
point, and exponential form, which is a decimal number followed by the
letter @samp{e} and a decimal exponent multiplying the first part of
the number by that power of ten. For example, @samp{10.0}, @samp{10.}
and @samp{1e1} all read as the inexact number ten. Note that the radix
prefixes currently have no effect when parsing inexact numbers, decimal
is used exclusively.

An integer's printed representation is simply the number printed in
decimal with a preceding minus sign if it is negative. Rational numbers
are printed as two integers separated by a @samp{/} character. Inexact
numbers are printed in their decimal form.

@node Arithmetic Functions, Integer Functions, Number Read Syntax, Numbers
@subsection Arithmetic Functions
@cindex Arithmetic Functions
@cindex Numbers, arithmetic functions

There are a number of functions which perform arithmetic operations on
numbers, they take a varying number of values as their arguments
returning a new number as their result. When given only exact
arguments, an exact result will be returned.

@defun + number1 @t{#!rest} numbers
This functions adds its arguments then returns their sum.
@end defun

@defun - number1 @t{#!rest} numbers
If this function is just given one argument (@var{number1}) that number is
negated and returned. Otherwise each of @var{numbers} is subtracted from
a running total starting with the value of @var{number1}.

@lisp
(- 20)
    @result{} -20

(- 20 10 5)
    @result{} 5
@end lisp
@end defun

@defun * number1 @t{#!rest} numbers
This function multiplies its arguments then returns the result.
@end defun

@defun / number1 @t{#!rest} numbers
This function performs division, a running-total (initialised from
@var{number1} is successively divided by each of @var{numbers} then
the result is returned.

@lisp
(/ 100 2)
    @result{} 50

(/ 200 2 5)
    @result{} 20

(/ 3 2)
    @result{} 3/2

(/ 3.0 2)
    @result{} 1.5
@end lisp
@end defun

@defun 1+ number
This function returns the result of adding one to @var{number}.

@lisp
(1+ 42)
    @result{} 43
@end lisp
@end defun

@defun 1- number
Returns @var{number} minus one.
@end defun


@node Integer Functions, Rational Functions, Arithmetic Functions, Numbers
@subsection Integer Functions
@cindex Integer functions
@cindex Numbers, integer functions

The functions described in this section all operate on, and return,
integer values.

@defun quotient dividend divisor
Return the integer part of dividing @var{dividend} by @var{divisor}.
@end defun

@defun remainder dividend divisor
Returns the integer remainder from dividing the @var{dividend} by
@var{divisor}. The remainder is either zero or has the same sign as
@var{dividend}.
@end defun

@defun modulo dividend divisor
@defunx mod dividend divisor
Return the value of @var{dividend} modulo @var{divisor}. Unlike the
@code{remainder} function the @code{modulo} function always has the
sign of the @var{divisor}, not of the @var{dividend}
@end defun

@defun gcd args@dots{}
Returns the greatest common divisor of the integers @var{args}@dots{}
If no arguments are given, returns zero.
@end defun

@defun lcm args@dots{}
Return the lowest common multiple of the integers @var{args}@dots{} If
no arguments are given, returns one.
@end defun


@node Rational Functions, Real Number Functions, Integer Functions, Numbers
@subsection Rational Functions
@cindex Rational functions
@cindex Numbers, rational functions

These functions operate on rational numbers.

@defun numerator x
Returns the exact numerator of @var{x}.
@end defun

@defun denominator x
Returns the exact denominator of @var{x}.
@end defun

@defun exact->inexact x
Returns an inexact version of rational number @var{x}.
@end defun


@node Real Number Functions, Mathematical Functions, Rational Functions, Numbers
@subsection Real Number Functions
@cindex Real number functions
@cindex Numbers, real number functions

@defun inexact->exact x
Returns an exact representation of @var{x}. This may involve a loss of
accuracy.
@end defun

@defun abs x
Returns the magnitude of @var{x}.
@end defun

@defun floor x
Round @var{x} downwards to the nearest integer less than or equal to
@var{x}.
@end defun

Four rounding functions are provided. With gmp, they return integer.
Without gmp, they return float type, just like libc counterparts, to
avoid overflow. You can convert it to integer with
@code{inexact->exact}.

@defun ceiling x
Round @var{x} upwards to the nearest integer less than or equal to
@var{x}.
@end defun

@defun truncate x
Round @var{x} to the nearest integer between @var{x} and zero.
@end defun

@defun round x
Round @var{x} to the nearest integer. Halfway cases are rounded to the
nearest even integer.
@end defun



@node Mathematical Functions, Bitwise Functions, Real Number Functions, Numbers
@subsection Mathematical Functions
@cindex Mathematical functions
@cindex Numbers, mathematical functions

Functions below returns float type number.

@defun exp x
Return `e' (the base of natural logarithms) raised to the power
@var{x}.
@end defun

@defun log x
Return the natural logarithm of @var{x}. An arithmetic error is
signalled if @var{x} is less than zero.
@end defun

@defun sin x
Return the sine of angle @var{x}; x is in terms of radians.
@end defun

@defun cos x
Return the cosine of angle @var{x}.
@end defun

@defun tan x
Return the tangent of angle @var{x}.
@end defun

@defun asin x
Return the arc sine of @var{x} (the value whose sine is @var{x}), in
radians.
@end defun

@defun acos x
Return the arc cosine of @var{x}.
@end defun

@defun atan x
Return the arc tangent of @var{x}.
@end defun

@defun sqrt x
Return the non-negative square root of @var{x}. Currently, if @var{x}
is negative, an arithmetic error is signalled.
@end defun

@defun expt x y
Returns @var{x} raised to the power @var{y}.

If @var{x} is negative and @var{y} is a non-integer, then an arithmetic
error is signalled (mathematically should return a complex number).
@end defun


@node Bitwise Functions, Random Numbers, Mathematical Functions, Numbers
@subsection Bitwise Functions
@cindex Bitwise functions
@cindex Numbers, bitwise functions

These functions operate on the bit string which an integer represents,
assuming a two's complement representation.

@defun lsh number count
This function shifts the integer @var{number} @var{count} bits to the
left, if @var{count} is negative @var{number} is shifted to the right
instead.

@lisp
(lsh 1 8)
    @result{} 256

(lsh 256 -8)
    @result{} 1
@end lisp
@end defun

@defun logand number1 @t{#!rest} numbers
This function uses a bit-wise logical `and' operation to combine all its
arguments (there must be at least one argument).

@lisp
(logand 15 8)
    @result{} 8

(logand 15 7 20)
    @result{} 4
@end lisp
@end defun

@defun logior number1 @t{#!rest} numbers
Uses a bit-wise logical `inclusive-or' to combine all its arguments (there
must always be at least one argument).

@lisp
(logior 1 2 4)
    @result{} 7
@end lisp
@end defun

@defun logxor number1 @t{#!rest} numbers
Uses a bitwise logical `exclusive-or' to combine all its arguments
(there must be at least one).

@lisp
(logxor 7 3)
    @result{} 4
@end lisp
@end defun

@defun lognot number
This function inverts all the bits in @var{number}.

@lisp
(lognot 0)
    @result{} -1

(lognot 2)
    @result{} -3

(lognot -1)
    @result{} 0
@end lisp
@end defun


@node Random Numbers, Characters, Bitwise Functions, Numbers
@subsection Pseudo-Random Numbers
@cindex Pseudo-random numbers
@cindex Random numbers
@cindex Numbers, pseudo random

The @code{random} function allows pseudo-random numbers to be
generated.

@defun random @t{#!optional} limit
Return a pseudo-random number between zero and @var{limit}-1 inclusive.
If @var{limit} is undefined, it is taken as being the largest positive
integer representable in a fixnum.

Calling @code{random} with @var{limit} equal to the symbol @code{t}
seeds the generator with the current time of day.
@end defun


@node Characters, , Random Numbers, Numbers
@subsection Characters
@cindex Characters

In Librep characters are stored in integers. Their read syntax
is a question mark followed by the character itself, which may be an
escape sequence introduced by a backslash. For details of the available
escape sequences see @ref{Strings}.

@lisp
?a
    @result{} 97

?\n
    @result{} 10

?\177
    @result{} 127

;; Also special escape syntaxes only for character, not for string.
#\newline
    @result{} 10  ; = ?\n
;; also #\backspace, #\tab, #\linefeed, #\return, #\page, 
;; #\space, and #\rubout are available.

#\s
    @result{} 115  ; = ?s
;; Other than above cases, the first character is read.
@end lisp

Functions below makes sence for ascii characters only.

@defun alpha-char-p character
This function returns true when @var{character} is one of the
alphabetic characters.

@lisp
(alpha-char-p ?a)
    @result{} t
@end lisp
@end defun

@defun upper-case-p character
When @var{character} is one of the upper-case characters this function
returns true.
@end defun

@defun lower-case-p character
Returns true when @var{character} is lower-case.
@end defun

@defun digit-char-p character
This function returns true when @var{character} is one of the decimal
digit characters.
@end defun

@defun alphanumericp character
This function returns true when @var{character} is either an alphabetic
character or a decimal digit character.
@end defun

@defun space-char-p character
Returns true when @var{character} is a white-space character (space, tab,
newline or form feed).
@end defun

@defun char-upcase character
This function returns the upper-case equivalent of @var{character}. If
@var{character} is already upper-case or has no upper-case equivalent it
is returned unchanged.

@lisp
(char-upcase ?a)
    @result{} 65                       ;`A'

(char-upcase ?A)
    @result{} 65                       ;`A'

(char-upcase ?!)
    @result{} 33                       ;`!'
@end lisp
@end defun

@defun char-downcase character
Returns the lower-case equivalent of the character @var{character}.
@end defun


@node Sequences, Symbols, Numbers, The language
@section Sequences
@cindex Sequences
@cindex Arrays

Sequences are ordered groups of objects, there are several primitive
types which can be considered sequences, each with their pros and cons.

A sequence is either an array or a list, where an array is either a vector
or a string.

@defun sequencep object
This function returns true if @var{object} is a sequence.
@end defun

@menu
* Cons Cells::                  An ordered pair of two objects
* Lists::                       Chains of cons cells
* Vectors::                     A chunk of memory holding a number of objects
* Strings::                     Strings are efficiently-stored vectors
* Array Functions::             Accessing elements in vectors and strings
* Sequence Functions::          These work on any type of sequence
@end menu


@node Cons Cells, Lists, , Sequences
@subsection Cons Cells
@cindex Cons cells
@cindex Sequences, cons cells

A @dfn{cons cell} is an ordered pair of two objects, the @dfn{car} and
the @dfn{cdr}.

The read syntax of a cons cell is an opening parenthesis followed by the
read syntax of the car, a dot, the read syntax of the cdr and a closing
parenthesis. For example a cons cell with a car of 10 and a cdr of
the string @samp{foo} would be written as,

@lisp
(10 . "foo")
@end lisp

@defun cons car cdr
This function creates a new cons cell. It will have a car of @var{car} and
a cdr of @var{cdr}.

@lisp
(cons 10 "foo")
    @result{} (10 . "foo")
@end lisp
@end defun

@defun consp object
This function returns true if @var{object} is a cons cell.

@lisp
(consp '(1 . 2))
    @result{} t

(consp '())
    @result{} ()

(consp (cons 1 2))
    @result{} t
@end lisp
@end defun

The strange syntax @samp{'(1 . 2)} is known as @dfn{quoting}
(@pxref{Quoting}), it tells the evaluator that the object following the
quote-mark is a constant, and therefore should not be evaluated. This
will be explained in more detail later.

@cindex Atom
In Lisp an @dfn{atom} is any object which is not a cons cell (and is,
therefore, atomic).

@defun atom object
Returns true if @var{object} is an atom (not a cons cell).
@end defun

Given a cons cell there are a number of operations which can be performed
on it.

@defun car cons-cell
This function returns the object which is the car (first element) of
the cons cell @var{cons-cell}.

@lisp
(car (cons 1 2))
    @result{} 1

(car '(1 . 2))
    @result{} 1
@end lisp
@end defun

@defun cdr cons-cell
This function returns the cdr (second element) of the cons cell
@var{cons-cell}.

@lisp
(cdr (cons 1 2))
    @result{} 2

(cdr '(1 . 2))
    @result{} 2
@end lisp
@end defun

Rep also provides @code{cXXr}, @code{cXXXr}, and @code{cXXXXr}, where
each @var{x} is either @code{a} or @code{d}. For example, @code{(cadr z)}
is equal to @code{(car (cdr z))}.

@defun rplaca cons-cell new-car
This function sets the value of the car (first element) in the cons
cell @var{cons-cell} to @var{new-car}. The value returned is
@var{cons-cell}.

@lisp
(setq x (cons 1 2))
    @result{} (1 . 2)
(rplaca x 3)
    @result{} (3 . 2)
x
    @result{} (3 . 2)
@end lisp
@end defun

@defun rplacd cons-cell new-cdr
This function is similar to @code{rplacd} except that the cdr slot
(second element) of @var{cons-cell} is modified.
@end defun

@defun setcar cons-cell new-car
@defunx setcdr cons-cell new-cdr
Same as @code{rplaca} and @code{rplacd} respectively, but the
return value is @var{new-car} / @var{new-cdr}.
@end defun

@node Lists, Vectors, Cons Cells, Sequences
@subsection Lists
@cindex Lists

A list is a sequence of zero or more objects, the main difference between
lists and vectors is that lists are more dynamic: they can change size,
be split, reversed, concatenated, etc@dots{} very easily.

In Lisp lists are not a primitive type; instead singly-linked lists are
formed by chaining cons cells together (@pxref{Cons Cells}). The empty
list is represented by the special value @code{()}.

@defun listp arg
This functions returns true when its argument, @var{arg}, is a
list (i.e. either a cons cell or @code{()}).
@end defun

@defun null arg
Returns a true value if @var{arg} is the empty list.
@end defun

@menu
* List Structure::              How lists are built from cons cells
* Building Lists::              Dynamically creating lists
* Accessing List Elements::     Getting at the elements which make the list
* Modifying Lists::             How to alter the contents of a list
* Association Lists::           Lists can represent relations
* Infinite Lists::              Circular data structures in Lisp
@end menu


@node List Structure, Building Lists, , Lists
@subsubsection List Structure
@cindex List structure

Each element in a list is given its own cons cell and stored in the car
of that cell. The list is then constructed by having the cdr of a cell
point to the cons cell containing the next element (and hence the
entire rest of the list). The cdr of the cell containing the last
element in the list is @code{()}. A list of zero elements is
represented by @code{()}.

The read syntax of a list is an opening parenthesis, followed by the
read syntax of zero or more space-separated objects, followed by a
closing parenthesis. Alternatively, lists can be constructed `manually'
using dotted-pair notation.

All of the following examples result in the same list of five elements:
the numbers from zero to four.

@lisp
(0 1 2 3 4)

(0 . (1 . (2 . (3 . (4 . ())))))

(0 1 2 . (3 4))
@end lisp

An easy way to visualise lists and how they are constructed is to see
each cons cell in the list as a separate @dfn{box} with pointers to its
car and cdr,

@example
+-----+-----+
|  o  |  o----> cdr
+--|--+-----+
   |
    --> car
@end example

Complex box-diagrams can now be drawn to represent lists. For example the
following diagram represents the list @code{(1 2 3 4)}.

@example
+-----+-----+   +-----+-----+   +-----+-----+   +-----+-----+
|  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |  o----> ()
+--|--+-----+   +--|--+-----+   +--|--+-----+   +--|--+-----+
   |               |               |               |
    --> 1           --> 2           --> 3           --> 4
@end example

A more complex example, the list @code{((1 2) (foo bar))} can be drawn as,

@example
+-----+-----+                          +-----+-----+
|  o  |  o---------------------------> |  o  |  o----> ()
+--|--+-----+                          +--|--+-----+
   |                                      |
+-----+-----+   +-----+-----+          +-----+-----+   +-----+-----+
|  o  |  o----> |  o  |  o----> ()     |  o  |  o----> |  o  |  o----> ()
+--|--+-----+   +--|--+-----+          +--|--+-----+   +--|--+-----+
   |               |                      |               |
    --> 1           --> 2                  --> foo         --> bar
@end example


@node Building Lists, Accessing List Elements, List Structure, Lists
@subsubsection Building Lists
@cindex Building lists
@cindex Lists, building

It has already been described how you can create lists using the Lisp
reader; this method does have a drawback though: the list created is
effectively static. If you modify the contents of the list and that
list was created when a function was defined the list will remain
modified for all future invocations of that function. This is not
usually a good idea, consider the following function definition,

@lisp
(defun bogus-function (x)
  "Return a list whose first element is nil and whose second element is X."
  (let
      ((result '(nil nil)))     ;Static list which is filled in each time
    (rplaca (cdr result) x)     ; the function is called
    result))
@end lisp

@noindent
This function does in fact do what its documentation claims, but a
problem arises when it is called more than once,

@lisp
(setq x (bogus-function 'foo))
    @result{} (nil foo)
(setq y (bogus-function 'bar))
    @result{} (nil bar)               ;The first result has been destroyed
x
    @result{} (nil bar)               ;See!
@end lisp

This example is totally contrived---no one would ever write a
function like the one in the example but it does demonstrate the need
for a dynamic method of creating lists.

@defun list @t{#!rest} elements
This function creates a list out of its arguments, if zero arguments are
given the empty list, @code{()}, is returned.

@lisp
(list 1 2 3)
    @result{} (1 2 3)

(list (major-version-number) (minor-version-number))
    @result{} (3 2)

(list)
    @result{} ()
@end lisp
@end defun

@defun list* arg1 arg2 @dots{} argn-1 argn
Creates a new list @code{(@var{arg1} @var{arg2} @dots{} @var{argn-1} .
@var{argn})}.

@lisp
(list* 1 2 '(3 4))
    @result{} (1 2 3 4)
@end lisp
@end defun

@defun make-list length @t{#!optional} initial-value
This function creates a list @var{length} elements long. If the
@var{initial-value} argument is given it defines the value of all
elements in the list, if it is not defined they are all @code{()}.

@lisp
(make-list 2)
    @result{} (() ())

(make-list 3 t)
    @result{} (t t t)

(make-list 0)
    @result{} ()
@end lisp
@end defun

@defun append @t{#!rest} lists
This function creates a new list with the elements of each of its arguments
(which must be lists). Unlike the function @code{nconc} this function
preserves the structure of all its arguments.

@lisp
(append '(1 2 3) '(4 5))
    @result{} (1 2 3 4 5)

(append)
    @result{} ()
@end lisp

What actually happens is that all arguments but the last are copied,
then the last argument is linked on to the end of the list (uncopied).

@lisp
(setq foo '(1 2))
    @result{} (1 2)
(setq bar '(3 4))
    @result{} (3 4)
(setq baz (append foo bar))
    @result{} (1 2 3 4)
(eq (nthcdr 2 baz) bar)
    @result{} t
@end lisp

The following diagram shows the final state of the three variables more
clearly,

@example
foo--> +-----+-----+   +-----+-----+
       |  o  |  o----> |  o  |     |
       +--|--+-----+   +--|--+-----+
          |               |
          o--> 1          o--> 2   bar
          |               |          ->
baz--> +--|--+-----+   +--|--+-----+   +-----+-----+   +-----+-----+
       |  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |     |
       +-----+-----+   +-----+-----+   +--|--+-----+   +--|--+-----+
                                          |               |
                                           --> 3           --> 4
@end example

Note how @code{foo} and the first half of @code{baz} use the @emph{same}
objects for their elements---copying a list only copies its cons cells, its
elements are reused. Also note how the variable @code{bar} actually
references the mid-point of @code{baz} since the last list in an @code{append}
call is not copied.
@end defun

@defun remove elt list
Return a copy of @var{list}, with all elements the same as @var{elt}
discarded (using the @code{equal} function to compare).
@end defun

@defun remq elt list
Similar to the @code{remove} function, except that comparisons are made
using @code{eq}.
@end defun

@defun reverse list
This function returns a new list; it is made from the elements of the list
@var{list} in reverse order. Note that this function does not alter its
argument.

@lisp
(reverse '(1 2 3 4))
    @result{} (4 3 2 1)
@end lisp
@end defun

As a postscript to this section, the function used as an example at the
beginning could now be written as,

@lisp
(defun not-so-bogus-function (x)
  (list nil x))
@end lisp

Also note that the @code{cons} function can be used to create lists by hand
and to add new elements onto the front of a list. For example:

@lisp
(setq x (list 1 2 3))
    @result{} (1 2 3)
(setq x (cons 0 x))
    @result{} (0 1 2 3)
@end lisp


@node Accessing List Elements, Modifying Lists, Building Lists, Lists
@subsubsection Accessing List Elements
@cindex Accessing list elements
@cindex Lists, accessing elements

The most flexible method of accessing an element in a list is via a
combination of the @code{car} and @code{cdr} functions. There are other
functions which provide an easier way to get at the elements in a flat
list. These will usually be faster than a string of @code{car} and
@code{cdr} operations.

@defun nth count list
This function returns the element @var{count} elements down the list,
therefore to access the first element use a @var{count} of zero (or even
better the @code{car} function). If there are too few elements in the list
and no element number @var{count} can be found @code{()} is returned.

@lisp
(nth 3 '(0 1 2 3 4 5))
    @result{} 3

(nth 0 '(foo bar)
    @result{} foo
@end lisp
@end defun

@defun nthcdr count list
This function takes the cdr of the list @var{list} @var{count} times,
returning the last cdr taken.

@lisp
(nthcdr 3 '(0 1 2 3 4 5))
    @result{} (3 4 5)

(nthcdr 0 '(foo bar))
    @result{} (foo bar)
@end lisp
@end defun

@defun last list
This function returns the last element in the list @var{list}. If the
list has zero elements @code{()} is returned.

@lisp
(last '(1 2 3))
    @result{} 3

(last '())
    @result{} ()
@end lisp
@end defun

@defun member object list
This function scans through the list @var{list} until it finds an element
which is @code{equal} to @var{object}. The tail of the list (the cons cell
whose car is the matched object) is then returned. If no elements match
@var{object} then the empty list @code{()} is returned.

@lisp
(member 'c '(a b c d e))
    @result{} (c d e)

(member 20 '(1 2))
    @result{} ()
@end lisp
@end defun

@defun memq object list
This function is similar to @code{member} except that comparisons are
performed by the @code{eq} function not @code{equal}.
@end defun

@node Modifying Lists, Association Lists, Accessing List Elements, Lists
@subsubsection Modifying Lists
@cindex Modifying lists
@cindex Lists, modifying

The @code{nthcdr} function can be used in conjunction with the @code{rplaca}
function to modify an arbitrary element in a list. For example,

@lisp
(rplaca (nthcdr 2 '(0 1 2 3 4 5)) 'foo)
    @result{} foo
@end lisp

@noindent
sets the third element of the list @code{(0 1 2 3 4 5)} to the symbol
called @code{foo}.

There are also functions which modify the structure of a whole list. These
are called @dfn{destructive} operations because they modify the actual
structure of a list---no copy is made. This can lead to unpleasant
side effects if care is not taken.

@defun nconc @t{#!rest} lists
This function is the destructive equivalent of the function @code{append},
it modifies its arguments so that it can return a list which is the
concatenation of the elements in its arguments lists.

Like all the destructive functions this means that the lists given as
arguments are modified (specifically, the cdr of their last cons cell
is made to point to the next list). This can be seen with the
following example (similar to the example in the @code{append} documentation).

@lisp
(setq foo '(1 2))
    @result{} (1 2)
(setq bar '(3 4))
    @result{} (3 4)
(setq baz (nconc foo bar))
    @result{} (1 2 3 4)
foo
    @result{} (1 2 3 4)                ;`foo' has been altered!
(eq (nthcdr 2 baz) bar)
    @result{} t
@end lisp

The following diagram shows the final state of the three variables more
clearly,

@example
foo-->                           bar-->
baz--> +-----+-----+   +-----+-----+   +-----+-----+   +-----+-----+
       |  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |     |
       +--|--+-----+   +--|--+-----+   +--|--+-----+   +--|--+-----+
          |               |               |               |
           --> 1           --> 2             --> 3           --> 4
@end example
@end defun

@defun nreverse list
This function rearranges the cons cells constituting the list @var{list}
so that the elements are in the reverse order to what they were.

@lisp
(setq foo '(1 2 3))
    @result{} (1 2 3)
(nreverse foo)
    @result{} (3 2 1)
foo
    @result{} (1)                      ;`foo' wasn't updated when the list
                                ; was altered.
@end lisp
@end defun

@defun delete object list
This function destructively removes all elements of the list @var{list}
which are @code{equal} to @var{object} then returns the modified list.

@lisp
(delete 1 '(0 1 0 1 0))
    @result{} (0 0 0)
@end lisp

When this function is used to remove an element from a list which is stored
in a variable that variable must be set to the return value of the
@code{delete} function. Otherwise, if the first element of the list
has to be deleted (because it is @code{equal} to @var{object}) the value
of the variable will not change.

@lisp
(setq foo '(1 2 3))
    @result{} (1 2 3)
(delete 1 foo)
    @result{} (2 3)
foo
    @result{} (1 2 3)
(setq foo (delete 1 foo))
    @result{} (2 3)
@end lisp
@end defun

@defun delq object list
This function is similar to the @code{delete} function, the only difference
is that the @code{eq} function is used to compare @var{object} with each
of the elements in @var{list}, instead of the @code{equal} function which
is used by @code{delete}.
@end defun

@defun sort list @t{#!optional} predicate
Destructively sorts (i.e. by modifying cdrs) the list of values
@var{list}, to satisfy the function @var{predicate}, returning the
sorted list. If @var{predicate} is undefined, the @code{<} function is
used, sorting the list into ascending order.

@var{predicate} is called with two values, it should return true if
the first is considered less than the second.

@lisp
(sort '(5 3 7 4))
    @result{} (3 4 5 7)
@end lisp

The sort is stable, in that elements in the list which are equal will
preserve their original positions in relation to each other.
@end defun

See also @code{delete-if}, @code{delete-if-not}, @code{filter} and so on.
(@pxref{Mapping Functions}).

@node Association Lists, Infinite Lists, Modifying Lists, Lists
@subsubsection Association Lists
@cindex Association lists
@cindex Alists
@cindex Lists, association

An @dfn{association list} (or @dfn{alist}) is a list mapping keys to
to. Each element of the alist is a cons cell, the car of which is the
@dfn{key}, the cdr the value that it associates to. For example an
alist could look like,

@lisp
((fred . 20)
 (bill . 30))
@end lisp

@noindent
this alist has two keys, @code{fred} and @code{bill} which both associate
to an integer (20 and 30 respectively).

It is possible to make the associated values lists, this looks like,

@lisp
((fred 20 male)
 (bill 30 male)
 (sue  25 female))
@end lisp

@noindent
in this alist the symbol @code{fred} is associated with the list
@code{(20 male)}.

There are a number of functions which let you interrogate an alist with
a given key for its association.

@defun assoc key alist
This function scans the association list @var{alist} for the first element
whose car is @code{equal} to @var{key}, this element is then returned. If
no match of @var{key} is found false is returned.

@lisp
(assoc 'two '((one . 1) (two . 2) (three . 3)))
    @result{} (two . 2)
@end lisp
@end defun

@defun assq key alist
Similar to the function @code{assoc} except that the function @code{eq} is
used to compare elements instead of @code{equal}.

It is not usually wise to use @code{assq} when the keys of the alist may not
be symbols---@code{eq} won't think two objects are equivalent unless they
are the @emph{same} object!

@lisp
(assq "foo" '(("bar" . 1) ("foo" . 2)))
    @result{} ()
(assoc "foo" '(("bar" . 1) ("foo" . 2)))
    @result{} ("foo" . 2)
@end lisp
@end defun

@defun rassoc association alist
This function searches through @var{alist} until it finds an element whose
cdr is @code{equal} to @var{association}, that element is then returned.
false will be returned if no elements match.

@lisp
(rassoc 2 '((one . 1) (two . 2) (three . 3)))
    @result{} (two . 2)
@end lisp
@end defun

@defun rassq association alist
This function is equivalent to @code{rassoc} except that it uses @code{eq}
to make comparisons.
@end defun

@defun assoc-regexp key-regex alist @t{#!optional} fold-case
Same as @code{assoc}, but it is matched with the regular expression
@var{key-regex}.
@end defun

@node Infinite Lists, , Association Lists, Lists
@subsubsection Infinite Lists
@cindex Infinite lists
@cindex Circular lists
@cindex Lists, circular

Sometimes it is useful to be able to create `infinite' lists---that is,
lists which appear to have no last element---this can easily be done
in Lisp by linking the cdr of the last cons cell in the list structure
back to the beginning of the list.

@example
 -----------------------------------
|                                   |
 --> +-----+-----+   +-----+-----+  |
     |  o  |  o----> |  o  |  o-----
     +--|--+-----+   +--|--+-----+
        |               |
         --> 1           --> 2
@end example

The diagram above represents the infinite list @code{(1 2 1 2 1 2 @dots{})}.

Infinite lists have a major drawback though, many of the standard list
manipulation functions can not be used on them. These functions work by
moving through the list until they reach the end. If the list has @emph{no}
end the function may never terminate and the only option is to send the
interpreter an interrupt signal.

The only functions which may be used on circular lists are: the cons
cell primitives (@code{cons}, @code{car}, @code{cdr}, @code{rplaca},
@code{rplacd}), @code{nth} and @code{nthcdr}.

Also note that infinite lists can't be printed. But note the
@code{print-length} and @code{print-level} variables, see @ref{Output
Functions}.


@node Vectors, Strings, Lists, Sequences
@subsection Vectors

A vector is a fixed-size sequence of Lisp objects, each element may be
accessed in constant time---unlike lists where the time taken to access
an element is proportional to the position of the element.

The read syntax of a vector is an opening square bracket, followed by zero
or more space-separated objects, followed by a closing square bracket. For
example,

@lisp
[zero one two three]
@end lisp

In general it is best to use vectors when the number of elements to be
stored is known and lists when the sequence may grow or shrink.

@defun vectorp object
This function returns true if its argument, @var{object}, is a vector.
@end defun

@defun vector @t{#!rest} elements
This function creates a new vector containing the arguments given to the
function.

@lisp
(vector 1 2 3)
    @result{} [1 2 3]

(vector)
    @result{} []
@end lisp
@end defun

@defun make-vector size @t{#!optional} initial-value
Returns a new vector, @var{size} elements big. If @var{initial-value} is
defined each element of the new vector is set to @var{initial-value}, otherwise
they are all @code{()}.

@lisp
(make-vector 4)
    @result{} [() () () ()]

(make-vector 2 t)
    @result{} [t t]
@end lisp
@end defun


@node Strings, Array Functions, Vectors, Sequences
@subsection Strings

A string is a vector of characters (@pxref{Characters}). It is
generally used for storing and manipulating pieces of text.
Librep puts no restrictions on the values which may be stored in
a string---specifically, the null character (@samp{^@@}) may be
stored with no problems.

In librep, a string is a sequcene of raw bytes, and no encoding is
assumed. Some special functions for utf-8 encoded strings are provided.
See @xref{utf-8}.

The read syntax of a string is a double quote character, followed by the
contents of the string, the object is terminated by a second double quote
character. For example, @code{"abc"} is the read syntax of the string
@samp{abc}.

@cindex Escape sequences in strings
@cindex Strings, escape sequences
Any backslash characters in the string's read syntax introduce an escape
sequence; one or more of the following characters are treated specially to
produce the next @emph{actual} character in the string.

The following escape sequences are supported (all are shown without their
leading backslash @samp{\} character).

@table @asis
@item @samp{n}
A newline character.

@item @samp{r}
A carriage return character.

@item @samp{f}
A form feed character.

@item @samp{t}
A TAB character.

@item @samp{a}
A `bell' character (this is Ctrl-g).

@item @samp{\}
A backslash character.

@item @samp{^@var{c}}
The `control' code of the character @var{c}. This is calculated by toggling
the seventh bit of the @emph{upper-case} version of @var{c}.

For example,

@lisp
\^C             ;A Ctrl-c character (ASCII value 3)
\^@@            ;The NUL character (ASCII value 0)
@end lisp

@item @samp{012}
The character whose ASCII value is the octal value @samp{012}. After the
backslash character the Lisp reader reads up to three octal digits and
combines them into one character.

@item @samp{x12}
The character whose ASCII value is the hexadecimal value @samp{12}, i.e.
an @samp{x} character followed by one or two hex digits.

@item Others
If none of the above applies, the leading backslash is ignored. This
is sometimes useful for editors syntax parsing, especially for
punctuation characters.
@end table

@defun stringp object
This function returns true if its argument is a string.
@end defun

@defun make-string length @t{#!optional} initial-character
Creates a new string containing @var{length} characters, each character
is initialised to @var{initial-character} (or to spaces if
@var{initial-character} is not defined).

@lisp
(make-string 3)
    @result{} "   "

(make-string 2 ?$)
    @result{} "$$"
@end lisp
@end defun

@defun concat @t{#!rest} args
This function concatenates all of its arguments, @var{args}, into a single
string which is returned. If no arguments are given then the null string
(@samp{}) results.

Each of the @var{args} may be a string, a character or a list or vector of
characters. Characters are stored in strings modulo 256.

@lisp
(concat "foo" "bar")
    @result{} "foobar"

(concat "a" ?b)
    @result{} "ab"

(concat "foo" [?b ?a ?r])
    @result{} "foobar"

(concat)
    @result{} ""
@end lisp
@end defun

@defun substring string start @t{#!optional} end
This function creates a new string which is a partial copy of the string
@var{string}. The first character copied is @var{start} characters from
the beginning of the string. If the @var{end} argument is defined it is
the index of the character to stop copying at, if it is not defined
all characters until the end of the string are copied.

@lisp
(substring "xxyfoozwx" 3 6)
    @result{} "foo"

(substring "xyzfoobar" 3)
    @result{} "foobar"
@end lisp

For utf-8 encoded strings, use @code{utf8-substring} instead
(@pxref{utf-8}).
@end defun

@defun string= string1 string2
This function compares the two strings @var{string1} and
@var{string2}---if they are made from the same characters in the same
order then true is returned.

@lisp
(string= "one" "one")
    @result{} t

(string= "one" "two")
    @result{} ()
@end lisp

Note that an alternate way to compare strings (or anything!) is to use the
@code{equal} function.
@end defun

@defun string-equal string1 string2
Returns true if @var{string1} and @var{string2} are the same,
ignoring differences in character case.
@end defun

@defun string< string1 string2
This function returns true if @var{string1} is `less' than @code{string2}.
This is determined by comparing the two strings a character at a time, the
first pair of characters which do not match each other are then compared
with a normal `less-than' function.

In Librep the standard @code{<} function understands strings so
@code{string<} is just a macro calling that function.

@lisp
(string< "abc" "abd")
    @result{} t

(string< "abc" "abb")
    @result{} ()
@end lisp
@end defun

@defun string-lessp string1 string2
Similar to @code{string<} but ignores character case in comparisons.
@end defun

See @ref{String Functions} for a few more string manipulating
functions, and @ref{Regular Expressions} for a method of pattern
matching in strings.


@node Array Functions, Sequence Functions, Strings, Sequences
@subsection Array Functions
@cindex Array functions

@defun arrayp object
This function returns true if @var{object} is an array.
@end defun

@defun aref array position
Returns the element of the array (vector or string) @var{array} @var{position}
elements from the first element (i.e. the first element is numbered zero).
If no element exists at @var{position} in @var{array}, false is
returned.

@lisp
(aref [0 1 2 3] 2)
    @result{} 2

(aref "abcdef" 3)
    @result{} 100                      ;`d'
@end lisp
@end defun

@defun aset array position value
This function sets the element of the array @var{array} with an index of
@var{position} (counting from zero) to @var{value}. An error is signalled
if element @var{position} does not exist. The result of the function is
@var{value}.

@lisp
(setq x [0 1 2 3])
    @result{} [0 1 2 3]
(aset x 2 'foo)
    @result{} foo
x
    @result{} [0 1 foo 3]
@end lisp
@end defun


@node Sequence Functions, , Array Functions, Sequences
@subsection Sequence Functions
@cindex Sequence functions

@defun sequencep arg
Returns true if @var{arg} is a sequence, i.e. a list or an array.
@end defun

@defun length sequence
This function returns the length (an integer) of the sequence @var{sequence}.

@lisp
(length "abc")
    @result{} 3

(length '(1 2 3 4))
    @result{} 4

(length [x y])
    @result{} 2
@end lisp

For utf-8 encoded strings, use @code{utf8-string-length}
(@pxref{utf-8}).
@end defun

@defun copy-sequence sequence
Returns a new copy of the sequence @var{sequence}. Where possible (in lists
and vectors) only the `structure' of the sequence is newly allocated: the
same objects are used for the elements in both sequences.

@lisp
(copy-sequence "xy")
    @result{} "xy"

(setq x '("one" "two"))
    @result{} ("one" "two")
(setq y (copy-sequence x))
    @result{} ("one" "two")
(eq x y)
    @result{} ()
(eq (car x) (car y))
    @result{} t
@end lisp
@end defun

@defun elt sequence position
This function returns the element of @var{sequence} @var{position} elements
from the beginning of the sequence.

This function is a combination of the @code{nth} and @code{aref} functions.

@lisp
(elt [0 1 2 3] 1)
    @result{} 1

(elt '(foo bar) 0)
    @result{} foo
@end lisp
@end defun


@node Symbols, Evaluation, Sequences, The language
@section Symbols
@cindex Symbols

Symbols are objects with a name (almost always a unique name). They are
one of the most important data types in Lisp since they are used to
provided named variables (@pxref{Variables}) and functions
(@pxref{Functions}).

@defun symbolp arg
This function returns true when its argument is a symbol.
@end defun

@menu
* Symbol Syntax::               The read syntax of symbols
* Symbol Attributes::           The objects stored in a symbol
* Obarrays::                    Vectors used to store symbols
* Creating Symbols::            Allocating new symbols
* Interning::                   Putting a symbol into an obarray
* Property Lists::              Each symbol has a set of properties
* Keyword Symbols::             Self-evaluating keywords
@end menu


@node Symbol Syntax, Symbol Attributes, , Symbols
@subsection Symbol Syntax
@cindex Symbol syntax

The read syntax of a symbol is usually its name; however, if the name
contains any meta-characters (whitespace or any from @samp{()[]'";|\})
they will have to be entered specially. There are two ways to tell the
reader that a meta-character is actually part of the symbol's name:

@enumerate
@item
Precede the meta-character by a backslash character (@samp{\}), for
example:

@lisp
xy\(z\)                 ;the symbol whose name is @samp{xy(z)}
@end lisp

@item
Enclose part of the name in vertical bars (two @samp{|} characters).
All characters after the starting vertical line are copied as-is until
the closing vertical line is encountered. For example:

@lisp
xy|(z)|                 ;the symbol @samp{xy(z)}
@end lisp
@end enumerate

Here are some example read syntaxes.

@lisp
setq                    ; @samp{setq}
|setq|                  ; @samp{setq}
\s\e\t\q                ; @samp{setq}
1                       ; the @emph{number} 1
\1                      ; the @emph{symbol} @samp{1}
|!$%zf78&|              ; @samp{!$%zf78&}
foo|(bar)|              ; @samp{foo(bar)}
foo\(bar\)              ; @samp{foo(bar)}
@end lisp


@node Symbol Attributes, Obarrays, Symbol Syntax, Symbols
@subsection Symbol Attributes
@cindex Symbol attributes

All symbols have two basic attributes: print name and property list.
Most important is the @dfn{print name} of the symbol. This is a string
naming the symbol, after it has been defined (when the symbol is first
created) it may not be changed.

@defun symbol-name symbol
This function returns the print name of the symbol @var{symbol}.

@lisp
(symbol-name 'unwind-protect)
    @result{} "unwind-protect"
@end lisp
@end defun

The symbol's @dfn{property list} (or plist) is similar to an alist
(@pxref{Association Lists}), though stored differently, and provides a
method of storing arbitrary extra values in each symbol. @xref{Property
Lists}.

Although not strictly an attribute of the symbol, symbols also provide
a means of associating values with names (i.e. variables). Within a
defined context, a symbol may have a @dfn{binding}, this binding
associates the symbol with a memory location within which a value may
be stored. When writing Lisp programs, the value of a symbol's current
binding is accessed by writing the print name of the symbol. Similarly
the binding may be modified by using the @code{setq} special form.
@xref{Variables}.


@node Obarrays, Creating Symbols, Symbol Attributes, Symbols
@subsection Obarrays
@cindex Obarrays
@cindex Symbols, obarrays

An @dfn{obarray} is the structure used to ensure that no two symbols
have the same name and to provide quick access to a symbol given its
name. An obarray is a vector, each element of the vector is a chain of
symbols whose names share the same hash-code (a @dfn{bucket}). These
symbols are chained together through links which are invisible to Lisp
programs: if you examine an obarray you will see that each bucket looks
as though it has at most one symbol stored in it.

The normal way to reference a symbol is simply to type its name in the
program, when the Lisp reader encounters a name of a symbol it looks
in the default obarray for a symbol of that name. If the named symbol
doesn't exist it is created and hashed into the obarray---this
process is known as @dfn{interning} the symbol, for more details see
@ref{Interning}.

@defvar obarray
This variable contains the obarray that the @code{read} function uses when
interning symbols.
@end defvar

@defun make-obarray size
This function creates a new obarray with @var{size} hash buckets (this
should probably be a prime number for the fewest hash collisions).

This is the only way of creating an obarray. @code{make-vector} is
@emph{not suitable}.
@end defun

@defun find-symbol symbol-name @t{#!optional} obarray
This function scans the specified obarray (@var{obarray} or the value of
the variable @code{obarray} if @var{obarray} is undefined) for a symbol
whose name is the string @var{symbol-name}. The value returned is the
symbol if it can be found or false otherwise.

@lisp
(find-symbol "setq")
    @result{} setq
@end lisp
@end defun

@defun apropos regexp @t{#!optional} predicate obarray
Returns a list of symbols from the obarray @var{obarray} (or the
default) whose print name matches the regular expression @var{regexp}
(@pxref{Regular Expressions}). If @var{predicate} is true, each symbol
which matches @var{regexp} is applied to the function @var{predicate},
if the value is true it is considered a match.

The @var{predicate} argument is useful for restricting matches to a
certain type of symbol, for example only commands.

@lisp
(apropos "^yank" 'commandp)
    @result{} (yank-rectangle yank yank-to-mouse)
@end lisp
@end defun


@node Creating Symbols, Interning, Obarrays, Symbols
@subsection Creating Symbols
@cindex Creating symbols
@cindex Symbols, creating

It is possible to allocate symbols dynamically, this is normally only
necessary when the symbol is to be interned in a non-default obarray or
the symbol is a temporary object which should not be interned (for
example: labels in a compiler).

@defun make-symbol print-name
This function creates and returns a new, uninterned, symbol whose print
name is the string @var{print-name}. Its value cell is void (undefined)
and it will have an empty property list.

If you're unsure, use @code{intern} instead. (@pxref{Interning}.)

@lisp
(make-symbol "foo")
    @result{} foo

(eq 'foo (make-symbol "foo"))
    @result{} ()

(eq 'foo (intern "foo"))
    @result{} t
@end lisp
@end defun

@defun gensym
This function returns a new, uninterned, symbol that has a unique print
name.

@lisp
(gensym)
    @result{} G0001

(gensym)
    @result{} G0002
@end lisp
@end defun


@node Interning, Property Lists, Creating Symbols, Symbols
@subsection Interning
@cindex Interning
@cindex Symbols, interning

@dfn{Interning} a symbol means to store it in an obarray so that it can
be found in the future: all variables and named-functions are found
through interned symbols.

When a symbol is interned a hash function is applied to its print name to
determine which bucket in the obarray it should be stored in. Then it is
simply pushed onto the front of that bucket's chain of symbols.

Normally all interning is done automatically by the Lisp reader. When
it encounters the name of a symbol which it can't find in the default
obarray (the value of the variable @code{obarray}) it creates a new
symbol of that name and interns it. This means that no two symbols can
have the same print name, and that the read syntax of a particular
symbol always produces the same object (unless the value of
@code{obarray} is altered).

@lisp
(eq 'some-symbol 'some-symbol)
    @result{} t
@end lisp

@defun intern symbol-name @t{#!optional} obarray
This function uses @code{find-symbol} to search the @var{obarray} (or the
standard obarray) for a symbol called @var{symbol-name}. If a symbol of
that name is found it is returned, otherwise a new symbol of that name is
created, interned into the obarray, and returned.

@lisp
(intern "setq")
    @result{} setq

(intern "my-symbol" my-obarray)
    @result{} my-symbol
@end lisp
@end defun

@defun intern-symbol symbol @t{#!optional} obarray
Interns the symbol @var{symbol} into the obarray @var{obarray} (or the
standard one) then returns the symbol. If @var{symbol} is currently
interned in an obarray an error is signalled.

@lisp
(intern-symbol (make-symbol "foo"))
    @result{} foo

(intern-symbol 'foo)
    @error{} Error: Symbol is already interned, foo
@end lisp
@end defun

@defun unintern symbol @t{#!optional} obarray
This function removes the symbol @var{symbol} from the obarray @var{obarray}
then returns the symbol.

Beware! this function should be used with @emph{extreme} caution---once you
unintern a symbol there may be no way to recover it.

@lisp
(unintern 'setq)                ;This is extremely stupid
    @result{} setq
@end lisp
@end defun


@node Property Lists, Keyword Symbols, Interning, Symbols
@subsection Property Lists
@cindex Property lists
@cindex Symbols, property lists

Each symbol has a property list (or @dfn{plist}), this is a structure which
associates an arbitrary Lisp object with a key (usually a symbol). The
keys in a plist may not have any duplications (so that each property is
only defined once).

The concept of a property list is very similar to an association list
(@pxref{Association Lists}) but there are two main differences:

@enumerate
@item
Structure; each element of an alist represents one key/association pair. In
a plist each pair of elements represents an association: the first
is the key, the second the property. For example, where an alist may
be,

@lisp
((one . 1) (two . 2) (three . 3))
@end lisp

@noindent
a property list would be,

@lisp
(one 1 two 2 three 3)
@end lisp

@item
Plists have their own set of functions to modify the list. This is done
destructively, altering the property list (since the plist is stored in
only one location, the symbol, this is quite safe).
@end enumerate

@defun get symbol property
This function searches the property list of the symbol @var{symbol} for
a property @code{equal} to @var{property}. If such a property is found
it is returned, otherwise false is returned.

@lisp
(get 'if 'lisp-indent)
    @result{} 2

(get 'set 'lisp-indent)
    @result{} ()
@end lisp
@end defun

@defun put symbol property new-value
@code{put} sets the value of the property @var{property} to
@var{new-value} in the property list of the symbol @var{symbol}. If
there is an existing value for this property (using @code{equal} to
compare keys) it is overwritten. The value returned is @var{new-value}.

@lisp
(put 'foo 'prop 200)
    @result{} 200
@end lisp
@end defun

@defun symbol-plist symbol
Returns the property list of the symbol @var{symbol}.

@lisp
(symbol-plist 'if)
    @result{} (lisp-indent 2)
@end lisp
@end defun

@defun setplist symbol plist
This function sets the property list of the symbol @var{symbol} to
@var{plist}.

@lisp
(setplist 'foo '(zombie yes))
    @result{} (zombie yes)
@end lisp
@end defun


@node Keyword Symbols, , Property Lists, Symbols
@subsection Keyword Symbols
@cindex Keyword symbols
@cindex Symbols, keywords

Keywords are a special class of symbols. They evaluate to themselves,
and have the read syntax @samp{#:@var{symbol}}, where @var{symbol} is
anything satisfying the usual symbol syntax. These objects are normally
used to mark keyword parameters in function applications (@pxref{Lambda
Expressions}).

@defun make-keyword symbol
Return the keyword symbol that could be used to mark an argument value
for the keyword parameter @var{symbol}.

@lisp
(make-keyword 'x)
    @result{} #:x
@end lisp
@end defun

@defun keywordp arg
Returns true if @var{arg} is a keyword symbol.
@end defun


@node Evaluation, Variables, Symbols, The language
@section Evaluation
@cindex Evaluation
@cindex Evaluating Lisp forms
@cindex Lisp forms, evaluating

So far only the primitive data types have been discussed, and how the
Lisp reader converts textual descriptions of these types into Lisp
objects. Obviously there has to be a way of actually computing
something---it would be difficult to write a useful program
otherwise.

What sets Lisp apart from other languages is that in Lisp there is no
difference between programs and data: a Lisp program is just a sequence
of Lisp objects which will be evaluated as a program when required.

The subsystem which does this evaluation is called the @dfn{Lisp
evaluator} and each expression to be evaluated is called a @dfn{form}.
The evaluator (the function @code{eval}) examines the structure of the
form that is applied to it and computes the value of that form within
the current Lisp environment.

A form can be any type of data object; the only types which the
evaluator treats specially are symbols (which describe variables) and
lists (subroutine applications), anything else is returned as-is (and
is called a @dfn{self-evaluating form}).

@defun eval form @t{#!optional} structure
This function computes and returns the value of @var{form} within the
current module and dynamic environment, and a null lexical environment.

If the optional argument @var{structure} is non-nil, then @var{form}
is evaluated in that structure.
@end defun

However, @code{eval} is rarely explicitly invoked, except in the
read-eval-print loop. Lisp provides many other methods of evaluation
that are usually much more suitable within a program.

@defvar max-lisp-depth
This variable limits the number of nested calls to @code{eval}. If more
than this many nested calls to @code{eval} exist, an error is
signalled. The intention is to detect infinite recursion before hitting
the stack size limit (causing a segmentation fault).
@end defvar

@menu
* Symbol Forms::                How variables are accessed
* List Forms::                  Subroutine calls
* Self-Evaluating Forms::       Forms which don't get evaluated
* Quoting::                     How to prevent evaluation of forms
@end menu


@node Symbol Forms, List Forms, , Evaluation
@subsection Symbol Forms
@cindex Symbol forms
@cindex Forms, symbol
@cindex Forms, variable

When the evaluator is applied to a symbol the computed value of the
form is the value associated with the symbol in the current
environment. Basically this means that to get the value of a variable
you simply write its name. For example,

@lisp
rep-version
    @result{} "1.0"
@end lisp

@noindent
this extract from a Lisp session shows the read syntax of a form to
get the value of the variable @code{rep-version} and the result when
this form is evaluated.

Since forms are evaluated within the current environment the value of a
variable is its most-recent extant binding (with slight differences for
lexical and special variables). @xref{Variables}.

If an evaluated symbol has no current binding, an error is signalled.


@node List Forms, Self-Evaluating Forms, Symbol Forms, Evaluation
@subsection List Forms
@cindex List forms

Forms which are lists are used to invoke a subroutine. The first
element of the list defines the subroutine to be called; all further
elements are arguments to be applied to that subroutine invocation.

There are several different types of subroutines available: functions,
macros, special forms and autoloads. When the evaluator finds a form
which is a list it tries to classify the form into one of these four
types.

First of all it evaluates the first element of the list; the computed
value of this element decides how the rest of the elements in the list
are treated. For example, if the first element is a symbol whose value
is a function, then that function is called with the other values in
the list.

@menu
* Function Call Forms::         `Normal' subroutines
* Macro Call Forms::            Source code expansions
* Special Forms::               Abnormal control structures
* Autoload Forms::              Loading subroutines from files on the fly
@end menu


@node Function Call Forms, Macro Call Forms, , List Forms
@subsubsection Function Call Forms
@cindex Function call forms
@cindex Forms, function call

When the first element of a list form evaluates to a function object
(either a primitive subroutine or a closure), all other elements in the
list are evaluated sequentially from left-to-right, then these values
are applied to the function definition. The result returned by the
function is then taken as the value of the whole list form.

For example, consider the form @code{(/ 100 (1+ 4))}. This is a
function call to the function stored in the variable @code{/}. First
the @code{/} form is evaluated, it is a variable containing a data
value representing the primitive subroutine for integer division. Then
the @code{100} form is evaluated: it is a number, so self-evaluates to
the value @code{100}. Next the form @code{(1+ 4)} is evaluated. This is
also a function call and computes to a value of @code{5} which becomes
the second argument to the @code{/} function. Now the @code{/} function
is applied to its evaluated arguments of @code{100} and @code{5}, and
returns the value @code{20}. This then becomes the value of the form
@code{(/ 100 (1+ 4))}.

@lisp
(/ 100 (1+ 4))
@equiv{} (/ 100 5)
@result{} 20
@end lisp

Or another example,

@lisp
(+ (- 10 (1- 7)) (* (1+ 2) 4)
@equiv{} (+ (- 10 6) (* (1+ 2) 4)
@equiv{} (+ 4 (* (1+ 2) 4)
@equiv{} (+ 4 (* 3 4))
@equiv{} (+ 4 12)
@result{} 16
@end lisp

The system is also capable of eliminating tail calls where possible,
allowing tail-recursive function definitions to run with bounded space
requirements.

A @dfn{tail-call} is a function call that occurs immediately before
exiting the containing function. Since the containing function need not
receive the result of the function call, it is possible to, in effect,
exit from the containing function before invoking the called function.

Note however, that this is only possible where none of the dynamic
features of the language (i.e. bindings to special variables,
@code{unwind-protect}, @code{condition-case}, @code{catch}, etc@dots{})
are currently active in the containing function.

Consider, for example, the following function:

@lisp
(defun print-list (l)
  (unless (null l)
    (format standard-output "%s\n" (car l))
    (print-list (cdr l))))
@end lisp

@noindent
the call to @code{print-list} occurs in the @dfn{tail-position} of the
function. This means that the call may be made after removing the
previous call to @code{print-list} from the interpreter's stack of
active functions.

[ XXX currently the interpreter is incapable of eliminating tail calls
to subrs, i.e. Lisp functions implemented in C ]


@node Macro Call Forms, Special Forms, Function Call Forms, List Forms
@subsubsection Macro Call Forms
@cindex Macro call forms
@cindex Forms, macro call

Macros are source code expansions, the general idea is that a macro
is a function which using the unevaluated arguments applied to it,
computes another form (the expansion of the macro and its arguments)
which is then evaluated to provide the value of the form.

Macros are generally used to implement control-flow operations, where
not all arguments may be evaluated, or evaluated in an unusual order.
For more details see @ref{Macros}.


@node Special Forms, Autoload Forms, Macro Call Forms, List Forms
@subsubsection Special Forms
@cindex Special forms
@cindex Forms, special

Special forms are built-in subroutines which the evaluator knows must
be handled specially. The main difference between a special form and a
function is that the arguments applied to a special form are @emph{not}
automatically evaluated---if necessary the special form will evaluate
arguments itself. This will be noted in the documentation of the
special form.

Special forms are generally used to provide control structures, for
example, the primitive conditional constructs are special forms (if all
of their arguments, including the forms to be conditionally evaluated,
were evaluated automatically this would defeat the object of being
conditional!).

The special forms supported by Librep are: @code{cond},
@code{defvar}, @code{progn}, @code{quote}, @code{setq}.

@defun special-form-p arg
Returns true if @var{arg} is a special form.

@lisp
(special-form-p quote)
    @result{} t
@end lisp
@end defun


@node Autoload Forms, , Special Forms, List Forms
@subsubsection Autoload Forms
@cindex Autoload forms
@cindex Forms, autoload

Not all parts of Librep are needed at once, autoload forms
provide a means of marking that a function (or macro) is contained by a
specific Lisp library. The first time that the function is accessed the
autoload form will be evaluated; this loads the file containing the
function, then re-evaluates the original form. By then the autoload
form will have been overwritten in the symbol's function slot by the
true function (when it was loaded) so the form will execute properly.

For more details see @ref{Autoloading}.


@node Self-Evaluating Forms, Quoting, List Forms, Evaluation
@subsection Self-Evaluating Forms
@cindex Self-evaluating forms
@cindex Forms, self-evaluating
@cindex Forms, constant

The computed value of any form which is not a symbol or a list will
simply be the form itself and the form is said to be a @dfn{self-evaluating
form}.

Usually the only forms to be evaluated in this way will be numbers, strings
and vectors (since they are the only other data types which have read
syntaxes) but the effect is the same for other types of data.

This means that forms you know are self-evaluating do not have to be
quoted to be used as constants (like lists and symbols do).

@lisp
"foo"
    @result{} "foo"
@end lisp

@node Quoting, , Self-Evaluating Forms, Evaluation
@subsection Quoting
@cindex Quoting

As the above sections explain some types of Lisp object have special
meaning to the Lisp evaluator (namely the symbol and list types) this
means that if you want to refer to a symbol or a list in a program you
can't because the evaluator will treat the form as either a variable
reference or a function call respectively.

To get around this Lisp uses an idea called @dfn{quoting}. The special
form @code{quote} simply returns its argument without evaluating it.
For example,

@lisp
(quote my-symbol)
    @result{} my-symbol
@end lisp

@noindent
the @code{quote} form prevents the @code{my-symbol} being treated as a
variable---it is effectively `hidden' from the evaluator.

Writing @samp{quote} all the time would be a bit time-consuming so
there is a shortcut: the Lisp reader treats any form @var{x} preceded
by a single quote character (@samp{'}) as the form @code{(quote
@var{x})}. So the example above would normally be written as,

@lisp
'my-symbol
    @result{} my-symbol
@end lisp

The general way to prevent evaluation of a form is to simply precede it
by a single quote-mark.

@defspec quote form
This special form returns its single argument without evaluating it. This
is used to @dfn{quote} constant objects to prevent them from being
evaluated.
@end defspec

For another form of quoting, see @ref{Backquoting}.


@node Variables, Functions, Evaluation, The language
@section Variables
@cindex Variables

In Lisp, symbols are used to represent variables. Each symbol contains
a @dfn{value} slot that is used to contain the value of the symbol when
it used as a variable.

The normal way to obtain the current value of a variable is simply to
evaluate the symbol of the same name (i.e. write the name of the
variable in your program). The @code{symbol-value} function can be used
to evaluate variables whose names not known statically.

@defun symbol-value variable
This function returns the value of the symbol @var{variable} in
the current environment.
@end defun

@menu
* Local Variables::             Creating temporary variables
* Setting Variables::           Altering a variable's value
* Scope and Extent::            Technical jargon
* Void Variables::              Some variables have no values
* Defining Variables::          How to define a variable before
                                  using it
* Fluid Variables::             Another dynamic binding method
@end menu


@node Local Variables, Setting Variables, , Variables
@subsection Local Variables
@cindex Local variables
@cindex Variables, local

A @dfn{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 @dfn{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 (@pxref{Void
Variables}). Assigning a value to the variable (@pxref{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. See also @xref{Fluid Variables}.

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

@defmac let bindings body-forms@dots{}
@code{let} creates new variable bindings as specified by the
@var{bindings} argument, then evaluates the @var{body-forms} in order.
The bindings are then removed, returning all variables to their state
before the @code{let} statement was entered. The value of the statement
is the value of the implicit @code{progn}.

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

@lisp
(setq foo 42)
    @result{} 42
(let
    ((foo (+ 1 2))
     bar)
  ;; Body forms
  (setq foo (1+ foo))   ;This sets the new binding
  (cons foo bar))
    @result{} (4 . ())
foo
    @result{} 42        ;The original values is back

;; More on scope.
(define a 'outer)
(define (foo) a)

(define (bar)
   (let ((a 'inner)) (foo)))

(bar)
   @result{} outer
;; The let binding is newly established inside of bar,
;; and foo doesn't see it.

;; Difference to defvar.
(defvar a 'outer)
(bar)
   @result{} inner ;; The scope of a is now dynamic.
@end lisp

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

@lisp
(setq foo 42)
    @result{} 42
(let
    ((foo 100)
     (bar foo))
  (cons foo bar))
    @result{} (100 . 42)
@end lisp

@noindent
Although @code{foo} is given a new binding this is not actually done
until all the new values have been computed, hence @code{bar} is
bound to the @emph{old} value of @code{foo}.

The second form, @code{(let function bindings body...)}, can be
used to make a loop. (@pxref{Looping Structures})
@end defmac

@defmac let* bindings body-forms@dots{}
This special form is exactly the same as @code{let} except for one
important difference: the new bindings are installed @emph{as they are
computed}.

You can see the difference by comparing the following example with the
last example in the @code{let} documentation (above),

@lisp
(setq foo 42)
    @result{} 42
(let*                   ;Using @code{let*} this time
    ((foo 100)
     (bar foo))
  (cons foo bar))
    @result{} (100 . 100)
@end lisp

@noindent
By the time the new value of @code{bar} is computed the new binding of
@code{foo} is already active.
@end defmac

@defmac letrec bindings body-forms@dots{}
@code{letrec} is similar to @code{let} and @code{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 @code{letrec}. For example, a local factorial function
(from SICP):

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

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

@lisp
(defun f (x)
  (letrec ((evenp
            (lambda (n)
              (if (= n 0)
                  t
                (oddp (1- n)))))
           (oddp
            (lambda (n)
              (if (= n 0)
                  nil
                (evenp (1- n))))))
    @dots{}
@end lisp
@end defmac


@node Setting Variables, Scope and Extent, Local Variables, Variables
@subsection Setting Variables
@cindex Setting variables
@cindex Variables, setting

@dfn{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, @pxref{Local Variables}).

The @code{setq} special form is the usual method of altering the value
of a variable.

@defspec setq variable form @dots{}
Each @var{variable} is set to the result of evaluating its
corresponding @var{form}. The last value assigned becomes the value of
the @code{setq} form.

@lisp
(setq x 20 y (+ 2 3))
    @result{} 5
@end lisp

@noindent
In the above example the variable @code{x} is set to @code{20} and @code{y}
is set to the value of the form @code{(+ 2 3)} (5).
@end defspec

@defun set variable new-value
The value of the variable @var{variable} (a symbol) is set to
@var{new-value} and the @var{new-value} is returned.

This function is used when the @var{variable} is unknown until
run-time, and therefore has to be computed from a form.

@lisp
(set 'foo 20)
@equiv{}
(setq foo 20)           ;@code{setq} means `set-quoted'
    @result{} 20
@end lisp

@emph{Note:} currently the @code{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 @code{set} function. It is strongly advised to
avoid using this function on lexical bindings! (Moreover the compiler
may generate incorrect code in certain circumstances.)
@end defun


@node Scope and Extent, Void Variables, Setting Variables, Variables
@subsection Scope and Extent
@cindex Scope and extent
@cindex Variables, scope and extent of

In the Librep by default variables have @dfn{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:

@lisp
(let
    ((counter 0))
  (defun count ()
    (setq counter (1+ counter))
    counter))
@end lisp

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

@lisp
(count)
  @result{} 1
(count)
  @result{} 2
@end lisp

An alternative method of scoping variables is also available. Any
variables declared using the @code{defvar} special form are said to be
@dfn{special} variables, they have @dfn{indefinite scope} and
@dfn{dynamic extent}, often simplified to @dfn{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. Special variables are stored in a
separate namespace. 

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

@lisp
(defvar *foo-var* nil)

(defun foo (x)
  (let
      ;; a dynamically-scoped binding
      ((*foo-var* (* x 20)))
    (bar x)
    @dots{}

(defun bar (y)
  ;; Since this function is called from
  ;; the function @code{foo} it can refer
  ;; to @code{*foo-var*}
  (setq y (+ y *foo-var*))
  @dots{}
@end lisp

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

@defun special-variable-p symbol
Returns t if @var{symbol} is a special variable (dynamically scoped).
@end defun

@node Void Variables, Defining Variables, Scope and Extent, Variables
@subsection Void Variables
@cindex Void variables
@cindex Variables, void

A variable which has no value is said to be @dfn{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.

@defun boundp symbol
Returns true if @var{symbol} is bound to a variable.
@end defun

@defun makunbound symbol
This function makes the current binding of @var{symbol} as a variable be
void, then returns @var{symbol}.

@lisp
(setq foo 42)
    @result{} 42
foo
    @result{} 42
(boundp 'foo)
    @result{} t
(makunbound 'foo)
    @result{} foo
(boundp 'foo)
    @result{} ()
foo
    @error{} Value as variable is void: foo
@end lisp
@end defun

@node Defining Variables, Fluid Variables, Void Variables, Variables
@subsection Defining Variables
@cindex Defining variables
@cindex Variables, defining

The special forms @code{define}, @code{defvar} and @code{defconst}
allow you to define the global variables that will be used by a
program.

@defmac define variable form
Defines a lexically scoped global variable called @var{variable}. It
will have the result of evaluating @var{form} assigned to it.

Note that the @code{define} special form may also be used to declare
block-structured functions, @ref{Definitions}.
@end defmac

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

If the @var{doc-string} argument is defined it is a string documenting
@var{variable} (@pxref{Docstrings}).

@lisp
(defvar *my-variable* '(x y)
  "This variable is an example showing the usage of the @code{defvar}
special form.")
    @result{} *my-variable*
@end lisp

Don't use @code{defvar} if @code{define} suffices. For the reason,
see @xref{Modules and Special Variables}.
@end defspec

@defmac defvar-setq var @t{#!optional} value doc
It's @code{defvar} + @code{setq}, so defines @var{var} as a special
variable, and sets the value to @var{value}.
@end defmac

@defmac define-special-variable var @t{#!optional} value doc
Same as @code{defvar-setq} above. A very confusing name, so it's
deprecated now.
@end defmac

@defmac defconst constant form [doc-string]
@code{defconst} defines a global constant, the symbol @var{constant}.
Its value is set to the result of evaluating @var{form}. Note that
unlike @code{defvar} the value of the symbol is @emph{always} set, even
if it already has a value.

The @var{doc-string} argument, if defined, is the documentation string
for the constant.

@lisp
(defconst the-answer 42
  "An example constant.")
    @result{} the-answer
@end lisp
@end defmac


@node Fluid Variables, , Defining Variables, Variables
@subsection Fluid Variables
@cindex Fluid variables
@cindex Variables, fluid

Special variables have a number of drawbacks, especially when used in
conjunction with the module system (@pxref{Modules and Special
Variables}). As a consequence of these drawbacks, @code{rep} provides a
second method of implementing dynamically scoped variables, known as
@dfn{fluid variables}, or just @dfn{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.

@defun make-fluid @t{#!optional} value
Create and return a new fluid, it will have an initial binding of
@var{value} (or false if @var{value} is undefined).
@end defun

@defun fluid fluid
Return the value of the most recently created binding of the fluid
variable object @var{fluid}.
@end defun

@defun fluid-set fluid value
Set the value of the most recently created binding of the fluid
variable object @var{fluid} to @var{value}.
@end defun

@defun with-fluids fluids values thunk
Call the zero parameter function @var{thunk} (and return the value that
it returns) with new bindings created for each of the fluid variables
specified in the list @var{fluids}.

For each member of @var{fluids} the corresponding member of the
@var{values} list provides the initial value of the new binding.

If the lists @var{fluids} and @var{values} are not of the same length,
an error is signalled.
@end defun

@defmac let-fluids bindings body @dots{}
A convenient wrapper around @code{with-fluids}, similar to the
@code{let} syntax.

The list @var{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 @var{body @dots{}}
forms are evaluated, and the bindings removed. The value of the last of
the @var{body @dots{}} forms is returned.
@end defmac

Here is an example code fragment using fluid variables and
@code{let-fluids}:

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

(let-fluids ((a 1)
             (b 2))
  (+ (fluid a) (fluid b))) @result{} 3

;; Compare with let.
(define c 'outer)
(define (foo) c)

(define (bar)
   (let ((c 'inner)) (foo)))

(bar)
   @result{} outer
;; The let binding is newly established inside of bar,
;; and foo doesn't see it.
@end lisp

@node Functions, Macros, Variables, The language
@section Functions
@cindex Functions

A @dfn{function} is a Lisp object which, when applied to a sequence of
argument values, produces another value---the function's
@dfn{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 (@pxref{Special Forms}) and macros
(@pxref{Macros}) are @emph{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: @dfn{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
@dfn{subr}. All other functions are defined in Lisp.

@defun functionp object
Returns true if @var{object} is a function (i.e. it can be used
as the function argument of @code{funcall}.

@lisp
(functionp set)
    @result{} t

(functionp setq)
    @result{} ()

(functionp (lambda (x) (+ x 2)))
   @result{} t
@end lisp
@end defun

@defun subrp arg
Returns true is @var{arg} is a primitive subroutine object.
@end defun

@defun subr-name subr
Returns a string naming the primitive subroutine @var{subr}.
@end defun

@menu
* Lambda Expressions::          Structure of a function object
* Closures::                    Function core
* Defining Named Functions::    Usual way of function definition
* Predicate Functions::         Functions which return boolean values
* Local Functions::             Binding functions temporarily
* Calling Functions::           Functions can be called by hand
* Mapping Functions::           Map a function to the elements of a list
@end menu


@node Lambda Expressions, Closures, , Functions
@subsection Lambda Expressions
@cindex Lambda expressions
@cindex Functions, lambda expressions

@dfn{Lambda expressions} are used to create functions from other Lisp
objects. A lambda expression is a list whose first element is the
symbol @code{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:

@lisp
(lambda @var{lambda-list} [@var{doc}] [@var{interactive-declaration}] @var{body-forms}@dots{} )
@end lisp

@noindent
Where @var{lambda-list} is a list defining the formal parameters of the
function, @var{doc} is an optional documentation string (@pxref{Docstrings}),
and @var{body-forms} is the sequence of forms making up
the function body, evaluated using an implicit @code{progn}.

@var{interactive-declaration} is an obsolete feature, only required by
interactive commands@footnote{Only used when Librep is
embedded within another application.}.

The @var{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 @code{(x y)} defines two
parameters, @code{x} and @code{y}. When called with two arguments the
first will be bound to the variable @code{x}, the second to @code{y}.
When used in a full lambda expression this looks like:

@lisp
(lambda (x y) (+ x y))
@end lisp

@noindent
this evaluates to an anonymous function with two parameters, @code{x}
and @code{y}, which when called evaluates to their sum. More on
evaluation is described in the next section, @xref{Closures}.

There are several @dfn{lambda-list keywords} which modify the meaning
of symbols in the lambda-list. The syntax of the lambda list is:

@lisp
([@var{required-parameters}@dots{}]
 [#!optional @var{optional-parameters}@dots{}]
 [#!key @var{keyword-parameters}@dots{}]
 [#!rest @var{rest-parameter} | . @var{rest-parameter}])
@end lisp

@noindent
Each lambda list keyword is a symbol whose name begins @samp{#!}, they
are interpreted as follows:

@table @code
@item #!optional
All variables following this keyword are considered @dfn{optional} (all
variables before the first keyword are @dfn{required}: an error will be
signalled if a required argument is undefined in a function call).

@var{optional-parameters} may either be of the form @code{@var{symbol}}
or of the form @code{(@var{symbol} @var{default})}. If no argument is
supplied for this parameter the @var{default} form is evaluated to give
the bound value@footnote{The @var{default} form is evaluated in the
environment of the closure being called, but without any of the
bindings created by the lambda expression.}. If no @var{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.

@lisp
((lambda (#!optional a b) (list a b)))
    @result{} (() ())
((lambda (#!optional a b) (list a b)) 1)
    @result{} (1 ())
((lambda (#!optional a b) (list a b)) nil 1)
    @result{} (() 1)
((lambda (#!optional (a 1)) (list a)))
    @result{} (1)
((lambda (#!optional (a 1)) (list a)) 2)
    @result{} (2)
@end lisp

@item #!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 @samp{#:@var{symbol}}.

As with optional parameters, default values may be supplied through the
use of the @code{(@var{symbol} @var{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 @code{(a #!key b c)} accepts one required
argument, and two optional keyword arguments. The variable @code{a}
would be bound to the first supplied argument; the variable @code{b}
would be bound to the argument preceded by the keyword @code{#:b}, or
@code{()} 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.)

@lisp
((lambda (a #!key b c) (list a b c))
 1 2 3)
    @result{} (1 () ())
((lambda (a #!key b c) (list a b c))
 1 #:b 2 3)
    @result{} (1 2 ())
((lambda (a #!key b c) (list a b c))
 1 #:b 2 #:c 3)
    @result{} (1 2 3)
((lambda (a #!key b c) (list a b c))
 1 #:c 3 #:b 2)
    @result{} (1 2 3)
@end lisp

@item #!rest
The @code{#!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 @code{#!rest}
keyword. For example, in

@lisp
(lambda (x #!rest y) @dots{})
@end lisp

@noindent
the first argument, @code{x}, is required. Any other arguments applied
to this function are made into a list and this list is bound to the
variable @code{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:

@lisp
(lambda (x . y) @dots{})
@end lisp
@end table

When a function represented by a lambda-list is called the first action
is to bind the argument values to the formal parameters. The
@var{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 @var{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.

@node Closures, Defining Named Functions, Lambda Expressions, Functions
@subsection Closures
@cindex Closure
@cindex Anonymous functions
@cindex Functions, anonymous

A lambda expression itself is @emph{not} a function; it must be
associated with its module, or more correctly a lexical environment.
This conjunction is called a ``closure''; it is the closure that
may be called as a function. 

Evaluation turns a lambda expression to its closure. Consider the
following example:

@lisp
(lambda (x) (1+ x))
    @result{}#<closure 1780f10 @@ module.foo> 
    ;; Anonymous closure is printed with internal pointer value.

(functionp (lambda (x) (1+ x)))
    @result{} t

(functionp '(lambda (x) (1+ x)))
    @result{} ()
@end lisp

A closure can access bindings which belong to the same module as the
closure. A closure can also have its own private bindings. (They're
hidden from the outside, thus ``closure''.)

N.B. It seems that @code{define} in a closure which is not top-level
creates a binding in the closure's module, NOT inside of the closure.

@lisp
(define (count-0)
  (define val 0)
  (setq val (1+ val)))

(count-0)
    @result{} 1
(count-0)
    @result{} 1
;; Each time `define' resets the value to 0.

(define (count)
  (unless (boundp 'val)
    (define val 0))
  (setq val (1+ val)))

(count)
    @result{} 1
(count)
    @result{} 2 ;; Ok, but
val
    @result{} 2 ;; Not invisible.
@end lisp

@defun closurep arg
Returns true if @var{arg} is a closure.
@end defun

@defun closure-name fun
Returns the name of closure @var{fun}, a string. Or if it's unnamed,
@code{nil}.
@end defun

@defun closure-structure fun
Returns the structure @var{fun} belongs to.
@end defun

@defun set-closure-structure closure structure
Sets the structure @var{closure} belongs to to @var{structure}.
@end defun

It is often useful to pass a function @emph{definition} to other
functions, instead of function's name, especially for example to
@code{mapc} or @code{delete-if}. It is called an ``anonymous
function'', and a lambda expression is all what's needed.

The following example removes all elements from the @var{list} which
are even and greater than 20.

@lisp
(setq @var{list} (delete-if (lambda (x)
                        (and (zerop (% x 2)) (> x 20)))
                      @var{list}))
@end lisp

There're some low-level closure handling functions. For example, in
certain cases it may be necessary to create a non-constant function,
for example by using backquoting (@pxref{Backquoting}). In these cases
the @code{make-closure} function may be used to create a function
object from a lambda expression.

@defun make-closure arg
Return the closure of @var{arg} and the current lexical environment.
@end defun

@defun closure-function closure
Returns the function object associated with the lexical closure
@var{closure}.
@end defun

@defun set-closure-function closure function
Sets the function value of @var{closure} to @code{function}.
@end defun

@lisp
(define (foo) 'foo-sym)
(define (bar) 'bar-sym)
(set-closure-function foo (closure-function bar))
(foo)
    @result{} foo-sym
@end lisp

@node Defining Named Functions, Predicate Functions, Closures, Functions
@subsection Defining Named Functions
@cindex Defining named functions
@cindex Functions, defining

Functions can be defined by the @code{defun} special form. However
@code{define} is the more preferred way. (@pxref{Definitions}.)

@defmac defun name lambda-list body-forms@dots{}
@code{defun} initialises the function definition of the symbol
@var{name} to the lambda expression resulting from the concatenation of
the symbol @code{lambda}, @var{lambda-list} and the @var{body-forms}.

The @var{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 (@pxref{Lambda Expressions}).
@end defmac

An example function definition taken from the Librep source code is:

@lisp
(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))
@end lisp


@node Predicate Functions, Local Functions, Defining Named Functions, Functions
@subsection Predicate Functions
@cindex Predicate functions
@cindex Boolean values, predicate functions

In Lisp, a function which returns a boolean `true' or boolean `false'
value is called a @dfn{predicate}. As is the convention in Lisp a value
of @code{()} means false, anything else means true. The symbols
@code{nil} and @code{t} are often used to represent constant false and
true values (@pxref{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
@samp{p} or @samp{-p} string. The @samp{p} variant is used when the
first string does not contain any hyphens.

For example, the predicate to test for the quality @dfn{const-variable}
(a variable which has a constant value, @pxref{Defining Variables}) is
called @code{const-variable-p}. On the other hand the predicate to test
for the quality @dfn{cons} (a Cons cell) is called @code{consp}.


@node Local Functions, Calling Functions, Predicate Functions, Functions
@subsection Local Functions
@cindex Local functions
@cindex Functions, local

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

For example,

@lisp
(let
    ((temporary-function (lambda (x)
                           (+ x 42))))
  @dots{}
  (temporary-function 20)
  @dots{}
@end lisp

@node Calling Functions, Mapping Functions, Local Functions, Functions
@subsection Calling Functions
@cindex Calling functions
@cindex Functions, calling

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.

@defun funcall function @t{#!rest} args
Applies the argument values @var{args} to the function @var{function}, then
returns its result.
@end defun

@defun apply function @t{#!rest} args
Similar to @code{funcall} except that the last of its arguments is
a @emph{list} of arguments which are appended to the other members of
@var{args} to form the list of argument values to apply to the
function @var{function}.
@end defun

@lisp
(apply + 1 '(2 3))
    @result{} 6

(apply + (make-list 1000000 1))
    @result{} 1000000
@end lisp

@node Mapping Functions, , Calling Functions, Functions
@subsection Mapping Functions
@cindex Mapping functions
@cindex Functions, mapping
@cindex Lists, mapping

A @dfn{mapping function} applies a function to each of a collection of
objects. Librep currently has two mapping functions,
@code{mapcar} and @code{mapc}.

@defun mapcar function list
Each element of @var{list} is individually applied to the function
@var{function}. The values returned are made into a new list which is
returned.

The @var{function} must accept a single argument value.

@lisp
(mapcar 1+ '(1 2 3 4 5))
    @result{} (2 3 4 5 6)
@end lisp
@end defun

@defun mapc function list
Similar to @code{mapcar} except that the values returned when each
element is applied to the function @var{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:

@lisp
(mapc (lambda (x)
        (print x standard-error)) list)
@end lisp
@end defun

The two following functions are also mapping functions of a sort. They
are variants of the @code{delete} function (@pxref{Modifying Lists})
and use predicate functions to classify the elements of the list which
are to be deleted.

@defun delete-if predicate list
This function is a variant of the @code{delete} function. Instead of
comparing each element of @var{list} with a specified object, each
element of @var{list} is applied to the predicate function
@var{predicate}. If it returns true then the
element is destructively removed from @var{list}.

@lisp
(delete-if stringp '(1 "foo" 2 "bar" 3 "baz"))
    @result{} (1 2 3)
@end lisp
@end defun

@defun delete-if-not predicate list
This function does the inverse of @code{delete-if}. It applies
@var{predicate} to each element of @var{list}, if it returns false
then the element is destructively removed from the list.

@lisp
(delete-if-not stringp '(1 "foo" 2 "bar" 3 "baz"))
    @result{} ("foo" "bar" "baz")
@end lisp
@end defun

@defun remove-if pred list
@defunx remove-if-not pred list
Same as @code{delete-if} / @code{delete-if-not} respectively, but
returns a new copy, instead of destructively. Defined in
@code{rep.data}.
@end defun

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

@defun filter predicate list
Return a new list, consisting of the elements in @var{list} which the
function @var{predicate} returns true when applied to. This
function is equivalent to:

@lisp
(mapcar nconc (mapcar (lambda (x)
                        (and (@var{predicate} x) (list x)))
                      @var{list}))
@end lisp
@end defun


@node Macros, Definitions, Functions, The language
@section Macros
@cindex Macros

@dfn{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 @code{when} macro (@pxref{Conditional Structures})
implements a new conditional operation by transforming its arguments
into a @code{cond} statement. That is,

@lisp
(when @var{condition} @var{form} @dots{})
    @expansion{} (cond (@var{condition} @var{form} @dots{}))
@end lisp

Since macros do not evaluate their arguments, instead just transforming
them, they may be expanded at @emph{compile-time}. The resulting form
is then compiled as usual.

@defun macrop arg
Returns true if @var{arg} is a macro object.
@end defun

@menu
* Defining Macros::             Macros are defined like functions
* Backquoting::                 Creating macros from templates
* Macro Expansion::             How macros are used by the evaluator
* Compiling Macros::            The compiler expands macros at compile-
                                  time.
@end menu


@node Defining Macros, Backquoting, , Macros
@subsection Defining Macros
@cindex Defining macros
@cindex Macros, defining

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 @code{macro}, its
cdr is the function which creates the expansion of the macro when
applied to the macro calls unevaluated arguments.

@defmac defmacro name lambda-list body-forms@dots{}
Defines the macro stored in the function cell of the symbol @var{name}.
@var{lambda-list} is the lambda-list specifying the arguments to the
macro (@pxref{Lambda Expressions}) and @var{body-forms} are the forms
evaluated when the macro is expanded. The first of @var{body-forms}
may be a documentation string describing the macro's use.
@end defmac

Here is a simple macro definition, it is the definition of the
@code{when} macro shown in the previous section.

@lisp
(defmacro when (condition #!rest body)
  "Evaluates @var{condition}, if it's true evaluates the @var{body}
forms."
  (list 'cond (list* condition body)))
@end lisp

@noindent
When a form of the type @code{(when @var{c} @var{b} @dots{})} is
evaluated the macro definition of @code{when} expands to the form
@code{(cond (@var{c} (progn @var{b} @dots{})))} which is then evaluated
to perform the @code{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.


@node Backquoting, Macro Expansion, Defining Macros, Macros
@subsection Backquoting
@cindex Backquoting
@cindex Macros, 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 (@pxref{Quoting}), here another form of quoting is
described, where only some of the quoted object is actually constant.
This is known as @dfn{backquoting}, since it is introduced by the
backquote character @samp{`}, a shortcut for the @code{backquote}
macro.

@defmac backquote arg
Constructs a new version of @var{arg} (a list). All parts of @var{list}
are preserved except for expressions introduced by comma (@samp{,})
characters, which are evaluated and spliced into the list. For example:

@lisp
`(1 2 ,(+ 1 2))
    @result{} (1 2 3)
@end lisp

Also, the @samp{,@@} prefix will splice the following @emph{list} into
the output list, at the same level:

@lisp
`(1 2 ,@@(list 3))
    @result{} (1 2 3)
@end lisp
@end defmac

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

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

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


@node Macro Expansion, Compiling Macros, Backquoting, Macros
@subsection Macro Expansion
@cindex Macro expansion
@cindex Expansion, of macros

When a macro call is detected (@pxref{List Forms}) the function which
is the cdr of the macro's definition (@pxref{Defining Macros}) is
applied to the macro call's arguments. Unlike in a function call, the
arguments are @emph{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.

@defun macroexpand form @t{#!optional} environment
If @var{form} is a macro call @code{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 @var{environment} argument is a function to call to do the
actual expansion.

@lisp
(defmacro when (condition #!rest body)
  "Evaluates @var{condition}, if it's true evaluates the @var{body}
forms."
  (list 'if condition (cons 'progn body)))
    @result{} when

(macroexpand '(when x (setq foo bar)))
    @result{} (cond (x (progn (setq foo bar))))
@end lisp

While a macro is being expanded, the special variable
@code{macro-environment} is bound to value of the @var{environment}
parameter in the containing call to @code{macroexpand}. This allows
macros to expand inner macros correctly.
@end defun

@defun macroexpand-1 form @t{#!optional} environment
Similar to @code{macroexpand}, but only a single macro expansion is
ever performed, i.e. if @var{form} is a macro call the result of
expanding that call will be returned, otherwise @var{form} is returned.

@lisp
(macroexpand-1 '(when x (setq foo bar)))
    @result{} (if x (progn (setq foo bar)))
@end lisp
@end defun


@node Compiling Macros, , Macro Expansion, Macros
@subsection Compiling Macros
@cindex Compiling macros
@cindex Macros, compiling

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 @code{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:

@itemize @bullet
@item
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).

@item
Macros which are defined by another file must be loaded so they can be
recognised. Use the @code{require} function, the compiler will evaluate
any @code{require} forms it sees loading any macro definitions used.
@end itemize

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


@node Definitions, Modules, Macros, The language
@section Block-Structured Definitions
@cindex Block structured definitions
@cindex Definitions, block structured
@cindex Functions, block structured

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 @code{define} statement. It allows block-structured
programs to be defined intuitively.

The @code{define} originates in Scheme.

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

@lisp
(defun foo (x) (1+ x))

(define (foo x) (1+ x))
@end lisp

@noindent
But note the different position of the parentheses. This is because
@code{define} may also be used to define (lexical)
variables. (@pxref{Defining Variables}) Hence the following is also
equivalent:

@lisp
(define foo (lambda (x) (1+ x)))
@end lisp

However this is the most uninteresting aspect of @code{define}. More
interesting is that it allows @dfn{internal definitions}.

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

@lisp
(define (foo x)
  (define (bar)
    (* x 42))
  (1+ (bar)))
@end lisp

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

@defmac define name form
@defmacx define (name . args) body-forms@dots{}
Define a global lexical variable called @var{name}, whose value will be
set to @var{form}.

If the first argument to the macro is a list, then a function is
defined whose name is @var{name} and whose formal parameters are
specified by @var{args}. The body of the function is defined by the
@var{body-forms}. The body forms have any macros expanded, and are
scanned for internal definitions (at the start of the body of
@code{let}, @code{let*}, @code{lambda} special forms)
@end defmac

@defmac define-macro name form
@defmacx define-macro (name . args) body-forms@dots{}
Similar to @code{define}, except that it creates a macro definition
(@pxref{Macros}).
@end defmac

@defmac with-internal-definitions body-forms
Recursively expand macros in @var{body-forms}, while scanning out any
internal definitions into @code{letrec} statements.
@end defmac


@node Modules, Control Structures, Definitions, The language
@section Modules
@cindex Modules

In Rep, ``module'' and ``structure'' are synonyms.

@menu
Introductions
* Informal Module Introduction::
* Introduction on Modules::

Module basics
* Simple Module Definition::
* Module and File::
* Using Other Modules::
* Modules and Special Variables::
* Module Functions::
* Implicit Exports::

Formal aspects
* Module Definition::
* Module Interfaces::
* Obsolete Aspects of Modules::  Emacs-like obsolete features.
@end menu

Some functions are not yet covered. For them, obtain the source,
and read @file{src/structures.c}.

@node Informal Module Introduction, Introduction on Modules, , Modules
@subsection Informal Module Introduction
This is a quick but informal introduction on Rep module system.

What's a module? First, a module is identified by its name. Each has
its local bindings, i.e. variables and functions. (Remember that
functions can be stored in variables.) Local bindings can be referred
to inside of the module. And a module can specify which bindings are
``exported'', that is, visible to outer worlds.

Ok, so let's use an existing module. How can it be done? To load a
module dynamically, use @code{require}:
@lisp
(require 'rep.util.time) ;; Module name is a symbol
@end lisp

Looks like Elips, but forget it; Elisp doesn't have the module system.
There's no @code{provide} in modules.

In fact, two things are done by @code{require}. First, the module is
loaded into the Rep if it's not yet, and second, the bindings declared
to be ``exported'' are imported to the current module.

Current module? Yes, the current module always exists. If you're using
the REPL, then it's @code{user} module. Also the module which the REPL
of @code{sawfish-client} and Sawfish's @file{~/.sawfish/rc} dwell is
called @code{user}.

When you want to use, say @code{rep.util.time} from another
module, then you have to call @code{require} again from there.

In this manual, the module in which a function is defined is
explicitly shown. If any module isn't named, then you don't have
to @code{require} any. (In fact, @code{rep} module is necessary,
but you can forget it now.)

If you look at @file{/usr/share/rep/x.y.z/lisp/rep/util/time.jl},
then it exports for example @code{seconds->time}. Now you can call it.

@lisp
(seconds->time (* 3600 72))
  @result{} (3 . 0) ;; Cons of days and the rest in seconds.
@end lisp

The file @file{time.jl} is a good example, because it's small. Please
have a look at it. You now know how to define a module. In the
@code{open} clause, you declare which modules you import to that
module. @code{require} is a usual function, but @code{open}
is only used in the definition of a module. @code{time} module opens
only one module, @code{rep}.

In a module definition, first comes @code{define-structure} (``structure''
is a synonym for ``module''), then @code{export}, and @code{open}. After
them come usual expressions, and they're evaluated in that module. You
can put there anything, not limited to @code{define}s.

@subsubheading Module name and file name
How does a module name corresponds to a file name? When loading,
modules are searched from @code{load-path}. If you're using Sawfish
in a Unix, its first element is @file{~/.sawfish/lisp}, the second
@file{/usr/share/sawfish/<version>/lisp}, and so on.

Now assume @code{load-path} is @code{(a b)}. When you require the
module @code{foo.bar}, then @file{a/foo/bar.jl} is tried e.g. in Unix,
since the directory separator is a slash '/', and if it exists, it's
loaded. If not, @file{b/foo/bar.jl} is tried.  If it fails, an error
is signaled.

A good news. If there're both a byte compiled file and a plain lisp
source, and if the compiled one is older, then the source is loaded.
In short, always the newer one is used.

@node Introduction on Modules, Simple Module Definition, Informal Module Introduction, Modules
@subsection Introduction on Modules

What's modules in general? When writing a large program, it is
important to break up it into separate components, or modules, and
encapsulate so that undesirable interference between modules are avoided.

In Rep, modules may be anonymous or named. 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.

An @dfn{interface} of a structure declares the module's bindings
that may be accessed by other modules. Each module also lists the
other modules whose bindings it may reference.

Rep's module system is inspired by the Scheme48, Xerox Scheme and
Standard ML module systems.

@node Simple Module Definition, Module and File, Introduction on Modules, Modules
@subsection Simple Module Definition

In its simplest form, a module definition looks like this:

@lisp
(define-structure simple.test
    (export foo
            bar)
    (open rep  ;; Make it rule to open `rep' always.
          rep.structures)
  (define (foo x) (* x 42))
  (define (bar x) (baz x (foo x))
  (define (baz x y) (+ (foo x) (1+ y)))
  (format standard-error "Module %s defined!" (current-structure))
)
@end lisp

This module has the name @code{simple.test}.  Then it ``exports'' two
bindings, @code{foo} and @code{bar}, functions in this case. It also
declare to use modules @code{rep} and @code{rep.structures}. The
entire order is fixed; first @code{export}, then @code{open}, and the
rest.

Always make it rule to open @code{rep} structure. It's because Librep
used to offer alternative Lisps, for example Scheme mimicry by
importing @code{scheme} structure, instead of @code{rep} module.

Then comes the body. They're evaluated when @code{define-structure} is
evaluated, @emph{inside} of this module. It defines three functions,
and it emits a message to stderr. The third function @code{baz} is
not exported, so it can't be seen outside of this module.

The function @code{current-structure} is defined in
@code{rep.structures}, and it can be used in this module because 
@code{rep.structures} was opened.

@node Module and File, Using Other Modules, Simple Module Definition, Modules
@subsection Module and File

A module can be defined anywhere, in any lisp expression, but usually
it only makes sense if the module @code{foo.bar.baz} is defined in a
file like @file{<prefix>/foo/bar/baz.jl}, and you don't put anything
other than the module definition in that file. Periods in module name
are converted to directory separator, in Unix a slash '/'.

Rep modules are searched from directories specified in
@code{load-path}. Files can be byte-compiled, and usually they have a
suffix @code{.jlc}, instead of @code{.jl} for plain Lisp source.

The variable @code{load-path} and suffixes are fully described in
@xref{Load Function}.

@node Using Other Modules, Modules and Special Variables, Module and File, Modules
@subsection Using Other Modules

We've already seen one way to use other module in the previous
subsection. It was @code{open}.

There're three aspects in module access: 
@itemize
@item Loading of a module to Rep,
@item How are that module's bindings are referred to from the current module,
@item And doing these things on the fly, as usual lisp expressions, not only in module definitions.
@end itemize

We'll see these three in turn.

Function @code{load} loads any file, not only module definitions,
and evaluate each form in it, but @code{load} does NOT import
bindings. For the full doc, see @xref{Load Function}.

We've seen @code{open} clause. If specified modules are not yet loaded
into Rep, then they're loaded. It also imports exported bindings.

The alternative, @code{access} is available, too. With @code{access},
exported bindings can be referred to by specifying the module it
belongs to:

@lisp
;; These three are equivalent
(structure-ref mod.foo.bar varX)
mod.foo.bar#varX ;; short form of structure-ref
(external-structure-ref 'mod.foo.bar 'varX)
@end lisp

One of @code{open} or @code{access} clauses can only be used at
the module definition, but there're equivalent lisp functions.
@code{require} and @code{open-structures} correspond to @code{open},
and @code{access-structures} to @code{access}:

@defun require module
@defunx open-structures list
@defunx access-structures list
Example:
@lisp
(require 'foo.bar)
(open-structures '(foo.bar baz))
(access-structures '(foo.bar baz))
@end lisp

All loads modules to Rep if not yet, and import the bindings of
specified modules, in the same way as @code{open} or @code{access}.
The latter two are defined in @code{rep.structures}.

If the load fails, an error is signaled.
@end defun

@node Modules and Special Variables, Module Functions, Using Other Modules, Modules
@subsection Modules and Special Variables
@cindex Modules, and special variables

As described earlier, @code{defvar} creates dynamically scoped
variables, or special variables. (@pxref{Defining Variables}.)
They do not fit well with the lexically scoped module system described
here.

This means special variable definition must avoid clashing of name
with those declared in other modules. The usual convention is to
prefix the variable name with a unique string derived from the module
name.

In fact, it is often advisable to avoid using special variables as
much as possible. An alternative 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.  @xref{Fluid
Variables}.

@node Module Functions, Implicit Exports, Modules and Special Variables, Modules
@subsection Module Functions

In this section basic module functions are explained. All are defined
in @code{rep.structures}. Functions related to contruction of modules
are described in following sections.

@defun structurep str
Returns @code{t} if @var{str} is a Lisp structure object.
@end defun

@defun current-structure
Returns the current structure.
@end defun

Evaluation of a lisp expression can be done in any module you specify,
not only in the current module, with the function
@code{eval}. (@pxref{Evaluation}.)

Structure's name is a symbol.

@defun structure-name str
Returns the name of a structure @code{str}.
@end defun

@defun get-structure name
Returns the structure called @var{name}, or @code{nil} if no such
structure exists.
@end defun

@defun intern-structure name
Returns the structure called @var{name}, or if one doesn't exist,
attempts to load it.

This is a kind of mixture of @code{require} and @code{load}; the
grammar is that of @code{require}, but it doesn't import any.
@end defun

These functions are related to opening other modules.

@defun structure-imports str
@defunx structure-accessible str
Returns the list of modules @code{str} has opened or accesses.
@end defun

There's a function for bindings.

@defun structure-exports-p str sym
Returns non-nil if the structure @var{structure} exports a binding
of the symbol @var{sym}. More specifically, it returns the symbol
@code{local} if @var{structure} defines it, and returns the symbol 
@code{external} if it exports but does not define it.
@end defun

Functions @code{open-structures} and @code{access-structures} are
explained in @xref{Using Other Modules}.

@node Implicit Exports, Module Definition, Module Functions, Modules
@subsection Implicit Exports
@cindex Implicit Exports
@cindex Exports, implicit

If you inspect the Librep source, you may find for example, the
function @code{caar} is defined in @code{rep.data} module, but you can
call it without importing.

It's because @code{rep} module exports some functions on behalf of
their modules. To name all, they are: @code{rep.data},
@code{rep.io.streams}, @code{rep.lang.debug},
@code{rep.lang.interpreter}, @code{rep.lang.math},
@code{rep.lang.symbols}, @code{rep.module-system}, and
@code{rep.vm.interpreter}.

The interactive environment pulls in a bit more. (@xref{Interactive
environment}.)

@node Module Definition, Module Interfaces, Implicit Exports, Modules
@subsection Module Definition
@cindex Modules, definition of

Formally, module definition needs an ``interface'', a ``config'' and
the body. An interface declares which bindings are exported,
and a config is either usually an @code{open} or @code{access} clause.

@defmac define-structure name interface config body@dots{}
@defmacx structure interface config body@dots{}
These special forms each create a new module with interface
@var{interface} and configuration @var{config}. The full syntax
of an interface is described in the next section. @code{structure}
defines an anonymous structure.

After configuring the module as specified, the sequence of forms
@var{body@dots{}} is evaluated; it should include the definitions
required by the interface that the module has promised to implement.

The @var{config} form is either a list of configuration clauses, or a
single configuration clause. Each such clause must be of the following
syntax:

@example
@var{clause} -> (open @var{name} @dots{})
       |  (access @var{name} @dots{})
@end example

@noindent
Each @var{name} specifies the name of a module.
@end defmac

Always make it rule to open @code{rep} structure. It's because Librep
used to offer Scheme mimicry by importing @code{scheme} structure.

As described in the section @code{Module and File}, it only
makes sense if a module is defined in a file with an appropriate
path.

Here is an example module definition, defining a module named
@code{test} that exports two functions @code{foo} and @code{bar}.

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

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

@defmac define-structures ((name interface) @dots{}) config body@dots{}
Create a module for each @code{(@var{name} @var{interface})} pair. The
module is called @var{name} and exports the interface defined by
@var{interface}.

The @var{config} and @var{body@dots{}} forms are as in
@code{define-structure}.

Here is a trivial example:

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

@noindent
the underlying environment has three bindings. Each created module
exports two of these.
@end defmac

@node Module Interfaces, Obsolete Aspects of Modules,Module Definition, Modules
@subsection Module Interfaces
@cindex Modules, interfaces

Module's interface is 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:

@example
@var{interface} -> (export @var{id} @dots{})
          |  @var{name}
          |  (compound-interface @var{interface} @dots{})
          |  (structure-interface @var{module-name})
@end example

@noindent
where each @var{id} is the name of a binding to export, and each
@var{name} is the name of an interface previously defined using
@code{define-interface}.

@defmac define-interface name interface
Associate the symbol @var{name} with the module interface
@var{interface} (using one of the forms listed above.
@end defmac

Here is an example defining an interface called @code{foo}:

@lisp
(define-interface foo (compound-interface bar (export baz quux)))
@end lisp

@noindent
It includes the interface called @code{bar} and adds two extra exported
symbols: @code{baz} and @code{quux}.

@defun structure-interface str
returns the interface of structure object @var{str}.
@end defun

@defun set-interface str int
Set the interface of structure object @var{str} to @var{int}.
@end defun

@node Obsolete Aspects of Modules, , Module Interfaces , Modules
@subsection Obsolete Aspects of Modules
@cindex Obsolete Aspects of Modules
@cindex Features

Ususally you can skip this section which describes obsolete, but still
in effect aspects of Rep modules.

Modules marked as already imported into the current module is called
@code{feature}s. Function @code{require} imports a module only when its
feature is absent.

@defvar features
A list of the features, i.e. module names marked as imported into the
current module. Each is a symbol.
@end defvar

@defun featurep feature
Returns true if the feature @var{feature} has been loaded
into the current module.
@end defun

@defun provide feature
Don't use this function unless you're sure. Usually you don't need it.

This function adds @var{feature} (a symbol) to the list of loaded
features. A call to this function is normally one of the top-level
forms in a file.
@end defun

@node Control Structures, Threads, Modules, The language
@section Control Structures
@cindex Control Structures

Control structures are special forms or macros that control
@emph{which} forms get evaluated, @emph{when} they get evaluated and
the @emph{number} of times to evaluate them. This includes conditional
structures, loops, etc@dots{}

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

@menu
* Sequencing Structures::       Evaluating several forms in sequence
* Conditional Structures::      Making decisions based on truth values
* Looping Structures::          `while' loops
* Non-Local Exits::             Exiting from several levels of evaluation
* Continuations::               Capturing the call stack
@end menu


@node Sequencing Structures, Conditional Structures, , Control Structures
@subsection Sequencing Structures
@cindex Sequencing structures
@cindex Control structures, sequencing

Each of the special forms in this section simply evaluates its
arguments in left-to-right order. The only difference is the result
returned.

The most widely used sequencing special form is @code{progn}: it
evaluates all its argument forms and returns the computed value of the last
one. Many other control structures are said to perform an @dfn{implicit progn},
this means that internally they call @code{progn} with a list of forms.

@code{progn} in Lisp is nearly analogous to a @code{begin@dots{}end}
block in Pascal; it is used in much the same places---to allow you to
evaluate a sequence of form where only one form was allowed (for
example the ``true'' clause of an @code{if} structure).

@defspec progn forms@dots{}
All of the @var{forms} are evaluated sequentially (from left-to-right),
the result of the last evaluated @var{form} is the return value of the
special form. If no arguments are given to @code{progn} it returns
false.

@lisp
(progn 'one (+ 1 1) "three")
    @result{} "three"

(progn)
    @result{} ()
@end lisp
@end defspec

@defmac prog1 first forms@dots{}
This special form evaluates its @var{first} form then performs an
implicit progn on the rest of its arguments. The result of this
structure is the computed value of the @var{first} form.

@lisp
(prog1 'one (+ 1 1) "three")
    @result{} one
@end lisp
@end defmac

@defmac prog2 first second forms@dots{}
This is similar to @code{prog1} except that the evaluation of its
@var{second} form is returned.

The @var{first} form is evaluated, then its @var{second}, then it
performs an implicit progn on the remaining arguments.

@lisp
(prog2 'one (+ 1 1) "three")
    @result{} 2
@end lisp
@end defmac


@node Conditional Structures, Looping Structures, Sequencing Structures, Control Structures
@subsection Conditional Structures
@cindex Conditional structures
@cindex Control structures, conditionals

Lisp provides a number of conditional constructs, the most complex of
which (@code{cond}) takes a list of conditions, the first of which
evaluates to true has its
associated list of forms evaluated. Theoretically this is the only
conditional special form necessary---all others can be implemented as
macros.

@defmac if condition true-form else-forms@dots{}
The @code{if} form is the nearest thing in Lisp to the
@dfn{if-then-else} construct found in most programming languages.

First the @var{condition} form is evaluated, if it returns true the
@var{true-form} is evaluated and its result returned. Otherwise the
result of an implicit progn on the @var{else-forms} is returned. If
there are no @var{else-forms} false is returned.

Note that one of the @var{true-form} or the @var{else-forms} is completely
ignored---it is not evaluated.

@lisp
(if (special-form-p if)
    "`if' is a special form"
  "`if' is not a special form")
    @result{} "`if' is not a special form"
@end lisp
@end defmac

@defmac when condition true-forms@dots{}
@var{condition} is evaluated, if it is true the result of an
implicit progn on the @var{true-forms} is returned, otherwise
false is returned.

@lisp
(when t
  (message "Pointless")
  'foo)
    @result{} foo
@end lisp
@end defmac

@defmac unless condition else-forms@dots{}
This special form evaluates @var{condition}, if its computed value is
true, @code{()} is returned. Otherwise the @var{else-forms} are
evaluated sequentially, the value of the last is returned.
@end defmac

@defspec cond clause@dots{}
The @code{cond} special form is used to choose between an arbitrary
number of conditions. Each @var{clause} is a list; the car of which is
a @var{condition}, the cdr is a list of forms to evaluate (in an
implicit @code{progn}) if the @var{condition} evaluates to true.
This means that each @var{clause} looks something like:

@lisp
(@var{condition} @var{body-forms}@dots{})
@end lisp

@noindent
and a whole @code{cond} form looks like:

@lisp
(cond
 (@var{condition-1} @var{body-forms-1}@dots{})
 (@var{condition-2} @var{body-forms-2}@dots{})
 @dots{})
@end lisp

The @var{condition} in each @var{clause} is evaluated in sequence
(@var{condition-1}, then @var{condition-2}, @dots{}), the first one
which evaluates to a true value has an implicit @code{progn}
performed on its @var{body-forms}. The value of this @code{progn} is
also the value of the @code{cond} statement.

If the true @var{condition} has no @var{body-forms} the value returned
is the value of the @var{condition}. If none of the clauses has a
true @var{condition} the value of the @code{cond} statement
is false.

Often you want a @dfn{default} clause which has its @var{body-forms}
evaluated when none of the other clauses are true. The way to do this
is to add a clause with a @var{condition} of @code{t} and
@var{body-forms} of whatever you want the default action to be.

@lisp
(cond
 ((stringp buffer-list))        ;Clause with no @var{body-forms}
 ((consp buffer-list)
  (setq x buffer-list)          ;Two @var{body-forms}
  t)
 (t                             ;Default clause
  (error "`buffer-list' is corrupted!")))
    @result{} t
@end lisp
@end defspec

@defmac case key clauses@dots{}
This special form is similar to @code{cond}, but switches on the result
of evaluating a single form @var{key}, checking for equality with a
number of other values, defined by the @var{clauses}. If any of these
other values is the same as the result of evaluating @var{key}, then a
sequence of forms associated with the value is evaluated.

Each element of the @var{clauses} list has the format:

@lisp
((@var{value-1} @var{value-2} @dots{} @var{value-n}) @var{forms}@dots{})
@end lisp

@noindent
Each of the values in the car of the clause is tested for equality with
@var{key}, using the @code{eql} function. If any test positively, then
the associated @var{forms} are evaluated and the resulting value
becomes the result of the special form.

Instead of supplying a list of possible values, it is also possible to
just specify the symbol @code{t}. If such a clause is encountered, and
no other clauses have matched the value of @var{key}, then this clause
is assumed to match by default.

If any of the values in the @var{clauses} appear multiply, then the
behaviour of the construct is undefined.

Here is an example use of @code{case}:

@lisp
(case foo
  ((bar baz)
    (print "It was either bar or baz"))
  ((quux)
    (print "It was quux"))
  (t
    (print "I've no idea what it was...")))
@end lisp
@end defmac

There are also a number of special forms which combine conditions together
by the normal logical rules.

@defmac or forms@dots{}
The first of the @var{forms} is evaluated, if it is true its
value is the value of the @code{or} form and no more of @code{forms}
are evaluated. Otherwise this step is repeated for the next member of
@var{forms}.

If all of the @var{forms} have been evaluated and none have a
true value the @code{or} form evaluates to false.

@lisp
(or nil 1 nil (beep))           ;@code{(beep)} won't be evaluated
    @result{} 1
@end lisp
@end defmac

@defmac and forms@dots{}
The first of the @var{forms} is evaluated. If it is false no more
of the @var{forms} are evaluated and false is the value of
the @code{and} statement. Otherwise the next member of @var{forms} is
evaluated and its value tested. If none of the @var{forms} are
false the computed value of the last member of @var{forms} is
returned from the @code{and} form.

@lisp
(and 1 2 nil (beep))            ;@code{(beep)} won't be evaluated
    @result{} ()

(and 1 2 3)                     ;All forms are evaluated
    @result{} 3
@end lisp
@end defmac

@defun not object
This function inverts the truth value of its argument. If @var{object}
is true, false is returned, otherwise true is
returned.

@lisp
(not nil)
    @result{} t

(not t)
    @result{} ()

(not (not 42))
    @result{} t
@end lisp
@end defun


@node Looping Structures, Non-Local Exits, Conditional Structures, Control Structures
@subsection Looping Structures
@cindex Looping structures
@cindex Control structures, looping

Librep only has one method of creating looping control
structures---recursion. Any looping construct found in an imperative
language can be represented as a recursive function. For example the
common @code{while} statement:

@lisp
(while @var{condition} @var{body}@dots{})
@equiv{}
(letrec ((loop (lambda ()
                 (when @var{condition}
                   @var{body}
                   (loop)))))
  (loop))
@end lisp

@noindent
Each successive iteration of the loop is simply another call to the
function. Also note that the recursive call to the @code{(loop)}
function occurs in the tail-position of the function. When combined
with the system's ability to eliminate tail-calls (@pxref{Function Call
Forms}) the above example loop has bounded space requirements. This is
important when loops make a large number of iterations.

Although tail-recursion is the only primitive method of looping, the
language offers a number of looping forms for convenience.

@defmac do vars (test expr@dots{}) body@dots{}
@code{do} is an iteration construct; @var{vars} specifies a set of
variable bindings to be created, how they are initialized and how they
are updated on each iteration. @var{test} specifies the termination
condition of the loop, any @var{expr}@dots{} forms are evaluated
immediately prior to exiting the `do' construct. The @var{body}@dots{}
forms specify the side effecting body of the loop.

@var{vars} is a list of variable clauses, each of which has the
structure @code{(@var{variable} @var{init} @var{step})} where
@var{variable} is the name of a variable, @var{init} defines the
initial value of its binding, and @var{step} defines how the next value
of the binding is computed. An alternative form is
@code{(@var{variable} @var{init})}, in this case the value of the
binding does not change across loop iterations.

Each iteration begins by evaluating @var{test}, if the result is
false, then the @var{body}@dots{} expressions are evaluated, and
the variables bound to new locations initialized to the results of
evaluating the associated @var{step} forms.

If the result of evaluating @var{test} is true then the
@var{expr}@dots{} forms are evaluated, and the @code{do} construct
returns the value of the last @var{expr} form evaluated.

@lisp
(do ((vec (make-vector 5))
     (i 0 (1+ i)))
    ((= i 5) vec)
  (aset vec i i))

    @result{} [0 1 2 3 4]
@end lisp
@end defmac

The ``named-let'' variant of the @code{let} form also provides a
convenient looping construct.

@defmac let function bindings body@dots{}
This is the same as the @code{(let @var{bindings} @var{body}@dots{})}
form described in @ref{Local Variables}, but within the
@var{body}@dots{} forms, the symbol @var{fuction} is bound to a
function whose parameters are the bound variables defined by
@var{bindings} and whose body is the sequence of forms
@var{body}@dots{}

This means that the body of the @code{let} may be repeated by invoking
the function @var{variable} with suitable parameters.

@lisp
(let loop ((rest '(1 2 3))
           (total 0))
  (if (null rest)
      total
    (loop (cdr rest) (+ total (car rest)))))

    @result{} 6
@end lisp
@end defmac

Finally, the imperative @code{while} form shown at the start of the
section is also provided:

@defmac while condition body@dots{}
The @var{condition} form is evaluated. If it is true an
implicit progn is performed on the @var{body} forms and the whole
procedure is repeated.

This continues until the @var{condition} form evaluates to false.
The value of every @code{while} structure that terminates is
false.
@end defmac


@node Non-Local Exits, Continuations, Looping Structures, Control Structures
@subsection Non-Local Exits
@cindex Non-local exits
@cindex Control structures, non-local exits

A @dfn{non-local exit} is a transfer of control from the current point
of evaluation to a different point (somewhat similar to the
much-maligned @code{goto} statement in imperative languages).

Non-local exits can either be used explicitly (@code{catch} and
@code{throw}) or implicitly (errors).

@menu
* Catch and Throw::             Programmed non-local exits
* Function Exits::              Returning values from a function
* Cleanup Forms::               Forms which will always be evaluated
* Errors::                      Signalling that an error occurred
@end menu


@node Catch and Throw, Function Exits, , Non-Local Exits
@subsubsection Catch and Throw
@cindex Catch and throw
@cindex Non-local exits, catch and throw

The @code{catch} and @code{throw} structures are used to perform
explicit transfers of control. First a @code{catch} form is used to
setup a @dfn{tag}; this acts like a label for a @code{goto} statement.
To transfer control a @code{throw} form is then used to transfer to the
named tag. The tag is destroyed and the @code{catch} form exits with
the value provided by the @code{throw}.

In a program this looks like,

@lisp
(catch '@var{tag}
  ;; Forms which may `throw' back to @var{tag}
  @dots{}
  (throw '@var{tag} @var{value})
  ;; Control has now passed to the `catch',
  ;; no more forms in this progn will be evaluated.
  @dots{})
    @result{} @var{value}
@end lisp

@noindent
where @var{tag} is the tag to be used (this is normally a symbol) and
@var{value} is the result of the @code{catch} form.

When a throw actually happens all catches in scope are searched for one
with a tag which is @code{eq} to the tag in the throw. If more than one
exists the innermost is selected. Now that the catch has been located
the environment is `wound-back' to the catch's position (i.e. local
variables are unbound, cleanup forms executed, unused catches removed,
etc@dots{}) and all Lisp constructs between the current point of
control and the catch are immediately exited.

For example,

@lisp
(let
    ((test 'outer))
  (cons (catch 'foo
          (let
              ((test 'inner))
            (throw 'foo test)
            (setq test 'unreachable)))  ;Never reached
        test))
    @result{} (inner . outer)
@end lisp

@noindent
when the throw executes the second binding of @code{test} is unwound
and the first binding comes back into effect. For more details on
variable binding see @ref{Local Variables}.

Note that catch tags are @emph{dynamically} scoped, the thrower does
not have to be within the same lexical scope (this means that you can
@code{throw} through functions).

@defmac catch tag body-forms@dots{}
This special form defines a catch tag which will be accessible while the
@var{body-forms} are evaluated.

@var{tag} is evaluated and recorded as the tag for this catch. Next the
@var{body-forms} are evaluated as an implicit @code{progn}. The value
of the @code{catch} form is either the value of the @code{progn}, or,
if a @code{throw} happened, the value specified in the @var{throw}
form.

Before exiting, the tag installed by this form is removed.
@end defmac

@defun throw tag @t{#!optional} catch-value
This function transfers the point of control to the catch form with a
tag which is @code{eq} to @var{tag}. The value returned by this catch
form is either @var{catch-value} or false if @var{catch-value} is
undefined.

If there is no catch with a tag of @var{tag} an error is signalled and
the interpreter returns to the top-level of evaluation.
@end defun

There are a number of pre-defined throw tags:

@table @code
@item quit
Terminate the Librep interpreter, returning the value of the
throw (if a number).

@item exit
Exit the innermost event loop, unless currently in the outermost event
loop, when control just passes back to the event loop.

@item user-interrupt
As if a @code{SIGINT} or @kbd{C-c} signal has been received. Control
passes back to the top-level event loop.

@item term-interrupt
Triggered when a @code{SIGTERM} or @code{SIGHUP} signal is received.
Tries to clean up any existing state, then terminates the interpreter.
@end table

Note that it is the event loop that catches these tags. If no event
loop is active (i.e. just in read-eval-print on the console mode), any
uncaught throws will result in termination.


@node Function Exits, Cleanup Forms, Catch and Throw, Non-Local Exits
@subsubsection Function Exits
@cindex Function exits
@cindex Non-local exits, function exits

Librep has no explicit @code{return} statement, as found in most
other languages. Where a value has to returned from a function before
the function would normally exit, a @code{catch}/@code{throw} pair may
be used.

For example:

@lisp
(defun foo (x y)
  (catch 'return
     (when (= x 2)
       (throw 'return nil))
     @dots{}
@end lisp


@node Cleanup Forms, Errors, Function Exits, Non-Local Exits
@subsubsection Cleanup Forms
@cindex Cleanup forms
@cindex Non-local exits, cleanup forms

It is sometimes necessary ensure that a certain form is @emph{always}
evaluated, even when a non-local exit would normally bypass that form.
The @code{unwind-protect} special form is used in this case.

@defmac unwind-protect body-form cleanup-forms@dots{}
The @var{body-form} is evaluated, if it exits normally the @var{cleanup-forms}
are evaluated sequentially then the value which the @var{body-form}
returned becomes the value of the @code{unwind-protect} form. If the
@var{body-form} exits abnormally though (i.e. a non-local exit happened)
the @var{cleanup-forms} are evaluated anyway and the non-local exit
continues.
@end defmac

One use of this is to ensure that an opened file is always closed, for
example,

@lisp
(catch 'foo
  (unwind-protect
      (let
          ((temporary-file (open-file (make-temp-name) 'write)))
        ;; Use @code{temporary-file}
        (write temporary-file "A test\n")
        ;; Now force a non-local exit
        (throw 'foo))
    ;; This is the @var{cleanup-form} it will @emph{always}
    ;; be evaluated, despite the @code{throw}.
    (close temporary-file)))
    @result{} ()
@end lisp


@node Errors, , Cleanup Forms, Non-Local Exits
@subsubsection Errors
@cindex Errors
@cindex Non-local exits, errors

Errors are a type of non-local exit; when a form can not be evaluated
for some reason an error is normally @dfn{signalled}. If an
error-handler has been installed for that type of error, control is
passed to the handler for that error, and evaluation continues. If
there is no suitable handler, control is passed back to the innermost
input loop and a suitable error message is printed.

@defun signal error-symbol data
Signals that an error has happened. @var{error-symbol} is a symbol
classifying the type of error, it should have a property
@code{error-message} (a string) which is the error message to be
printed.

@var{data} is a list of objects which are relevant to the error ---
they will be made available to any error-handler or printed with the
error message otherwise.

@lisp
(signal 'void-value '(some-symbol))
    @error{} Value as variable is void: some-symbol
@end lisp
@end defun

@defun error template #!rest values
Same as @code{(signal 'error @var{string})}, where @var{string}
is a string formatted by @var{template} and @var{VALUES}. (@pxref{Formatted Output})
@end defun

@defvar debug-on-error
This variable controls the condition to enter the Lisp debugger.
When the debugger exits the error is signalled as normal.

If it's @code{t}, then the debugger starts if the control is not
inside of any @code{condition-case} described below.  Notice that the
criterion is NOT if the error is actually handled by an error handler.

If it's a symbol @code{always}, then the debugger is entered always,
i.e. even if it is inside of a @code{condition-case}. If it's a list
of errer-symbols, for example @code{(void-value bad-arg)}, then only
when the error matches one of them, the debugger is called even
inside of a @code{condition-case}.

@lisp
(setq backtrace-on-error t) ;; Ordinary usage.
(setq backtrace-on-error '(void-value bad-arg)) ;; Catch them only
@end lisp
@end defvar

@defvar backtrace-on-error
Similar to @code{debug-on-error} (read WELL its description), but
instead of entering the debugger, the current backtrace is printed to
the standard error stream, and control continues.
@end defvar

When you expect an error to occur and need to be able to regain control
afterwards the @code{condition-case} special form may be used.

@defmac condition-case symbol body-form error-handlers@dots{}
@code{condition-case} evaluates the @var{body-form} with the
@var{error-handlers} in place. If an error occurs and one of the
handles matches the error, then it is evaluated with the value of
@var{symbol} set to the error information.

Each of the @var{error-handlers} is a list whose car is a symbol
defining the type of error which this handler catches. The cdr of the
list is a list of forms to be evaluated in a @code{progn} if the
handler is invoked.

While the forms of the error handler are being evaluated the variable
@var{symbol} is bound to the value @code{(@var{error-symbol} .
@var{data})} (these were the arguments to the @code{signal} form which
caused the error). If @var{symbol} is the symbol @code{nil} (or the
empty list @code{()}), then the error information is not available to
the handler.

The special value, the symbol @code{error}, in the car of one of the
@var{error-handlers} will catch @emph{all} types of errors.

@lisp
(condition-case data
    (signal 'file-error '("File not found" "/tmp/foo"))
  (file-error
   data)
  (error
   (setq x z)))         ;Default handler
    @result{} (file-error "File not found" "/tmp/foo")
@end lisp
@end defmac


@node Continuations, , Non-Local Exits, Control Structures
@section Continuations
@cindex Continuations

Whenever a function is called, there is a control path waiting to
receive the result of the function, e.g. often the form following the
function invocation. This waiting control path is called the
@dfn{continuation} of the function, since control will continue down
this path when the called function exits.

These continuations are usually not paid much thought, but in some
cases it may be useful to be able to directly manipulate the
continuation of a function. For this purpose Rep provides the
@code{call-with-current-continuation} function (often shortened to
@code{call/cc}) that is standard in Scheme.

@defun call/cc function
@var{function} is a function with a single parameter; it will be
immediately invoked with this parameter bound to an object representing
the current continuation (i.e. the control path that would be taken
after @var{function} exits).

The continuation object passed to @var{function} is itself a function
accepting a single argument, when called it transfers control to the
continuation of @var{function}, as if @var{function} had returned the
argument applied to the continuation object.
@end defun

@defun call-with-current-continuation function
This is an alias for @code{call/cc}.
@end defun

In its simplest form, @code{call/cc} can mimic the @code{catch} and
@code{throw} procedures (@pxref{Catch and Throw}), for example:

@lisp
(defun foo (bar)
  (call/cc (lambda (esc)
             (when (null bar)
               ;; throws out of the call/cc
               (esc nil))
             ;; do something with bar
             @dots{}
@end lisp

@noindent
this is roughly equivalent to:

@lisp
(defun foo (bar)
  (catch 'tag
    (when (null bar)
      (throw 'tag nil))
    ;; do something with bar
    @dots{}
@end lisp

This is only half the story---the most powerful feature of
@code{call/cc} is that since continuations have dynamic extent (that
is, no object is freed until no references to it exist) it is possible
to return control to scopes that have already exited.

For example, consider the following fragment of a lisp interaction:

@lisp
(prog1 (call/cc (lambda (esc)
                  (setq cont esc)))
  (message "foo!"))
    @print{} foo!
    @result{} #<closure>

cont
    @result{} #<closure>

(cont 10)
    @print{} foo!
    @result{} 10
@end lisp

@noindent
The continuation of the @code{prog1} form is saved into the variable
@code{cont}. When subsequently called with a single argument, it has
exactly the same effect as the first time that the second form in the
@code{prog1} construct was evaluated.

@subsection Implementation Notes

@code{call/cc} works by making a copy of the process' entire call
stack. For this reason, it is likely to be less efficient than using
the control structures described in the previous parts of this section.
Of course, it is much more powerful than the other constructs, so this
often outweighs the slight inefficiency.

Also note that currently no attempt is made to save or restore the
dynamic state of the Lisp system, apart from variable bindings (both
lexical and special). This means that any @code{unwind-protect},
@code{condition-case} or @code{catch} forms that are active when
invoking a continuation are all ignored.

Another restriction is that invoking a continuation may not cause
control to pass across a dynamic root (@pxref{Threads}).


@node Threads, Loading, Control Structures, The language
@section Threads
@cindex Threads

Librep supports a simple model of multi-threaded programming.
Multiple threads of execution may be created, with control preemptively
being switched between them.

Unless otherwise noted, all definitions described in this section are
provided by the @code{rep.threads} module.

@menu
* Thread Contexts::
* Creating Threads::
* Deleting Threads::
* Manipulating Threads::
* Mutexes::
* Thread Implementation Notes::
@end menu


@node Thread Contexts, Creating Threads, , Threads
@subsection Thread Contexts
@cindex Thread contexts

Every thread created by Rep is a member of a @dfn{thread context}, this
context is defined by the current position in the lisp call stack. At
any point in time, only threads which are members of the current
context may be executing.

@defun call-with-dynamic-root thunk
Call the function of zero-parameters @var{thunk} in a new thread
context. The new context will contain a single thread, that executing
@var{thunk}.

The call to @code{call-with-dynamic-root} will only return once all
threads in the newly created context have been deleted, or a non-local
exit causes control to leave forcibly.
@end defun


@node Creating Threads, Deleting Threads, Thread Contexts, Threads
@subsection Creating Threads
@cindex Creating threads
@cindex Threads, creating

The @code{make-thread} function may be used to create threads that
execute within the current thread context (dynamic root). Each thread
is represented by a lisp object.

@defun threadp arg
Return true if lisp object @var{arg} represents a thread of
execution in the lisp environment.
@end defun

@defun make-thread thunk @t{#!optional} name
Create and return a new thread of execution; it will initially invoke
the zero-parameter function @var{thunk}. If the call to @var{thunk}
returns the thread is automatically deleted.

If @var{name} is defined, it is a string naming the current thread.
@end defun

@defun make-suspended-thread @t{#!optional} name
Similar to @code{make-thread}, except that the newly created thread
will be immediately suspended from running.
@end defun

@defun current-thread
Returns the currently executing thread. If no threads have been created
yet in the current dynamic root (i.e. there is a single ``implicit''
thread) then false is returned.
@end defun

@defun all-threads
Returns a newly-created list containing all threads in the current
dynamic root. If no threads have been created yet, returns a null list.
@end defun


@node Deleting Threads, Manipulating Threads, Creating Threads, Threads
@subsection Deleting Threads
@cindex Deleting threads
@cindex Threads, deleting

A thread may be deleted by either returning from the function specified
when it was created, or by explicit deletion. Also, the implicit thread
created by the @code{call-with-dynamic-root} function may be deleted by
exiting from the function called in the new context.

@defun thread-delete @t{#!optional} thread
Mark @var{thread} (or the current thread), as being deleted. It will
not be switched to in the future. If the current thread is deleted,
control will be passed to the next runnable thread. Deleting the last
runnable thread results forces the containing dynamic root to be
closed.
@end defun

@defun thread-deleted-p thread
Returns true if @var{thread} has been deleted.
@end defun


@node Manipulating Threads, Mutexes, Deleting Threads, Threads
@subsection Manipulating Threads
@cindex Manipulating threads
@cindex Threads, manipulating

@defun thread-yield
This function may be used to pass control away from the current thread
if other threads are waiting to run. There is usually no need to call
this function since running threads will be preempted after a period of
time.
@end defun

@defun thread-suspend @t{#!optional} thread milliseconds
Mark @var{thread} (or the current thread) as being suspended. It will
not be selected until either it has had this status removed, or
@var{milliseconds} milliseconds time has passed.

Suspending the current thread will pass control to the next runnable
thread in the same dynamic root. If there are no runnable threads, then
the interpreter will sleep until the next thread becomes runnable.
@end defun

@defun thread-join thread @t{#!optional} timeout default-value
Suspends the current thread until either @var{thread} has exited, or
@var{timeout} milliseconds have passed.

If @var{thread} exits normally, then the value of the last form it
evaluated is returned; otherwise @var{default-value} is returned.

It is an error to call @code{thread-join} on a @var{thread} that is not
a member of the current dynamic root.
@end defun

@defun thread-wake thread
Remove the suspended state from thread @var{thread}. It will then be
scheduled for execution sometime subsequently, if its dynamic root is
active.
@end defun

@defun thread-suspended-p thread
Returns true if @var{thread} is currently suspended.
@end defun

Thread preemption may be forbidden at times, to allow atomic operations
to take place. Each dynamic root has its own ``forbid counter''. Only
when this counter is zero may the current thread be preempted.

@defun thread-forbid
Increment the forbid count.
@end defun

@defun thread-permit
Decrement the forbid count.
@end defun

@defmac without-interrupts @t{#!rest} forms
Evaluate the list of forms @var{forms} with thread preemption
temporarily disabled.
@end defmac


@node Mutexes, Thread Implementation Notes, Manipulating Threads, Threads
@subsection Mutual Exclusion Devices
@cindex Mutual exclusion devices
@cindex Mutexes
@cindex Threads, mutexes

@dfn{Mutexes} are lisp objects used to coordinate access to data shared
across multiple threads (where interleaved access would be bad). These
functions are exported by the @code{rep.threads.mutex} module
(@pxref{Modules}).

@defun make-mutex
Create and return a mutex object. No thread will own the new mutex.
@end defun

@defun mutexp arg
Return true if @var{arg} is a mutex object.
@end defun

@defun obtain-mutex mutex
Obtain the mutex @var{mutex} for the current thread. Will suspend the
current thread until the mutex is exclusively available.
@end defun

@defun maybe-obtain-mutex mutex
Attempt to obtain mutex @var{mutex} for the current thread without
blocking. Returns true if able to obtain the mutex, false
otherwise.
@end defun

@defun release-mutex mutex
Release the mutex object @var{mutex} (which must have previously been
obtained by the current thread). Returns true if the mutex has no
new owner.
@end defun


@node Thread Implementation Notes, , Mutexes, Threads
@subsection Thread Implementation Notes
@cindex Thread implementation notes

The threads used by Librep are @emph{software threads}. This
means that they are currently implemented by manually switching in and
out thread context (i.e. the call stack) as required. There are a
number of disadvantages to this method:

@itemize @bullet
@item blocking I/O blocks @emph{all} threads, not just the thread doing
the I/O,

@item only a single processor is used, thereby avoiding any true
parallelism on multi-processor systems.
@end itemize

@noindent
The main advantage is the ease of implementation, especially when
retrofitting threads into the previously single-threaded interpreter.


@node Loading, Compiled Lisp, Threads, The language
@section Loading
@cindex Loading
@cindex Loading programs
@cindex Programs, loading

In Lisp, programs (also called @dfn{modules}, or @dfn{libraries}) are
stored in files. Each file is a sequence of Lisp forms (known as
@dfn{top-level forms}). Most of the top-level forms in a program will
be definitions (i.e. function, macro or variable definitions) since
generally each library is a system of related functions and variables.

Before the program can be used it has to be @dfn{loaded} into the editor's
workspace; this involves reading and evaluating each top-level form in
the file, i.e. instantiating all function definitions, or whatever.

@menu
* Load Function::               The function which loads programs
* Autoloading::                 Functions can be loaded on reference
@end menu


@node Load Function, Autoloading, , Loading
@subsection Load Function
@cindex Load function
@cindex Functions, loading

@defun load program @t{#!optional} no-error no-path no-suffix
This function loads the file containing the program called @var{program}.
First the file is located, then evaluated, i.e., each top-level form
is read and evaluated in order.

If @var{program} is not an absolute path, each directory named by the
variable @code{load-path} is searched until the file containing
@var{program} is found. In each directory two different file names are
tried,

@enumerate
@item
@var{program} with @samp{.jlc} appended to it. Files with a
@samp{.jlc} suffix are usually compiled Lisp files. @xref{Compiled
Lisp}.

If it is older than a @samp{.jl} version of the same file (i.e. the
source code is newer than the compiled version), a warning is
displayed and the @samp{.jl} version is used instead.

@item
@var{program} with @samp{.jl} appended, most uncompiled Lisp programs are
stored in files with names like this.
@end enumerate

Notice that the file @var{program} with no modifications is @emph{not}
loaded. If you want it, set @var{no-suffix} to non-nil.

Filename can have a leading tilde in Unix, and tar archive is
also readable directly. See @xref{File Handlers}.

If none of these gives a result the next directory is searched in the
same way. When all directories in @code{load-path} have been exhausted
and the file still has not been found an error is signalled.

Next the file is opened for reading and Lisp forms are read from it
one at a time, each form is evaluated before the next form is read. When
the end of the file is reached, this function returns true.

The optional arguments to this function are used to modify its behaviour,

@table @var
@item no-error
When this argument is true no error is signalled if the file
can not be located. Instead the function returns false.

@item no-path
The variable @code{load-path} is not used, @var{program} must point to
the file from the current working directory.

@item no-suffix
When true no @samp{.jlc} or @samp{.jl} suffixes are applied to
the @var{program} argument when locating the file.
@end table

If no Lisp file can be found matching @var{program}, then each
directory in the variable @code{dl-load-path} is searched for a
@code{libtool} shared library called @file{@var{program}.la}.
@end defun

@defvar load-filename
Whilst loading a Lisp library, this variable is bound to the name of
the file being loaded.
@end defvar

@defvar load-path
A list of strings, each element is the name of a directory which is
prefixed to the name of a program when Lisp program files are being
searched for.

@lisp
load-path
    @result{} ("/usr/local/lib/rep/1.0/lisp/"
        "/usr/local/lib/rep/site-lisp/" "")
@end lisp

The element @code{""} refers to the current directory, note that
directory names should have an ending @samp{/} (or whatever) so that
when concatenated with the name of the file they make a meaningful
filename.
@end defvar

@defvar dl-load-path
A list of strings defining all directories to search for shared
libraries.
@end defvar

@defvar lisp-lib-directory
The name of the directory in which the standard Lisp files are stored.

@lisp
lisp-lib-dir
    @result{} "/usr/local/lib/rep/1.0/lisp/"
@end lisp
@end defvar

@defvar after-load-alist
An association list of elements of the format @code{(@var{file}
@var{forms} @dots{})}. When the library @var{file} is loaded, all
@var{forms} are executed. However, note that @var{file} must
@emph{exactly} match the @var{program} argument to the @code{load}
function.
@end defvar

@defun eval-after-load library form
Arrange for @var{form} to be evaluated immediately after the Lisp
library of @var{library} has been read by the @code{load} function.
Note that @var{library} must exactly match the @var{program} argument
to @code{load}.
@end defun


@node Autoloading, , Load Function, Loading
@subsection Autoloading
@cindex Autoloading
@cindex Loading, on reference

Obviously, not all features of the Librep environment are always
used. @dfn{Autoloading} allows libraries to only be loaded when they
are first required. This speeds up the initialisation process and may
save memory.

Functions which may be autoloaded have a special form in their symbol's
function cell---an @dfn{autoload form}. This is a special kind of
closure. When the function call dispatcher finds one of these forms it
loads the program file specified in the form then re-evaluates the
function call. The true function definition will then have been loaded
and therefore the call may proceed as normal.

Autoload stubs may be created through the @code{autoload} function.

@defun autoload symbol file @t{#!optional} is-command
Installs an autoload form into the symbol @var{symbol}. It marks that
when @var{symbol} is called as a function the lisp library @var{file}
should be loaded to provided the actual definition of @var{symbol}.
@end defun

``Magic cookie'' @code{;;;###autoload} comment in the source
is meaningless. It was supported by Obsolete ``Jade'' editor only.

@node Compiled Lisp, Docstrings, Loading, The language
@section Compiled Lisp
@cindex Compiled Lisp

Librep contains a Lisp compiler as well as an interpreter; this
takes a Lisp form or program and compiles it into a @dfn{byte-code}
object. This byte-code object is a string of characters representing
virtual machine instructions, a vector of constants and some other
meta-information. The system also contains a byte-code interpreter;
this takes the compiled byte-codes and executes them by simulating the
virtual machine. This simulation will have exactly the same effect as
interpreting the original form or program.

One of the main reasons for compiling programs is to increase their
efficiency. Compiled functions are likely to be more efficient than
interpreted counterparts in all areas (space and time). For example:

@example
user> (define (fib n) (if (<= n 2) 1 (+ (fib (- n 1)) (fib (- n 2)))))
user> ,time (fib 30)
832040
Elapsed: 17.05572 seconds
user> ,compile
user> ,time (fib 30)
832040
Elapsed: 1.479007 seconds
@end example

@noindent
---the compiled function is over an order of magnitude faster than the
interpreted version.

@menu
* Compilation Functions::       How to compile Lisp programs
* Compiler Declarations::       Hinting to the compiler
* Compilation Tips::            Getting the most out of the compiler
* Disassembly::                 Examining compiled functions
@end menu


@node Compilation Functions, Compiler Declarations, , Compiled Lisp
@subsection Compilation Functions
@cindex Compilation functions
@cindex Functions, compilation

These functions are defined in @code{rep.vm.compiler}.

@defun compile-form form
This function compiles the Lisp form @var{form} into a byte-code form
which is returned.

@lisp
(compile-form '(setq foo bar))
    @result{} (run-byte-code "\030F!v" [bar foo] 2)
@end lisp
@end defun

@deffn Command compile-function function
This function replaces the uncompiled body of the function @var{function}
(a symbol) with a compiled version, then returns @var{function}.
@end deffn

@deffn Command compile-file file-name
This function compiles the file called @var{file-name} into a file of
compiled Lisp forms whose name is @var{file-name} with @samp{c} appended
to it (i.e. if @var{file-name} is @file{foo.jl} it will be compiled to
@file{foo.jlc}).

If an error occurs while the file is being compiled any semi-written
file will be deleted.

When called interactively this function will ask for the value of
@var{file-name}.
@end deffn

@deffn Command compile-directory directory @t{#!optional} force exclude
Compiles all the Lisp files in the directory called @var{directory} which
either haven't been compiled or whose compiled version is older than
the source file (Lisp files are those ending in @samp{.jl}).

If the optional argument @var{force} is true @emph{all} Lisp files
will be recompiled whatever the status of their compiled version.

The @var{exclude} argument may be a list of filenames, these files will
@emph{not} be compiled.

When this function is called interactively it prompts for the directory.
@end deffn

@deffn Command compile-module module-name
Compiles all uncompiled function definitions in the module named
@var{module-name} (a symbol).

When called interactively the module name will be prompted for.
@end deffn

@defun run-byte-code byte-codes constants stack
Interprets the string of byte instructions @var{byte-codes} with
the vector of constants @var{constants}.

This function should @emph{never} be called by hand. The compiler will
produce calls to this function when it compiles a form or a function.
@end defun

There is a second form that byte-code objects can take: a vector whose
read syntax includes a preceding @samp{#} character is a @dfn{byte-code
subr}. These objects represent compiled Lisp functions and macros.

@defun bytecodep arg
Returns true if @var{arg} is a byte-code subroutine.
@end defun


@node Compiler Declarations, Compilation Tips, Compilation Functions, Compiled Lisp
@subsection Compiler Declarations
@cindex Compiler declarations
@cindex Declarations, compiler

It is often useful to be able to give the compiler extra knowledge
about the program forms that it is compiling. The language includes
special declaration forms that have no effect when interpreted, but are
meaningful to the compiler as it traverses the program.

@defmac declare clause@dots{}
Offer the information contained in the @var{clause}@dots{} forms to the
compiler, which it may or may not use when compiling the program.

Each @var{clause} is a list, the first element of each clause is a
symbol defining the type of declaration, the interpretation of any
other elements in the clause depends upon the declaration type.

The following table lists the syntax of all currently supported
declaration types:

@table @code
@item (bound @var{variables}@dots{})
This declaration tells the compiler that all symbols @var{variables}
have lexical bindings for the extent of the current lexical scope. This
is often useful to prevent spurious compiler warnings.

@item (special @var{variables}@dots{})
This tells the compiler that all symbols @var{variables} have special
(dynamic) bindings for the extent of the current lexical scope.

(It is important that the compiler is able to distinguish special
bindings from lexical bindings, since different instruction sequences
must be generated to access the different types of binding.)

@item (unused @var{variables}@dots{})
Directs the compiler not to warn about bindings for
@var{variables}@dots{} being unreferenced.

@item (inline @var{names}@dots{})
Tells the compiler that it should consider inlining calls to the
functions called @var{names}@dots{}. Inlining will only occur if these
functions are declared in the same module as, and after, the
declaration itself.

@item (in-module @var{module-name})
This declaration should occur at the top-level of a program; it tells
the compiler that the forms in the program will be evaluated within the
context of the module called @var{module-name} (a symbol).

@item (language @var{module})
Obsolete declaration.

Explicitly specifies the particular language dialect that the current
module or file body is written for. Language dialects included with the
librep distribution include Rep, Scheme and
Unscheme. These are also the names of the modules that should be
imported to use a particular dialect.

By default, the Rep is assumed for code outside module
definitions. For code inside a module definition the list of imported
modules is scanned for a known language dialect (i.e. if the module
imports @code{rep}, then the Rep language dialect is compiled for).

@item (unsafe-for-call/cc)
Tell the compiler that it may register-allocate variables, even if it
can't prove that doing so wouldn't produce incorrect results if
@code{call/cc} causes a function call to return more than once
(@pxref{Continuations}). This declaration applies to the entire file
that it occurs in.

Without this declaration, the compiler will only register-allocate
bindings if the following conditions are met:

@itemize @bullet
@item the binding is not accessed from any inner closures, and,

@item the binding is never modified after being initialized (actually,
the binding may be modified between being intialized and the next
function call)
@end itemize

@noindent
this declaration is often useful where @code{call/cc} isn't used, and
there is a lot of side effecting of local variables.
@end table

Declaration forms always evaluate to false.
@end defmac

A second type of declaration is the @code{eval-when-compile} form, it
allows Lisp forms to be evaluated only at compile-time.

@defmac eval-when-compile form
This form tells the system that @var{form} should only be evaluated
when the containing code is being compiled.

The compiler knows to recognize @var{form}s of the pattern
@code{(eval-when-compile (require '@var{feature}))} as marking that
@var{feature} should be imported at compile-time. Any other @var{form}s
are simply evaluated in an unspecified environment.

When interpreted, @code{eval-when-compile} forms alway evaluate to
false, when compiled they evaluate to the result of evaluating
the @var{form} at compile-time.
@end defmac


@node Compilation Tips, Disassembly, Compiler Declarations, Compiled Lisp
@subsection Compilation Tips
@cindex Compilation tips
@cindex Tips, compilation

Here are some tips for making compiled code run fast(er):

@itemize @bullet
@item
Instead of using @code{while} loops to traverse lists, use @code{mapc}
or tail recursion.

For example you might code a function to scan a list using iteration
through a @code{while} loop:

@lisp
(defun scan-list (lst elt)
  "Search the LST for an element similar to ELT.
Return it if one is found."
  (catch 'return
    (while (consp lst)
      (when (equal (car lst) elt)
        (throw 'return elt))
      (setq lst (cdr lst)))))
@end lisp

@noindent
As well as obscuring what is actually happening, this will probably be
fairly slow to execute. A more elegant solution is to use
tail-recursion:

@lisp
(defun scan-list (lst elt)
  (if (equal (car lst) elt)
      elt
    (scan-list (cdr lst) elt)))
@end lisp

@noindent
An alternative idiom is to map an anonymous function over the list
using the @code{mapc} function:

@lisp
(defun scan-list (lst elt)
  (catch 'return
    (mapc (lambda (x)
            (when (equal x elt)
              (throw 'return elt)))
          lst)
    nil))
@end lisp

@noindent
In fact, the compiler knows that calls to @code{mapc} with a constant
lambda expression can be open-coded, so it will code the list traversal
directly using the virtual machine stack.

However, in most cases the execution time differences are likely to
negligible.


@item
In some cases the functions @code{member}, @code{memq}, @code{assoc},
etc@dots{} can be used to search lists. Since these are primitives
written in C they will probably execute several times faster than an
equivalent Lisp function.

So the above @code{scan-list} example can again be rewritten, this time
as:

@lisp
(defun scan-list (lst elt)
  (car (member elt lst)))
@end lisp

@item
All conditional structures are equivalent when compiled (they are all
translated to @code{cond} statements), so use whichever is the easiest
to understand.

@item
A certain amount of constant folding is performed. If a function is
known to be free of side effects, and all its arguments are constants,
then it is evaluated at compile-time, and the result folded into the
program in its place. For example

@lisp
(logor (lsh 1 6) x)
    @expansion{} (logor 32 x)
@end lisp

@item
Careful use of named constants (@pxref{Defining Variables}) can increase
the speed of some programs. For example, in the Lisp compiler itself
all the opcode values (small integers) are defined as constants.

It must be stressed that in some cases constants may @emph{not} be
suitable; they may drastically increase the size of the compiled
program (when the constants are `big' objects, i.e. long lists) or even
introduce subtle bugs (since two references to the same constant may
not be @code{eq} whereas two references to the same variable are always
@code{eq}).

@item
Many primitives have corresponding byte-code instructions; these primitives
will be quicker to call than those that don't (and incur a normal function
call). Currently, the functions which have byte-code instructions (apart
from all the special forms) are:

@code{cons}, @code{car}, @code{cdr}, @code{rplaca}, @code{rplacd},
@code{nth}, @code{nthcdr}, @code{aset}, @code{aref}, @code{length},
@code{eval}, @code{+}, @code{*}, @code{/}, @code{%}, @code{mod},
@code{lognot}, @code{not}, @code{logior}, @code{logand}, @code{logxor},
@code{equal}, @code{eq}, @code{=}, @code{/=}, @code{>}, @code{<},
@code{>=}, @code{<=}, @code{1+}, @code{1-}, @code{-}, @code{set},
@code{lsh}, @code{zerop}, @code{null}, @code{atom}, @code{consp},
@code{listp}, @code{numberp}, @code{stringp}, @code{vectorp},
@code{throw}, @code{boundp}, @code{symbolp}, @code{get}, @code{put},
@code{signal}, @code{return}, @code{reverse}, @code{nreverse},
@code{assoc}, @code{assq}, @code{rassoc}, @code{rassq}, @code{last},
@code{mapcar}, @code{mapc}, @code{member}, @code{memq}, @code{delete},
@code{delq}, @code{delete-if}, @code{delete-if-not},
@code{copy-sequence}, @code{sequencep}, @code{functionp},
@code{special-form-p}, @code{subrp}, @code{eql}, @code{max},
@code{min}, @code{filter}, @code{macrop}, @code{bytecodep},
@code{bind-object}.

@item
When a file is being compiled each top-level form it contains is inspected
to see if it should be compiled into a byte-code form. Different types
of form are processed in different ways:

@itemize @bullet
@item
Function and macro definitions have their body forms compiled into a single
byte-code form. The doc-string and interactive declaration are not compiled.

@item
If the form is a list form (@pxref{List Forms}) and the symbol which is
the car of the list is one of:

@code{if}, @code{cond}, @code{when}, @code{unless}, @code{let}, @code{let*},
@code{catch}, @code{unwind-protect}, @code{error-protect}, @code{with-buffer},
@code{with-window}, @code{progn}, @code{prog1}, @code{prog2}, @code{while},
@code{and}, @code{or}, @code{case}.

@noindent
then the form is compiled. Otherwise it is just written to the output file
in its uncompiled state.
@end itemize

If your program contains a lot of top-level forms which you know will
not be compiled automatically, consider putting them in a @code{progn}
block to make the compiler coalesce them into one byte-code form.
@end itemize


@node Disassembly, , Compilation Tips, Compiled Lisp
@subsection Disassembly
@cindex Disassembly
@cindex Compilation, disassembly of forms

It is possible to disassemble byte-code forms; originally this was so I
could figure out why the compiler wasn't working but if you're curious
about how the compiler compiles a form it may be of use to you.

Naturally, the output of the disassembler is a listing in the assembly
language of the Librep virtual machine---it won't take a
byte-code form and produce the equivalent Lisp code!

@deffn Command disassemble function @t{#!optional} stream
This function disassembles the compile Lisp function @var{function}. It
writes a listing to the output stream @var{stream} (normally the
value of the @code{standard-output} variable).

When called interactively it will prompt for a function to disassemble.
Defined in @code{rep.vm.disassembler}.
@end deffn

When reading the output of the disassembler bear in mind that
Librep simulates a stack machine for the code to run on. All
calculations are performed on the stack, the value left on the stack
when the piece of code ends is the value of the byte-code form.

Here is a small example. Consider the @code{fib} function given at the
start of this section:

@lisp
(define (fib n)
  (if (<= n 2)
      1
    (+ (fib (- n 1))
       (fib (- n 2)))))
@end lisp

@noindent
After compilation and disassembly, the following is produced (but
without the annotations):

@example
Disassembly of #<closure fib>:

21 bytes, 1 constants, and (5,0,1) stack slots

0    required-arg       ;requires a single parameter
1    dup
2    slot-set #0        ;store it in register 0 (r0)
3    pushi 2
4    le
5    jn 10              ;unless r0 <= 2, goto 10
8    pushi 1
9    return             ;else, return 1
10   refg [0] fib
11   slot-ref #0
12   dec
13   call #1            ;push result of (fib (1- n))
14   refg [0] fib
15   slot-ref #0
16   pushi 2
17   sub
18   call #1            ;push (fib (- n 2))
19   add
20   return             ;return the sum of the two calls
@end example

@node Docstrings, Datums, Compiled Lisp, The language
@section Documentation Strings
@cindex Docstrings
@cindex Documentation Strings

The ``docstring'', or documentation string, of a variable or function
gives the description on it, given at its definition.

@defun documentation symbol structure value
Returns the documentation-string for @var{symbol}. It should be the
name of a special variable, function, macro, or a special form.  If
it's not a variable, then @var{value} should be the function itself,
like a closure.

Returns nil when not found. This function is defined in
@code{rep.lang.doc} module.

@var{structure} can be nil. It was required in the old syntax.
@end defun

Docstring is stored in a very complicated way. Those from installed files
are stored in @file{DOC} file. Others use the plist for the name. If
it's a special variable, then docstring is in @code{documentation}
property, and a closure and a macro, in @code{documentation#MODULE}.

@node Datums, Queues, Docstrings, The language
@section Datums
@cindex Datums
@cindex Data types, datums

@dfn{Datums} are the mechanism by which Librep allows Lisp
programs to define new data types, such that these types are completely
distinct from the built-in data types (i.e. they match none of the
standard type predicates).

They also provide encapsulation, in that the data objects they provide
are completely opaque, unless a pre-defined value is known (which was
specified when the object was created, and is typically known only by
the object's creator).

These functions are provided in @code{rep.data.datums}.

@defun make-datum value key
Create and return a new datum object. It has the value @var{value}
associated with it, and has type @var{key}.
@end defun

@defun datum-ref arg key
If @var{arg} has type @var{key}, then return the value associated with
it. Otherwise, an error is signalled.
@end defun

@defun datum-set arg key value
If @var{arg} has type @var{key}, then set the value associated with it
to be @var{value}. Otherwise, an error is signalled.
@end defun

@defun has-type-p arg key
Return true if @var{arg} has type @var{key}.
@end defun

@defun define-datum-printer key printer
Associate the function @var{printer} with all datum objects of type
@var{key}. When any such object is printed, @var{printer} is applied to
two arguments, the datum and the stream to which it should be printed
(@pxref{Output Streams}).
@end defun


@node Queues, Records, Datums, The language
@section Queues
@cindex Queues
@cindex Data types, queues

A @dfn{queue} is an ordered set of objects, such that objects enter at
one end of the queue (the @dfn{tail}), and leave from the other end of
the queue (the @dfn{head}). The acts of entering and leaving a queue
are often called @dfn{enqueing} and @dfn{dequeueing}.

Librep provides a straightforward queue implementation,
implemented by the @code{rep.data.queues} module (@pxref{Modules}).

@defun make-queue
Create and return a new queue object. The queue will initially be
empty.
@end defun

@defun enqueue q arg
Add the object @var{ARG} to the tail of the queue @var{q}.
@end defun

@defun dequeue q
Remove the object at the head of the queue @var{q}, and return it. If
@var{q} is empty, an error is signalled.
@end defun

@defun queue-empty-p q
Return true if the queue @var{q} is not empty.
@end defun

@defun queuep arg
Return true if the object @var{arg} is a queue.
@end defun

@defun queue->list q
Return a list of objects representing the contents of the queue
@var{q}, with objects ordered from head to tail. Modifying the list
structure causes undefined effects to the queue itself.
@end defun

@defun queue-length q
Return the number of objects stored in the queue @var{q}.
@end defun

@defun delete-from-queue q arg
Removes any occurrences of the object @var{arg} from the queue @var{q}.
@end defun


@node Records, Hash Tables, Queues, The language
@section Records
@cindex Records
@cindex Data types, records

The @dfn{record} is a convenient means of defining structured data
types which is similar to C struct. Each record is a distinct data
type, meaning that there will only be a single type-predicate matching
objects of any individual record type.

All definitions documented in this section are provided by the
@code{rep.data.records} module (@pxref{Modules}).

Record types are defined using the @code{define-record-type} macro,
this in turn defines a number of functions implementing the type. These
functions include a constructor, a type predicate, and a user-defined
set of field-accessor and -modifier functions.

@defmac define-record-type type (constructor fields@dots{}) [predicate] (field accessor [modifier])@dots{}

This macro creates a new record type storing an opaque object
identifying the type in the variable named @var{type}.

It then defines a function @var{constructor} with parameter list as
specified by the @var{fields@dots{}}, and a predicate function called
@var{predicate} if @var{predicate} is given.

The fields of the record are defined by the sequence of
@code{(@var{field} @var{accessor} [@var{modifier}])} forms, each form
describes a single field (named @var{field}, which may match one of
the constructor arguments).

The function @var{accessor} of each field will be defined that when
applied to an argument of the record type, returns the value stored in
the associated @var{field}. If the @var{modifier} name is defined a
function will be defined of that name, that when applied to a record
and an object, stores the object into the associated field of the
record.

Note that the @var{fields@dots{}} may include all the standard
lambda-list features (@pxref{Lambda Expressions}), including keyword
parameters and default values.
@end defmac

Here is an example record definition:

@lisp
(define-record-type :pare
  (kons x y)          ; constructor
  pare?               ; predicate
  (x kar set-kar!)    ; field @code{x}, its accessor and modifier
  (y kdr))            ; field @code{y} is read-only.
@end lisp

@noindent
the variable @code{:pare} is bound to the record type. Following this
definition, the record type could be used as follows:

@lisp
(define my-kons (kons 1 2))

(pare? my-kons)
    @result{} t

(kar my-kons)
    @result{} 1

(set-kar! my-kons 42)

(kar my-kons)
    @result{} 42
@end lisp

Printed representation of record objects is the name of their type in
angle brackets, e.g. for the above @code{pare} type, each object
prints as the string @samp{#<:pare>}. This may be redefined using the
@code{define-record-discloser} function.

@defun define-record-discloser type discloser
Associate the function @var{discloser} with the record type @var{type}.
When any record of this type is printed, @var{discloser} is applied to
the object, it should return the value that will actually be printed.
@end defun

For the above example, the following could be used:

@lisp
(define-record-discloser :pare (lambda (x) `(pare ,(kar x) ,(kdr x))))

(kons 'a 'b)
    @result{} (pare a b)
@end lisp

Constructors for records with large numbers of fields often benefit
from using keyword parameters. For example the @code{kons} record above
could be defined as follows (though this would make more sense if it
had more than two fields):

@example
(define-record-type :pare
  (kons #!key (kar 1) (kdr 2))
  pare?
  (kar kar set-kar!)
  (kdr kdr set-kdr!))

(kons #:kar 42) @result{} (pare 42 2)
(kons #:kdr 42) @result{} (pare 1 42)
@end example


@node Hash Tables, Guardians, Records, The language
@section Hash Tables
@cindex Hash tables
@cindex Data types, hash tables

The @code{rep.data.tables} module provides a flexible hash table
implementation (@pxref{Modules}). Each hash table is represented by a
lisp object satisfying the @code{tablep} predicate:

@defun tablep arg
Return true if @var{arg} is a hash table.
@end defun

Hash tables may be created by using the @code{make-table} and
@code{make-weak-table} functions:

@defun make-table hash-fun compare-fun
Create and return a new hash table. When storing and referencing keys
it will use the function @var{hash-fun} to map keys to hash codes
(positive fixnums), and the predicate function @var{compare-fun} to
compare two keys (should return true if the keys are considered equal).
@end defun

@defun make-weak-table hash-fun compare-fun
Similar to @code{make-table}, except that key-value pairs stored in the
table are said to be ``weakly keyed''. That is, they are only retained
in the table as long the key has not been garbage collected.

Unlike with tables created by the @code{make-table} function, the fact
that the key is stored in the table is not considered good enough to
prevent it being garbage collected.
@end defun

@defun table-ref table key
Return the value stored in hash table @var{table} indexed by object
@var{key}. Returns false if no such value exists.
@end defun

@defun table-bound-p table key
Returns true if the hash table @var{table} contains a value associated
with @var{key}.
@end defun

@defun table-set table key value
Associate the value @var{value} with @var{key} in hash table
@var{table}. Returns @code{value}.
@end defun

@defun table-unset table key
Remove any value stored in @var{table} associated with @var{key}.
@end defun

@defun table-walk function table
Call function @var{function} for every key-value pair stored in hash
table @var{table}. For each pair, the function is called with arguments
@code{(@var{key} @var{value})}.
@end defun

@defun table-size table
Returns the number of items currently stored in @var{table}.
@end defun

Several hash functions are also provided:

@defun string-hash string
Return an integer representing the string @var{string}.
@end defun

@defun symbol-hash symbol
Call @code{(string-hash (symbol-name @var{symbol}))}.
@end defun

@defun eq-hash arg
Return a hash value representing object @var{arg}. The hash is
generated from the @emph{address} of the object.
@end defun

@defun equal-hash arg
Return a hash value representing object @var{arg}. The hash is
generated from the @emph{contents} of the object.
@end defun


@node Guardians, Streams, Hash Tables, The language
@section Guardians
@cindex Guardians
@cindex Garbage collection, guardians

A @dfn{guardian} is a lisp object used to control when other data
objects are recycled by the garbage collector (@pxref{Garbage
Collection}).@footnote{Guardians were first described in a paper by R.
Kent Dybvig, Carl Bruggeman, and David Eby: @cite{"Guardians in a
Generation-Based Garbage Collector", ACM SIGPLAN Conference on
Programming Language Design and Implementation, June 1993.}} The usual
behaviour of the collector is to recycle objects as soon as they have
no remaining references.

Guardians allow the programmer to detect when a specified object would
be freed by the garbage collector, and to implement their own
allocation policy. This can be useful, for example, with objects that
have a high creation-overhead, and thus need to be cached for
performance reasons.

@defun make-guardian
This function allocates and returns a new guardian. Each guardian has a
list of data objects associated with it; some of which may have been
proved to have no remaining references to them (except from the
guardian system).

Calling the guardian object with a single argument, adds that value to
the list of objects associated with that guardian. Calling the guardian
with no arguments has one of two effects:

@itemize @bullet
@item
If objects are associated with the guardian that have been proved to be
inaccessible, then return one of those objects, and remove it from the
list of objects associated with the guardian.

@item
If none of the associated objects have been proved to be inaccessible,
then return the value false.
@end itemize
@end defun

Note the use of the word ``prove'' in the above description, objects
are only moved into a guardian's inaccessible set by the garbage
collector.

Here is an example use of the guardian system:

@lisp
;; create a new guardian object
(setq G (make-guardian))

;; create a lisp object
(setq x (cons 'a 'b))
   @result{} (a . b)

;; protect the object using the guardian
(G x)

;; remove the sole reference to the object
(setq x nil)
   @result{} ()

;; invoke the garbage collector, this will
;; prove that the value added to the
;; guardian is no longer accessible
(garbage-collect)

;; call the guardian to retrieve the
;; inaccessible value
(G)
   @result{} (a . b)

;; no more inaccessible values available
(G)
   @result{} ()
@end lisp


@node Streams, Hooks, Guardians, The language
@section Streams
@cindex Streams
@cindex Input and output

A @dfn{stream} is a Lisp object which is either a data sink (an
@dfn{output stream}) or a data source (an @dfn{input stream}). All
streams produce or consume sequences of 8-bit characters.

Streams are very flexible, functions using streams for their input and
output do not need to know the type of stream being accessed. For
example the Lisp reader (the @code{read} function) takes an input
stream as its sole argument, it then reads characters from this stream
until it has parsed a whole object. This stream could be a file, a
function, or even a string; the @code{read} function does not need to
differentiate.

@defun streamp arg
Return true if @var{arg} is a stream.
@end defun

@defun input-stream-p arg
Return true if @var{arg} is an input stream.
@end defun

@defun output-stream-p arg
Return true if @var{arg} is an output stream.
@end defun

@menu
* Input Streams::               Types of input stream
* Output Streams::              Types of output stream
* Input Functions::             Functions to read from streams
* Output Functions::            How to output to a stream
* Formatted Output::            Output by template
@end menu


@node Input Streams, Output Streams, , Streams
@subsection Input Streams
@cindex Input streams
@cindex Streams, input

These are the possible types of input stream, for the functions which
use them see @ref{Input Functions}.

@table @code
@item @var{file}
Characters are read from the file object @var{file}, for the functions
which manipulate file objects see @ref{Files}.

@item @var{function}
Each time an input character is required the @var{function} is called with
no arguments. It should return the character read (an integer) or false
if for some reason no character is available.

@var{function} should also be able to `unread' one character. When this
happens the function will be called with one argument---the value of
the last character read. The function should arrange it so that the
next time it is called it returns this character. A possible implementation
could be,

@lisp
(defvar ms-unread-char nil
  "If true the character which was pushed back.")

(defun my-stream (#!optional unread-char)
  (if unread-char
      (setq ms-unread-char unread-char)
    (if ms-unread-char
        (prog1
          ms-unread-char
          (setq ms-unread-char nil))
      ;; Normal case -- read and return a character from somewhere
      @dots{}
@end lisp

@item nil
Read from the stream stored in the variable @code{standard-input}.
@end table

It is also possible to use a string as an input stream. The string to
be read from must be applied to the @code{make-string-input-stream} function
and the result from this function used as the input stream.

@defun make-string-input-stream string @t{#!optional} start
Returns an input stream which will supply the characters of the string
@var{string} in order starting with the character at position @var{start}
(or from position zero if this argument is undefined).

@lisp
(read (make-string-input-stream "(1 . 2)"))
    @result{} (1 . 2)
@end lisp
@end defun

@defvar standard-input
The input stream which is used when no other is specified or is false.
@end defvar

Applications that embed Librep, or dynamically loaded
extensions, may provide further input stream types.


@node Output Streams, Input Functions, Input Streams, Streams
@subsection Output Streams
@cindex Output streams
@cindex Streams, output

These are the different types of output stream, for the functions which
use them see @ref{Output Functions}.

@table @code
@item @var{file}
Writes to the file object @var{file}. @xref{Files}.

@item @var{function}
The function @var{function} is called with one argument, either a string
or a character. This should be used as the circumstances dictate. If the
function returns a number it is the number of characters actually used,
otherwise it is assumed that all the characters were successful.

@item @var{process}
Writes to the standard input of the process object @var{process}. If
@var{process} isn't running an error is signalled. @xref{Processes}.

@item t
Appends the character(s) to the end of the status line message.

@item ()
Write to the stream stored in the variable @code{standard-output}.
@end table

It is also possible to store the characters sent to an output stream
in a string.

@defun make-string-output-stream
Returns an output stream. It accumulates the text sent to it for the benefit
of the @code{get-output-stream-string} function.
@end defun

@defun get-output-stream-string string-output-stream
Returns a string consisting of the text sent to the @var{string-output-stream}
since the last call to @var{get-output-stream-string} (or since this stream
was created by @code{make-string-output-stream}).

@lisp
(setq stream (make-string-output-stream))
    @result{} ("" . 0)
(prin1 keymap-path stream)
    @result{} ("(lisp-mode-keymap global-keymap)" . 64)
(get-output-stream-string stream)
    @result{} "(lisp-mode-keymap global-keymap)"
@end lisp
@end defun

@defvar standard-output
This variable contains the output stream which is used when no other
is specified (or when the given output stream is false).
@end defvar

@defvar standard-error
This variable contains the output stream which is used when an error
message is being reported.
@end defvar

Applications that embed Librep, or dynamically loaded
extensions, may provide further output stream types.


@node Input Functions, Output Functions, Output Streams, Streams
@subsection Input Functions
@cindex Input functions
@cindex Functions, input
@cindex Streams, input functions

@defun read-char stream
Read and return the next character from the input stream @var{stream}. If
the end of the stream is reached false is returned.
@end defun

@defun peek-char stream
returns the next character from the input-stream @var{stream},
@emph{without} removing that character from the head of the stream. if
no more characters are available returns nil.
@end defun

@defun read-chars stream count
read upto @var{count} characters from the input stream @var{stream},
returning a string containing the characters. If EOF is read before
reading @var{count} characters, the returned string will contain the
characters read up to that point. If no characters are read,
@code{nil} will be returned.
@end defun

@defun read-line stream
This function reads one line of text from the input stream
@var{stream}, a string containing the line (including the newline
character which terminates the line).

If the end of stream is reached before any characters can be read
false is returned, if the end of stream is reached but some
characters have been read (but not the newline) these characters are
made into a string and returned.

Note that unlike the Common Lisp function of the same name, the newline
character is not removed from the returned string.
@end defun

@defun read stream
This function is the function which encapsulates the Lisp reader
(@pxref{The Lisp Reader}). It reads as many characters from the input
stream @var{stream} as required to form the read syntax of a single
Lisp object (@pxref{Read Syntax}), this object is then returned.
@end defun

@defun read-from-string string @t{#!optional} start
Reads one Lisp object from the string @var{string}, the first character
is read from position @var{start} (or position zero).

@lisp
(read-from-string @var{string} @var{start})
@equiv{}
(read (make-string-input-stream @var{string} @var{start}))
@end lisp
@end defun


@node Output Functions, Formatted Output, Input Functions, Streams
@subsection Output Functions
@cindex Output functions
@cindex Functions, output
@cindex Streams, output functions

@defun write stream data @t{#!optional} length
Writes the specified character(s) to the output stream @var{stream}.
@var{data} is either the character or the string to be written. If
@var{data} is a string the optional argument @var{length} may
specify how many characters are to be written. The value returned
is the number of characters successfully written.

@lisp
(write standard-output "Testing 1.. 2.. 3..")
    @print{} Testing 1.. 2.. 3..
    @result{} 19
@end lisp
@end defun

@defun copy-stream input-stream output-stream
This function copies all characters which may be read from
@var{input-stream} to @var{output-stream}. The copying process is not
stopped until the end of the input stream is read. Returns the number
of characters copied.

Be warned, if you don't choose the streams carefully you may get a
deadlock which only an interrupt signal can break!
@end defun

@defun print object @t{#!optional} stream
Outputs a newline character to the output stream @var{stream}, then
writes a textual representation of @var{object} to the stream.

If possible, this representation will be the read syntax of
@var{object}.

@var{object} is returned.

@lisp
(print '(1 2 3))
    @print{}
    @print{} (1 2 3)
    @result{} (1 2 3)
@end lisp
@end defun

@defun prin1 object @t{#!optional} stream
Similar to @code{print} but no initial newline is output.

@lisp
(prin1 '(1 2 3))
    @print{} (1 2 3)
    @result{} (1 2 3)

(prin1 '|(xy((z]|)              ;A strange symbol
    @print{} \(xy\(\(z\]
    @result{} \(xy\(\(z\]
@end lisp
@end defun

@defun prin1-to-string object
Returns a string containing the characters that @code{prin1} would
output when it prints @var{object}.

@lisp
(prin1-to-string '(1 2 3))
    @result{} "(1 2 3)"
@end lisp
@end defun

@defun princ object @t{#!optional} stream
Prints a textual representation of @var{object} to the output stream
@var{stream}. No steps are taken to create output that @code{read} can
parse; in particular, no double-quote characters surround strings.

@lisp
(princ "foo")
    @print{} foo
    @result{} "foo"

(princ '|(xy((z]|)
    @print{} (xy((z]
    @result{} \(xy\(\(z\]
@end lisp
@end defun

Several variables may be used to control how objects are printed.

@defvar print-escape
This defines which control characters @code{print} and @code{prin1}
will escape (using backslashes). Possible values are:

@table @code
@item ()
Only escape double-quote and backslash characters.

@item newlines
Only escape double-quote, backslash, newline, @kbd{TAB}, and formfeed
characters.

@item t
Escape double-quote, backslash, and all control characters (anything
with a numeric value less than 32, or greater than 126).
@end table
@end defvar

@defvar print-length
This variable, if true, limits the number of elements printed
from lists.
@end defvar

@defvar print-level
This variable, if true, limits the recursion depth when
printing lists.
@end defvar


@node Formatted Output, , Output Functions, Streams
@subsection Formatted Output
@cindex Formatted output
@cindex Output, formatted
@cindex Streams, formatted output

@defun format stream template @t{#!rest} values
Writes to a stream, @var{stream}, a string constructed from the
format string, @var{template}, and list of arguments @var{values}.

If @var{stream} is false the resulting string will be returned,
not written to a stream.

@var{template} is a template for the output string, any @samp{%}
characters introduce a substitution, using the next unused argument.
The substitutions have the following syntax,

@example
%[@var{index}$][@var{flags}][@var{field-width}]@var{conversion}
@end example

@noindent
@var{index} is an optional decimal number specifying exactly which of
the @var{values} this conversion refers to (with the first at position
one), and is usually used when translating messages; by default the
next value is used.

@var{field-width} is a positive decimal integer, defining the size in
characters of the substitution output.

@var{conversion} is a character defining how to convert the
corresponding argument value to text. The default options are:

@table @samp
@item s
Write the printed representation of the value without quoting (as if from
the @code{princ} function).

@item S
Write the printed representation @emph{with} quoting enabled (like the
@code{prin1} function).

@item d
Output the value as a decimal number.

@item o
Write the value in octal.

@item x
@itemx X
In hexadecimal.

@item c
Write the character specified by the value.

@item %
Print a literal percent character. None of the @var{values} are used.
@end table

@var{flags} is a sequence of zero or more of the following characters,

@table @asis
@item @samp{_}
Left justify the substitution within the field.

@item @samp{^}
Truncate the substitution at the size of the field.

@item @samp{0}
Pad the field with zeros instead of spaces.

@item @samp{+}
For @samp{d}, @samp{x}, and @samp{o} conversions, output a leading plus
sign if the argument is positive.

@item @samp{ } (a space)
For @samp{d}, @samp{x}, and @samp{o} conversions, if the result doesn't
start with a plus or minus sign, output a leading space.
@end table

The list of @var{conversions} can be extended through the
@code{format-hooks-alist} variable; the strings created by these extra
conversions are formatted as if by the `s' conversion.

Note that the @var{field-width} and all flags currently have no effect
on the @samp{S} conversion, (or the @samp{s} conversion when the
argument isn't a string).

If @var{stream} isn't false (in which case the created string is
returned) the value of @var{stream} is returned.

@lisp
(format nil "foo %S bar 0x%x" '(x . y) 255)
    @result{} "foo (x . y) bar 0xff"

(format standard-output "The %2$s is %1$s!" "purple" "dog")
    @print{} The dog is purple!
    @result{} #<buffer *jade*>
@end lisp
@end defun

@defvar format-hooks-alist
This variable is an association-list, each element being
@code{(@var{char} . @var{function})}, defining extra conversions
for the @code{format} function.

If a conversion @samp{%@var{x}} is given, and the alist contains an
element whose car is the character @var{x}, the the associated function
is called with one value, the next argument to be formatted. It should
return the string to be inserted.
@end defvar


@node Hooks, Files, Streams, The language
@section Hooks
@cindex Hooks

A @dfn{hook} allows you to wedge your own pieces of Lisp code into the
operation of other functions, enable the extension of that
functionality. These pieces of code are evaluated via the hook and the
result is available to the hook's caller. One hook has already been
encountered, the @code{format-hooks-alist} variable (@pxref{Formatted
Output}).

@menu
* Functions As Hooks::          Some hooks are a single function,
* Normal Hooks::                Others may be a list of pieces of code
                                  to evaluate.
@end menu


@node Functions As Hooks, Normal Hooks, , Hooks
@subsection Functions As Hooks
@cindex Functions as hooks
@cindex Hooks, functions as

Some hooks only allow a single piece of code to be hooked in. Usually a
normally-undefined function is used; to install your hook defined a
function with the name of the hook. When the hook is to be evaluated
the function is called.

Generally the name of the hook's function will end in @code{-function}.

An alternative scheme is to use a variable to store the hook, its value
should be the function to call.


@node Normal Hooks, , Functions As Hooks, Hooks
@subsection Normal Hooks
@cindex Normal hooks
@cindex Hooks, normal

This is the standard type of hook, it is a variable whose value is a
list of functions. When the hook is evaluated each of the functions
will be called in turn.

The names of hooks of this type will normally end in @code{-hook}.

These functions are exported by the @code{rep.system} module.

@defun add-hook hook function @t{#!optional} at-end
This function adds a new function @var{function} to the list of
functions installed in the (list) hook @var{hook} (a symbol).

If @var{at-end} is true the new function is added at the end
of the hook's list of functions (and therefore will be called last when
the hook is evaluated), otherwise the new function is added to the
front of the list.

@lisp
text-mode-hook
    @result{} (#<closure fill-mode-on>)
(add-hook 'text-mode-hook my-function)
    @result{} (#<closure my-function> #<closure fill-mode-on>)
@end lisp
@end defun

@defun remove-hook hook function
This function removes the function @var{function} from the list of
functions stored in the (list) hook @var{hook} (a symbol).

@emph{All} instances of @var{function} are deleted from the hook.
@end defun

There are actually three calling conventions for this type of hook,
differing in how many of the functions in the list actually get called.
In this simplest form, @emph{all} functions are called. In an
@code{and} type hook, functions are only invoked while all others have
returned true. As soon as the first function in the hook returns
false, no others will be called. Finally, an @code{or} type hook
aborts when a function returns a true result.

@defun call-hook hook arg-list @t{#!optional} type

Call the hook named by the symbol @var{hook}, passing all functions the
arguments in the list @var{arg-list}. Note that @var{hook} may also be
the actual list of functions to call.

@var{type} defines how the return values of each function in the hook
are treated. If @var{type} is false they are ignored, if
@var{type} is the symbol @code{and} the hook aborts after a function
returns false, if @var{type} is @code{or} the hook aborts when a
function returns true.

In all cases the value returned by the last-evaluated function is
returned.
@end defun


@node Files, Processes, Hooks, The language
@section Files
@cindex Files

Librep allows you to manipulate files in the operating system's
filing system; a special type of Lisp object, a @dfn{file object}, is
used to represent files which have been opened for reading or writing
(through the streams mechanism, @pxref{Streams}).

Names of files are represented by strings, the syntax of file names is
defined by the underlying operating system: Librep simply treats
it as a string.

Many functions described in this chapter signal an error on failure,
though it's not stated explicitly.

Unless otherwise stated, all functions and variables described in the
following sections are exported by the @code{rep.io.files} module.

@menu
* File Names::                  Files are named by a string
* File Objects::                Lisp objects representing files
* File Information::            Predicates on files
* Manipulating Files::          Deleting, renaming and copying files
* Manipulating Directories::    Accessing directories
* Manipulating Symlinks::       Handling symbolic links
* File Handlers::               Extending the file name-space
* Remote Files::                Accessing remote files
@end menu


@node File Names, File Objects, , Files
@subsection File Names
@cindex File names
@cindex Names of files

A @dfn{file name} is a string identifying an individual file (or
directory) in the filing system (i.e. the disk). The exact syntax of
file names depends on the operating system. There are several functions
for manipulating file names.

@defun file-name-absolute-p file-name
Returns true when @var{file-name} is not specified relative to the
current directory.
@end defun

@defun file-name-directory file-name
This function returns the directory part of the file name string
@var{file-name}. This is the substring of @var{file-name} defining the
directory containing the file.

@lisp
(file-name-directory "/tmp/foo")
    @result{} "/tmp/"

(file-name-directory "foo")
    @result{} ""

(file-name-directory "foo/bar/")
    @result{} "foo/bar/"
@end lisp
@end defun

@defun file-name-nondirectory file-name
Returns the substring of the file name @var{file-name} which is
@emph{not} the directory part.

@lisp
(file-name-nondirectory "/tmp/foo")
    @result{} "foo"

(file-name-nondirectory "foo")
    @result{} "foo"

(file-name-nondirectory "foo/bar/")
    @result{} ""
@end lisp
@end defun

@defun file-name-as-directory file-name
Returns a string through which the item in the file system named by
@var{file-name} can be referred to as a directory.

@lisp
(file-name-as-directory "./foo")
    @result{} "./foo/"

(file-name-as-directory "./foo/")
    @result{} "./foo/"
@end lisp
@end defun

@defun directory-file-name directory-name
Returns a string through which the directory named by
@var{directory-name} can be referred to as a file.

@lisp
(directory-file-name "./foo/")
    @result{} "./foo"

(directory-file-name "./foo")
    @result{} "./foo"
@end lisp
@end defun

@defun expand-file-name file-name @t{#!optional} base-dir
Expands @var{file-name} assuming that it specifies a file relative to
@var{base-dir}. If @var{base-dir} is undefined it is taken as the
current value of the @code{default-directory} variable. While expanding
the file name, any obvious simplifications will be performed (e.g. on
Unix the removal of "." and ".." where possible).

Note that the returned file name will only be absolute if one of the
following conditions is met:

@enumerate
@item
@var{base-dir} (or @code{default-directory}) is absolute,

@item
@var{file-name} is already absolute.
@end enumerate

@lisp
(expand-file-name "foo" "./bar")
    @result{} "bar/foo"
@end lisp

Note for file handler implementors: when a handler is called for the
@code{expand-file-name} operation, it will only ever receive one
argument, the already expanded file name. The only action that may be
need to be taken is to simplify the file name (e.g. removing @file{.}
and @file{..} entries or whatever).
@end defun

@defun canonical-file-name file-name
This function returns the canonical name of the file referred to by the
string @var{file-name}. The canonical name of a file is defined such
that two files can be compared simply by comparing their canonical
names; if the names match, they refer to the same file.

(Note that the opposite isn't always true, if two canonical names don't
match the files could still be the same, for example via hard links. On
most operating systems, symbolic links will be expanded where
possible.

@lisp
(canonical-file-name "foo")
    @result{} "/home/john/src/librep/man/foo"
@end lisp
@end defun

@defun local-file-name file-name
Librep supports extensible file handling (@pxref{File
Handlers}), so file names may refer to files not residing in the
system's local file structure, and thus which are unavailable to other
programs.

This function returns either the absolute name of the file
@var{file-name}, if it is found in the local system, or false, if
the file does not.

@lisp
(local-file-name "foo")
    @result{} "/home/john/src/librep/man/foo"

(local-file-name "/john@@tango:foo")
    @result{} ()
@end lisp
@end defun

@defun make-temp-name
This function returns the name of a file which, when created, may be used
for temporary storage. Each time this function is called a unique name is
computed.

@lisp
(make-temp-name)
    @result{} "/tmp/00088aaa"

(make-temp-name)
    @result{} "/tmp/00088baa"
@end lisp
@end defun

@defvar default-directory
This variable names the current working directory. All relative file
names are interpreted starting from this location in the file system.
@end defvar


@node File Objects, File Information, File Names, Files
@subsection File Objects
@cindex File objects

A file object is a Lisp object which represents an open file in the
filing system. Any file object may be used as a stream (either input or
output) to access the contents of the file (@pxref{Streams}).

@defun filep object
This function returns true when its argument is a file object.
@end defun

@menu
* Creating File Objects::       Opening files
* Destroying File Objects::     Closing files
* Functions on File Objects::   Functions operating on file objects
@end menu


@node Creating File Objects, Destroying File Objects, , File Objects
@subsubsection Creating File Objects
@cindex Creating file objects
@cindex File objects, creating
@cindex Files, opening

@defun open-file file-name mode
This function opens the file called @var{file-name} (@pxref{File
Names}) and returns the new file object.

The @var{mode} argument is a symbol defining the access modes used to
open the file with, the options are:

@table @code
@item read
Open an existing file for reading only.

@item write
Open the file for writing only, if the file exists it is truncated to
zero length. Otherwise a new file is created.

@item append
Open the file for appending to, i.e. writing to the end of the file. If
the file doesn't exist it is created.
@end table
@end defun

The three standard I/O streams are also available as file handles.

@defun stdin-file
Return a file object representing the interpreters standard input.
@end defun

@defun stdout-file
Return a file object representing the interpreters standard output.
@end defun

@defun stderr-file
Return a file object representing the interpreters standard error.
@end defun

Attempting to close any of these files will result in the associated
stream being connected to @file{/dev/null}.


@node Destroying File Objects, Functions on File Objects, Creating File Objects, File Objects
@subsubsection Destroying File Objects
@cindex Destroying file objects
@cindex File objects, destroying
@cindex Files, closing

The easiest way to close a file is simply to eliminate all references to it,
subsequently the garbage collector will close it for you. It is better
to close files explicitly though since only a limited number of files may be
opened concurrently.

@defun close-file file-object
This function closes the file pointed to by the file object
@var{file-object}.

Subsequently, any stream accesses @var{file-object} are illegal and
will signal an error.
@end defun


@node Functions on File Objects, , Destroying File Objects, File Objects
@subsubsection Functions on File Objects
@cindex Functions on File Objects
@cindex File objects, functions

@defun seek-file file @t{#!optional} offset where
When called as @code{(seek-file @var{file})}, returns the distance in
bytes from the start of the file that the next character would be read
from.

When called as @code{(seek-file @var{file} @var{offset} [@var{where}])}
alters the position from which the next byte will be read. @var{where}
can be one of the values:

@table @code
@item ()
@var{offset} bytes after the current position.

@item start
@var{offset} bytes after the beginning of the file.

@item end
@var{offset} bytes before the end of the file.
@end table

Note that not all files may be seekable; if @code{(seek-file
@var{file})} returns false, indicating that the current position
is unknown, any attempts to set the current position will also fail.
@end defun

@defun flush-file file
This function flushes any buffered output to the file object
@var{file} to disk.
@end defun

@defun file-binding file
Returns the name of the file which the file object @var{file} is
currently bound to. Returns false if the file is currently unbound
(i.e. @code{close-file} was called on it).
@end defun

The next three functions are used when non-local files are being
accessed. See @ref{File Handlers} for more details.

@defun file-bound-stream file
If the file object @var{file} doesn't refer to a file in the local
filing system, return the stream that it is bound to (allowing the
file's contents to be accessed), this may or may not be another file
object.
@end defun

@defun file-handler-data file
Return the file-handler-specific data associated with the file object
@var{file}.
@end defun

@defun set-file-handler-data file data
Set the handler-specific data of file object @var{file} to @var{data}.
This should only be done by the handler owning the file.
@end defun

It's also possible to register a callback function to be invoked when
input is available on a file,

@defun set-input-handler local-file function
Arrange for @var{function} to be called whenever pending input is
available on @var{local-file}, a file object bound to a file in the
local file space.

Note that this makes @var{local-file} subsequently do non-blocking
input.

This function is normally only useful when @var{local-file} represents
a pipe or socket.
@end defun


@node File Information, Manipulating Files, File Objects, Files
@subsection File Information
@cindex File information

A number of functions exist which when given the name of a file return
one of the attributes relating to that file.

@defun file-exists-p file-name
Returns true when a file @var{file-name} exists.
@end defun

@defun file-regular-p file-name
Returns true when the file @var{file-name} is a `normal' file. This means
that it isn't a directory, device, symbolic link or whatever.
@end defun

@defun file-directory-p file-name
Returns true when the file @var{file-name} is a directory.
@end defun

@defun file-symlink-p file-name
Returns true when the file @var{file-name} is a symbolic link.
@end defun

@defun file-readable-p file-name
Returns true when the file @var{file-name} is readable.
@end defun

@defun file-writable-p file-name
Returns true when the file @var{file-name} is writable.
@end defun

@defun file-executable-p file-name
Returns true when the file @var{file-name} is executable.
@end defun

@defun file-owner-p file-name
Returns true when the ownership of the file @var{file-name} is
the same as that of any files written by the editor.
@end defun

@defun file-gid file-name
Returns the gid of the file @var{file-name}, as integer.
@end defun

@defun file-uid file-name
Returns the uid of the file @var{file-name}, as integer.
@end defun

@defun file-size file-name
Returns the number of bytes stored in the file named @var{file-name}.
@end defun

@defun file-nlinks file-name
Returns the number of hard links pointing to the file @var{file-name}. If
@var{file-name} has only one name the number will be one.
@end defun

@defun file-modes file-name
This function returns the access permissions of the file @var{file-name}.
This will be an integer whose format is undefined; it differs from
operating system to operating system.
@end defun

@defun file-modes-as-string file-name
Returns a ten-character string describing the attibutes of the file
called @var{file-name}

@lisp
(file-modes-as-string ".")
    @result{} "drwxr-sr-x"
@end lisp
@end defun

@defun set-file-modes file-name modes
This function sets the access permissions of the file @var{file-name} to
the integer @var{modes} (as returned by the @code{file-modes} function).
@end defun

@defun file-modtime file-name
Returns the system time at the last modification to the file
@var{file-name}, this will be in the usual timestamp format,
@xref{Timestamps}.
@end defun

@defun file-newer-than-file-p file-name1 file-name2
This function returns true if the file @var{file-name1} was modified
more recently than the file @var{file-name2} was.
@end defun


@node Manipulating Files, Manipulating Directories, File Information, Files
@subsection Manipulating Files
@cindex Manipulating files
@cindex Files, manipulating

@deffn Command delete-file file-name
This function deletes the file called @var{file-name}. When called
interactively @var{file-name} is prompted for.
@end deffn

@deffn Command rename-file file-name new-name
This function attempts to change the name of the file @var{new-name}
to @var{new-name}.

This won't work from one file system to another or if a file called
@var{new-name} already exists, in these cases an error is signalled.

This prompts for its arguments when called interactively.
@end deffn

@deffn Command copy-file file-name destination-name
Creates a new copy of the file @var{file-name} with the name
@var{destination-name}.

The access modes of the new file will be the same as those of the original
file.

The arguments are prompted for when this function is called interactively.
@end deffn

@node Manipulating Directories, Manipulating Symlinks, Manipulating Files, Files
@subsection Manipulating Directories
@cindex Reading directories
@cindex Files, manipulating directories

@deffn Command make-directory directory-name
Create a new directory called @var{directory-name}.
@end deffn

@deffn Command delete-directory directory-name
Delete the directory called @var{directory-name}. This only succeeds if
the directory in question is empty, otherwise an error is signalled.
@end deffn

@defun directory-files directory-name
Returns a list of the names of all items in the directory whose name is
@var{directory-name}. The names in the list will be relative to the
directory @var{directory-name}.

@lisp
(directory-files "/tmp/foo"
    @result{} ("bar" "subdir" "xyz" "." "..")
@end lisp
@end defun


@node Manipulating Symlinks, File Handlers, Manipulating Directories, Files
@subsection Manipulating Symbolic Links
@cindex Manipulating Symbolic Links
@cindex Symbolic Links, manipulating

@defun make-symlink name contents
Create a symbolic link called @var{name}, containing the string
@var{contents}.
@end defun

@defun read-symlink name
Return the string that is the contents of the symbolic link called
@var{name}. Signals an error if no such link exists.
@end defun


@node File Handlers, Remote Files, Manipulating Symlinks, Files
@subsection File Handlers
@cindex File Handlers

As noted earlier, Librep supports virtual files; that is it
allows file names to be accessed that don't reside on the local filing
system, or aren't normally valid as file names. This is achieved
through the use of @dfn{file handlers}, Lisp functions that have
signalled that they should be used to redirect all accesses to files
whose names match a particular regular expression (@pxref{Regular
Expressions}).

For example, in Unix, a leading tilde @file{~} expands to the
home directory. See below.

@defvar file-handler-alist
This variable contains a list of file handler declarations, each one of
the form @code{(@var{regexp} . @var{function})}. Whenever a file
operation is performed on a file whose name matches @var{regexp},
@var{function} is invoked to perform the action. The function is called
as @code{(@var{function} @var{operation} @var{args}@dots{})}, where
@var{operation} and @var{args} are from the original call.

For example if the @code{file-handler-alist} contains the entry
@code{("^~" . tilde-file-handler)}, then all file operations on files
starting with a tilde are redirected to the @code{tilde-file-handler}
function.

Thus if a form @code{(file-exists-p "~/foo")} is executed, it would
result in a call to @code{tilde-file-handler} as
@code{(tilde-file-handler 'file-exists-p "~/foo")}.
@end defvar

The list of operations that may be redirected to a file handler is:
@code{file-name-absolute-p}, @code{expand-file-name},
@code{local-file-name}, @code{canonical-file-name},
@code{file-name-nondirectory}, @code{file-name-directory},
@code{file-name-as-directory}, @code{directory-file-name},
@code{open-file}, @code{close-file}, @code{flush-file},
@code{seek-file}, @code{write-buffer-contents},
@code{read-file-contents}, @code{insert-file-contents},
@code{delete-file}, @code{rename-file}, @code{copy-file},
@code{copy-file-to-local-fs}, @code{copy-file-from-local-fs},
@code{make-directory}, @code{delete-directory}, @code{file-exists-p},
@code{file-regular-p}, @code{file-readable-p}, @code{file-writable-p},
@code{file-directory-p}, @code{file-symlink-p}, @code{file-owner-p},
@code{file-nlinks}, @code{file-size}, @code{file-modes},
@code{file-modes-as-string}, @code{set-file-modes},
@code{file-modtime}, @code{directory-files},
@code{make-symlink}, @code{read-symlink}.

There are several undefined functions in this list. The
@code{write-buffer-contents}, @code{read-file-contents}, and
@code{insert-file-contents} pertain to the Jade text editor. The other
two are defined as follows.

@deffn Operation copy-file-to-local-fs file-name local-name
Called when copying files between file handlers, this operation should
copy the file matching the handler @var{file-name}, to the file on the
local file system @var{local-name}.
@end deffn

@deffn Operation copy-file-from-local-fs local-name file-name
Called when copying files between file handlers, this operation should
copy the local file @var{file-name} to the file matching the handler
@var{file-name}.
@end deffn

To prevent infinite recursion, while a particular operation is being
processed by a file handler, that operation may not be passed back to
the same handler.

To allow file handlers to handle the @code{open-file} operation, it is
possible to create file handles from arbitrary streams.

@defun make-file-from-stream file-name stream handler
Return a new file object that refers to the logical file called
@var{file-name}, that is not in the local filing system. All access to
the file object will be directed through the stream object
@var{stream}, and the file handler function @var{handler}.
@end defun

An alternative method of opening remote files is to use a temporary
file in the local file system with either one (@code{read} or
@code{write} modes), or two (@code{append} mode) synchronisations with
the remote system. This is the method used by the FTP remote file
backend (see the next section). It has the advantage of simplifying the
@code{seek-file} operation.

@subheading Default File Handlers
Librep provides the following file handlers by default:

@itemize

@item Tilde expansion

In Unix, a leading tilde @file{~} is expanded to the user's home
directory.
@item Archives as directories

Some archive files' contents are treated like a directory, by adding
@t{``#tar/''}. For example, the file @file{foo/bar.jl} stored in
@file{/dir/baz.tar.gz} can be accessed with 
@lisp
(load "/dir/baz.tar.gz#tar/foo/bar")
@end lisp
Supported compressions are gz with suffixes @code{gz} and @code{tgz}, 
bzip2 with @code{bz2}, lzma with @code{xz}, @code{lz} and @code{lzma}.
@end itemize

@node Remote Files, , File Handlers, Files
@subsection Remote files
@cindex Remote files
@cindex Files, remote
@cindex File handlers, remote files

Since one of the intentions for file handlers is to allow remote files
to be accessed, a common method of providing new methods of doing this
has been implemented, in the @file{remote.jl} Lisp library.

Accessing a file name matching the regular expression:

@example
^/(([a-zA-Z0-9._-]+)@@)?([a-zA-Z0-9._-]+):
@end example

@noindent
for example @file{/john@@host.com:file} refers to a file called
@samp{file} owned by the user @samp{john}, on the system
@samp{host.com}.

If no username is specified explicitly, two variables are used to
select the user:

@defvar remote-host-user-alist
An alist mapping host regexps to the default user name to use for
remote file connections to that host.
@end defvar

@defvar remote-default-user
User name to use for remote file connections when otherwise
unspecified. By default the current user name on the local system.
@end defvar

Two variables control how individual hosts are matched to methods of
accessing files.

@defvar remote-auto-backend-alist
An alist of @code{(@var{host-regexp} . @var{backend-type})} mapping
host names to methods of accessing remote files.
@end defvar

@defvar remote-default-backend
A symbol defining the method to use for otherwise unselected hosts.
@end defvar

A method of accessing files, or a @dfn{backend} is a symbol whose
@code{remote-backend} property names a function to call when files need
to be accessed. For example the @code{ftp} backend is initialised as:

@lisp
(put 'ftp 'remote-backend remote-ftp-handler)
@end lisp

The backend function is called as @code{(@var{function}
@var{split-name} @var{operation} @var{args})}. The @var{split-name} is
a three-element list, @code{(@var{user-or-nil} @var{host} @var{file})}
defining the file to be accessed. The other options are as usual.
Further details can be found in the @file{remote.jl},
@file{remote-ftp.jl} and @file{remote-rcp.jl} Lisp source files.

The @code{ftp} backend is currently the most well-developed, several
functions and variables may be used to customise its behaviour.

@defun remote-ftp-add-passwd user host passwd
Add the string @var{passwd} as the password for the FTP session
connecting to @var{user@@host}.
@end defun

@defvar remote-ftp-show-messages
When true (the default), messages are displayed as FTP commands are
executed.
@end defvar

@defvar remote-ftp-display-progress
When true (the default) display progress of FTP transfers.
@end defvar

@defvar remote-ftp-anon-users
A regular expression matching the user names for ``anonymous'' FTP
sessions.
@end defvar

@defvar remote-ftp-anon-passwd
The string to send as the passwd of an anonymous FTP session. By
default the current uses email address.
@end defvar

There is a problem with the @code{ftp} backend however; due to
limitations in the FTP protocol, not all Librep file operations
are supported, with the most obvious exception being the
@code{make-symlink} function.

When this is a problem it may be possible to use rep's custom file
transfer protocol. If it is possible to use @code{rsh} to connect to
the remote host in question, then the @code{rep} backend may be used.

The @code{rep-remote} program distributed with Librep must exist
on the remote host, this is executed via @code{rsh} and provides a
protocol for executing all of Librep's file operations on that
host. See the @file{lisp/remote-rep.jl} file in the distribution for
more details.


@node Processes, String Functions, Files, The language
@section Processes
@cindex Processes
@cindex Subprocesses

When running on a Unix-style operating system Librep allows you
to launch and control an arbitrary number of subprocesses. These
subprocesses can run either synchronously or asynchronously in respect
to the Lisp system; data can be sent to the @code{stdin} channel and
any output from the process is automatically written to a specified
Lisp output stream.

Unless otherwise stated, all functions and variables described in the
following sections are exported by the @code{rep.io.processes} module.

@menu
* Process Objects::             Lisp objects associated with subprocesses
* Asynchronous Processes::      Subprocesses running in parallel
* Synchronous Processes::       Subprocesses which run to completion
* Process I/O::                 Input and output with subprocesses
* Process States::              Suspending subprocesses
* Signalling Processes::        Sending signals to subprocesses
* Process Information::         Information stored in a process object
* Shell Commands::              Executing shell commands
@end menu


@node Process Objects, Asynchronous Processes, , Processes
@subsection Process Objects
@cindex Process objects

A @dfn{process object} is a type of Lisp object used to provide a link
between a `physical' process running in the operating system and the
Lisp system. Each process object consists of a number of values
(references to other Lisp objects); these values are used when the
object is used to run a subprocess.

Process objects which aren't currently being used to run a subprocess
store the exit value of the last subprocess which was run on that object.

@defun processp object
This function returns true when its argument is a process object.
@end defun

The programmer-accessible components of a process object are,

@table @dfn
@item Output stream
A normal Lisp output stream (@pxref{Output Streams}), all data which the
subprocess outputs to its @code{stdout} channel is copied to this
output stream. @xref{Process I/O}.

@item Error stream
A normal Lisp output stream (@pxref{Output Streams}), all data which
the subprocess outputs to its @code{stderr} channel is copied to this
output stream. Unless explicitly specified error output goes to the
@code{stdout} stream. @xref{Process I/O}.

@item State change function
A Lisp function, called each time the state of the subprocess being run
on the object changes. @xref{Process States}.

@item Program name
The name of the program (a string) to execute when the subprocess is created.

@item Program arguments
A list of strings defining the arguments which the program executed
is given.

@item Directory
When a subprocess is started its current working directory is set to
the directory named by this component of its process object.

@item Connection type
Asynchronous subprocesses (@pxref{Asynchronous Processes}) use this
component to decide how to connect to the I/O channels of the subprocess.
Current options include pseudo-terminals and pipes.
@end table

@defun make-process @t{#!optional} output-stream state-function directory program args
This functions creates and returns a new process object. @emph{No subprocess
will be started.}

The optional arguments are used to define the values of the components of
the new process object, any undefined components will be set to default
or null values.
@end defun

For each component of a process object two functions exist; one to
read the component's value in a specific process object, the other
to set the component's value.

@defun process-prog process
Returns the value of the program name component of the process object
@var{process}.
@end defun

@defun set-process-prog process prog-name
Sets the value of the program name component of the process object
@var{process} to the string @var{prog-name}, then returns @var{prog-name}.
@end defun

@defun process-args process
Returns the value of the program arguments component of the process object
@var{process}.
@end defun

@defun set-process-args process arg-list
Sets the value of the program arguments component of the process object
@var{process} to the list @var{arg-list}, then returns @var{arg-list}.
@end defun

@defun process-dir process
Returns the value of the directory component of the process object
@var{process}.
@end defun

@defun set-process-dir process directory
Sets the value of the directory component of the process object
@var{process} to the string @var{directory}, then returns @var{directory}.
@end defun

@defvar process-environment
This is a list of environment variable definitions, as well as being
used by the @code{setenv} and @code{getenv} functions
(@pxref{Environment Variables}), it also provides the environment of
all started subprocesses.

@lisp
(car process-environment)
    @result{} "LOGNAME=john"
@end lisp
@end defvar

@defun active-processes
Returns a list containing all active (i.e. running or stopped) process
objects.
@end defun


@node Asynchronous Processes, Synchronous Processes, Process Objects, Processes
@subsection Asynchronous Processes
@cindex Asynchronous processes
@cindex Processes, asynchronous

An @dfn{asynchronous process} is one that runs in parallel with Lisp
evaluation, basically this means that once the subprocess has been
started (by the @code{start-process} function) Librep will carry
on as normal.

The event loop checks for output from asynchronous processes, any found
is copied to the process' output stream, and calls the the process' state
change function when necessary (@pxref{Process States}). Alternatively
the @code{accept-process-output} function can be called to explicitly
allow output to be processed.

When using asynchronous processes you have a choice as to the Unix
mechanism used to connect the @code{stdin}, @code{stdout} and
@code{stderr} streams of the subprocess to Librep's process.

The two options currently available are pipes or pseudo-terminals; in
general pseudo-terminals should only be used to provide a direct
interface between the user and a process (i.e. the @samp{*shell*}
buffer) since they allow job control to work properly. At other times
pipes will be more efficient and are used by default. However, there
are cases where the buffering characteristics of pipes mean that ptys
must be used.

@defun start-process @t{#!optional} process program @t{#!rest} args
This function starts an asynchronous subprocess running on the process
object @var{process}. If @var{process} is undefined a new process
object is created (by calling the function @code{make-process} with all
arguments undefined).

The function always returns the process object which the subprocess has
been started on. If for some reason the subprocess can't be created an
error of type @code{process-error} is signalled.

The optional argument @var{program} is a string defining the name of
the program to execute, it will be searched for in all the directories
in the @code{PATH} environment variable. The @var{args} are strings to
pass to the subprocess as its arguments.

When defined, the optional arguments overrule the values of the related
components of the process object.

The following example runs the @code{ls} program asynchronously, its output
is sent to the @code{standard-output} stream.

@lisp
(let
    ((process (make-process standard-output)))
  (start-process process "ls" "-s"))
@end lisp
@end defun

Note that when Librep exits it kills all of its asynchronous
subprocesses which are still running without warning.

@defun process-connection-type process
Returns the value of the connection type component of the process object
@var{process}. See the documentation of the @code{set-process-connection-type}
function for the values this may take.
@end defun

@defun set-process-connection-type process symbol
Sets the value of the connection type component of the process object
@var{process} to @var{symbol}, then returns @var{symbol}.

@var{symbol} should be one of the following symbols,

@table @code
@item pty
Use pseudo-terminals to connect to subprocesses running asynchronously on
this process object.

@item pipe
Use standard Unix pipes to connect, this is the default value of this
component.

@item socketpair
Uses a connected pair of sockets.
@end table
@end defun

Note that currently only the @code{pipe} connection type allows the
normal and error output streams of the process to be separated.


@node Synchronous Processes, Process I/O, Asynchronous Processes, Processes
@subsection Synchronous Processes
@cindex Synchronous processes
@cindex Processes, synchronous

When a @dfn{synchronous process} is started Librep waits for it
to terminate before continuing; they are usually used when a Lisp
program must invoke an external program as part of its function, i.e.
the auto-compression feature runs the compression program @code{gzip}
synchronously when it needs to compress a buffer.

Unlike asynchronous processes their is no choice between pipes and
pseudo-terminals for connecting to a subprocess. Instead, it is
possible to link the @code{stdin} channel of a synchronous process to a
named file.

For shell command invocation, see @xref{Shell Commands}.

@defun call-process @t{#!optional} process input-file-name program @t{#!rest} args
This function starts a process running on the process object
@var{process}. If @var{process} is undefined a new process object is
created by calling the @code{make} function.

If defined, the string @var{input-file-name} names the file to connect
to the standard input of the subprocess, otherwise the subprocess'
input comes from the null device (@file{/dev/null} on UNIX).

The optional arguments @var{program} and @var{args} define the name of
the program to invoke and any arguments to pass to it. The program will
be searched for in all directories listed in the
@code{process-environment} variable.

If any of the optional parameters are unspecified they should have been
set in the @var{process-object} prior to calling this function.

After successfully creating the new subprocess, this function simply
copies any output from the process to the output stream defined by the
output stream component of the process object. When the subprocess
exits its exit-value is returned (an integer). Note that the exit-value
is the value returned by the @code{process-exit-value} function, see
@ref{Process Information}.

If, for some reason, the new subprocess can't be created an error of
type @code{process-error} is signalled.
@end defun

The following function definition is taken from the @file{gzip.jl}
file, it shows how the @code{call-process} function can be used to
uncompress a file into a buffer (for Jade).

@lisp
;; Uncompress FILE-NAME into the current buffer
(defun gzip-uncompress (file-name)
  (let
      ((proc (make-process (current-buffer))))
    (message (concat "Uncompressing `" file-name "'") t)
    ;; gunzip can do .Z files as well
    (unless (zerop (call-process proc nil "gunzip" "-c" file-name))
      (signal 'file-error (list "Can't gunzip file" file-name)))))
@end lisp

The user is able to interrupt synchronous subprocesses (for example if
they seem to have got wedged somehow). Each time a user-interrupt is
received by Librep (i.e. the @code{INT} signal), a stronger
signal is sent to the subprocess. First an interrupt signal, then a
termination signal, before finally a non-ignoreable quit signal is
sent.


@node Process I/O, Process States, Synchronous Processes, Processes
@subsection Process I/O
@cindex Process I/O

It is only possible for lisp programs to explicitly send input data to
@emph{asynchronous} processes (by the time it's possible to call a
function to send data to a synchronous process, the process will
already have terminated!). Simply use the process object which an
asynchronous process is running on as a normal Lisp input stream, any
strings or characters written to the stream will immediately be copied
to the @code{stdin} channel of the subprocess.

With synchronous processes, the only control over input data possible
is by giving the @code{call-process} function the name of a file
containing the subprocess' input data.

Output data from subprocesses is handled the same way by both
asynchronous and synchronous processes: it is simply copied to the
stream defined by the output stream component of the subprocess'
process object.

@defun process-output-stream process
Returns the value of the output stream component of the process object
@var{process}.
@end defun

@defun set-process-output-stream process stream
Sets the value of the output stream component of the process object
@var{process} to the stream @var{stream}, then returns @var{stream}.
@end defun

By default the @code{stdout} and @code{stderr} streams are combined,
use the @code{set-process-error-stream} function to separate them.
(Note that this currently only works with @code{pipe} connection
types.)

@defun process-error-stream process
Returns the value of the error stream component of the process object
@var{process}.
@end defun

@defun set-process-error-stream process stream
Sets the value of the error stream component of the process object
@var{process} to the stream @var{stream}, then returns @var{stream}.
@end defun

Output from asynchronous subprocesses (this includes changes of state
as well as stream output) is only propagated at well-defined times.
Either when in the read stage of the read-eval-print, or input, loop,
or when the @code{accept-process-output} or @code{sit-for} functions
are called.

@defun accept-process-output @t{#!optional} seconds milliseconds
Wait @var{seconds} plus @var{milliseconds} for output from any
asynchronous subprocesses. If any arrives, process it, then return
false. Otherwise return true. If either of the arguments is
undefined, they count as zero in the addition.
@end defun

@defun sit-for @t{#!optional} seconds milliseconds
Wait for input to arrive and be processed. No more than @var{seconds}
seconds plus @var{milliseconds} milliseconds will be waited. If at the
end of this time no input has arrived, return true. Otherwise
return false if input was found.

Note that this function is only distinct to
@code{accept-process-output} when Librep is embedded in another
application, or an extension has been loaded that provides an event
loop (such as the @code{gtk} binding). In this case other input forms,
such as user input, for example, can preempt the timeout.

This function is exported by the @code{rep.system} module.
@end defun

@xref{Streams}.


@node Process States, Signalling Processes, Process I/O, Processes
@subsection Process States
@cindex Process states

Each process object has a @dfn{state} associated with it; this depends on
the status of the subprocess currently running on the process object (or
not as the case may be).

The possible states are,

@table @dfn
@item running
This state means that the subprocess using this process object is currently
running, i.e. it hasn't been stopped.

@item stopped
Means that the subprocess has been temporarily suspended from running.

@item unused
This means that the process object is free to have a new subprocess created
on it.
@end table

Predicates exist which test whether a given process object is in one of
these states.

@defun process-running-p process-object
Returns true when @var{process-object} is in the running state.
@end defun

@defun process-stopped-p process-object
Returns true when @var{process-object} is in the stopped state.
@end defun

@defun process-in-use-p process-object
Returns true when @var{process-object} is @emph{not} in the unused
state.
@end defun

The following two functions are used to stop and then subsequently
continue a process running.

@defun stop-process process-object @t{#!optional} whole-group
This function suspends execution of the subprocess running on the
process object @var{process-object}.

If @var{whole-group} is true all subprocesses in the
process group of @var{process-object} are stopped.
@end defun

@defun continue-process process-object @t{#!optional} whole-group
Use this function to continue a subprocess executing after it has been
stopped (by the @code{stop-process} function).

If @var{whole-group} is true all subprocesses in the
process group of @var{process-object} are continued.
@end defun

The state change function component of a process object defines a function
which will be called each time the state of the process object changes. If
your program needs to be informed when an asynchronous process terminates
this function is the way to do it.

@defun process-function process
Returns the value of the state change function component of the process object
@var{process}.
@end defun

@defun set-process-function process function
Sets the value of the state change function component of the process object
@var{process} to the function @var{function}, then returns @var{function}.
@end defun

@node Signalling Processes, Process Information, Process States, Processes
@subsection Signalling Processes
@cindex Signalling processes
@cindex Processes, signalling

@defun interrupt-process process-object @t{#!optional} whole-group
Sends the @code{SIGINT} signal to @var{process-object}.
@end defun

@defun kill-process process-object @t{#!optional} whole-group
Sends the @code{SIGKILL} signal to the @var{process-object}.
@end defun

Note that the functions @code{stop-process} and @code{continue-process}
also send signals to the subprocess.

@defun signal-process process signal @t{#!optional} whole-group
Send the signal @var{signal} to the process @var{process}; if
@var{whole-group} is true the signal is also sent to all
processes in the process group of @var{process}.

@var{process} may be either a Lisp process object, or an integer
defining the pid of the process to signal (not necessarily started by
Librep).

@var{signal} may either be an integer defining the actual signal
number, or a symbol naming the signal. All names are as usual but with
the preceding @code{SIG} removed, for example the @code{SIGINT} signal
would be sent by using the symbol @code{INT}. If a named signal doesn't
exist on the current operating system, an error is raised.

Returns true if the signal was sent successfully.
@end defun

As with the UNIX @code{kill} system call, @code{signal-process} may
also be used to test whether a process with a particular pid is
currently active, by using a signal with value zero.


@node Process Information, Shell Commands, Signalling Processes, Processes
@subsection Process Information
@cindex Process information

@defun process-id process-object
This function returns the operating-system identifier associated with the
subprocess currently running on the process object @var{process-object}.
@end defun

@defun process-exit-value process-object
Returns the integer representing the return code of the last subprocess
to be run on @var{process-object}.

If no subprocess has been run on @var{process-object}, @var{process-object}
is currently in the running state or the last subprocess exited abnormally
(i.e. from a terminal signal) false is returned.
@end defun

@defun process-exit-status process-object
This function returns the integer that was the exit status of the last
subprocess which was run on the process object @var{process-object}.

Note that the exit status is @emph{not} the value given to the @code{exit}
function in a C program, use the @code{process-exit-value} to access this
value.

If no process has been run on @var{process-object}, or the process is currently
in the running state false is returned.
@end defun

@node Shell Commands, , Process Information, Processes
@subsection Executing Shell Commands
@cindex Executing shell commands
@cindex Shell commands, executing

Convenient shell invocatino is possible, with its I/O going to the same
places as the interpreter's.

@defun system command
Execute the shell command @var{command} synchronously, returning its
exit status. An error will be signalled if the shell process could not
be started.

The @code{stdin}, @code{stdout} and @code{stderr} streams of the shell
are left as in the interpreter process.

The subprocesses environment is copied from the current value of the
@code{process-environment} variable.
@end defun

Note that the exit status is @emph{not} the same as the return code of
the command. It depends on the operating system, but under UNIX the
return code can be found through right-shifting the exit status by
eight bits. Low non-zero values represent that the process was killed
by a signal.

It is possible to interrupt a running shell process in the same way as
with a normal synchronous process (@pxref{Synchronous Processes}).
Interrupt the interpreter, it will send progressively harder-to-ignore
signals to the child each interrupt, until it is eventually terminated.

@node String Functions, utf-8, Processes, The language
@section String Functions
@cindex String functions

@defun translate-string string map
Applies the @var{map} to each character in the @var{string}. @var{map}
is also string, each character represents the translation for an ASCII
character of that characters position in the string. If the string is
less than 256 chars long any undefined characters will remain
unchanged.

For example, if @var{string} contains the character @samp{A}, with
ASCII code 65, then it would be replaced by the 65th character in the
string @var{map}.

Note that the @var{string} really is modified, no copy is made
@end defun

@defvar upcase-table
A @code{translate-string} compatible translation map to convert
lowercase characters to uppercase characters.
@end defvar

@defvar downcase-table
A map to convert uppercase characters to lowercase.
@end defvar

@defvar flatten-table
A translation map to convert newline characters to spaces.
@end defvar

@lisp
(translate-string "Foo" upcase-table)
    @result{} "FOO"

(translate-string "Foo" downcase-table)
    @result{} "foo"
@end lisp

@defun complete-string template list @t{#!optional} ignore-case
Return a string whose beginning matches the string @var{template}, and
is unique in the set of all strings in @var{list} which also match
@var{template}. If @var{ignore-case} is true, all matching
ignores case of characters.

@lisp
(complete-string "foo" '("bar" "foobar" "forbarf" "foobat"))
    @result{} "fooba"
@end lisp
@end defun

@defun string-head-eq string-1 string-2
Returns t if @var{string-2} matches the beginning of @var{string-1}.

@lisp
(string-head-eq "foobar" "foo")
    @result{} t

(string-head-eq "foo" "foobar")
    @result{} ()
@end lisp
@end defun

@defun string-upper-case-p string
Return true if @var{string} contains no lower case characters.
@end defun

@defun string-lower-case-p string
Return true if @var{string} contains no upper case characters.
@end defun

@defun string-capitalized-p string
Return true if the first character of @var{string} is upper case.
@end defun

@defun string-upcase string
Return a new string, an upper case copy of @var{string}.
@end defun

@defun string-downcase string
Return a new string, a lower case copy of @var{string}.
@end defun

@defun capitalize-string string
Return a new string, a copy of @var{string} with the first character in
upper case.
@end defun

@defun mapconcat function sequence separator
Call @var{function} for each member of @var{sequence}, concatenating
the results. Between each pair of results, insert @var{separator}.
Return the resulting string.
@end defun

@defun string->number string &optional radix
Return the number represented by @var{string}. If @var{radix} is
specified, the number is parsed from that base, otherwise base 10 is
assumed.
@end defun

@defun number->string num &optional radix
Return a string containing a printed representation of the number
@var{num}. If @var{radix} is specified, print the number in that base,
otherwise print it in base 10.
@end defun

@node utf-8, Regular Expressions, String Functions, The language
@section utf-8
@cindex utf-8

Some functions for utf-8 strings are available.

They assume that the string is encoded in utf-8. Otherwise, the
behavior is not defined. Defined in @code{rep.util.utf8}.

@defun utf8-string-length string
Returns the number of characters of utf-8 encoded @var{string}.
@end defun

@defun utf8-substring string start @t{#!optional} end
Returns the portion of @var{string}, encoded in utf-8, starting at
character number @var{start} and ending at the character before
@var{end} (or the end of the string if @var{end} is not given). All
indices start at zero.
@end defun

@node Regular Expressions, Time and Date, utf-8, The language
@section Regular Expressions
@cindex Regular expressions
@cindex Regexps

Regular expressions (or @dfn{regexps}) are a powerful method of
matching patterns in strings. Librep uses the @code{regexp(3)}
implementation by Henry Spencer, with some modifications that I have
made. It comes with this banner:

@quotation
Copyright (c) 1986 by University of Toronto.@*
Written by Henry Spencer.  Not derived from licensed software.

Permission is granted to anyone to use this software for any
purpose on any computer system, and to redistribute it freely,
subject to the following restrictions:

@enumerate
@item
The author is not responsible for the consequences of use of
this software, no matter how awful, even if they arise
from defects in it.

@item
The origin of this software must not be misrepresented, either
by explicit claim or by omission.

@item
Altered versions must be plainly marked as such, and must not
be misrepresented as being the original software.
@end enumerate
@end quotation

@menu
* Regexp Syntax::               How to write regular expressions
* Regexp Functions::            How to use them
@end menu


@node Regexp Syntax, Regexp Functions, , Regular Expressions
@subsection Regular Expression Syntax
@cindex Regular expression syntax
@cindex Regexp syntax
@cindex Syntax of regexps

The syntax of a regular expression is as follows (this is adapted from
the manual page):

A regular expression is zero or more @dfn{branches}, separated by
@samp{|}. It matches anything that matches one of the branches.

A branch is zero or more @dfn{pieces}, concatenated. It matches a match
for the first, followed by a match for the second, etc.

A piece is an @dfn{atom} possibly followed by @samp{*}, @samp{+}, or
@samp{?}. An atom followed by @samp{*} matches a sequence of 0 or more
matches of the atom. An atom followed by @samp{+} matches a sequence of
1 or more matches of the atom. An atom followed by @samp{?} matches a
match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for
the regular expression), a @dfn{range} (see below), @samp{.} (matching
any single character), @samp{^} (matching the null string at the
beginning of the input string), @samp{$} (matching the null string at
the end of the input string), one of the strings @samp{\s}, @samp{\S},
@samp{\w}, @samp{\W}, @samp{\d}, @samp{\D}, @samp{\b}, @samp{\B}, or a
@samp{\} followed by a single character (matching that character), or a
single character with no other significance (matching that character).

A @dfn{range} is a sequence of characters enclosed in @samp{[]}. It
normally matches any single character from the sequence. If the
sequence begins with @samp{^}, it matches any single character
@emph{not} from the rest of the sequence. If two characters in the
sequence are separated by @samp{-}, this is shorthand for the full list
of ASCII characters between them (e.g. @samp{[0-9]} matches any decimal
digit). To include a literal @samp{]} in the sequence, make it the
first character (following a possible @samp{^}). To include a literal
@samp{-}, make it the first or last character.

Also, any of the @samp{*}, @samp{+} or @samp{?} operators can be
suffixed by a @samp{?} character (i.e. @samp{*?}, @samp{+?},
@samp{??}). The meaning of the operator remains the same but it becomes
@dfn{non-greedy}. This means that it will match the @emph{smallest}
number of characters satisfying the regular expression, instead of the
default behaviour which is to match the @emph{largest}.

The backslash-introduced atoms have the following meanings:

@table @samp
@item \s
Match any whitespace character.

@item \S
Match any non-whitespace character.

@item \w
Match any alphanumeric or underscore character.

@item \W
Match any non-(alphanumeric or underscore) character.

@item \d
Match any numeric character.

@item \D
Match any non-numeric character.

@item \b
Match the null string between two adjacent @samp{\w} and @samp{\W}
characters (in any order).

@item \B
Match the null string that is not between two adjacent @samp{\w} and
@samp{\W} characters.
@end table

@noindent
Some example legal regular expressions could be:

@table @samp
@item ab*a+b
Matches an @samp{a} followed by zero or more @samp{b} characters, followed by
one or more @samp{a} characters, followed by a @samp{b}. For example,
@samp{aaab}, @samp{abbbab}, etc@dots{}

@item (one|two)_three
Matches @samp{one_three} or @samp{two_three}.

@item ^cmd_[0-9]+
@itemx ^cmd_\d+
Matches @samp{cmd_} followed by one or more digits, it must start at the
beginning of the line.
@end table


@node Regexp Functions, , Regexp Syntax, Regular Expressions
@subsection Regexp Functions
@cindex Regexp functions
@cindex Matching strings
@cindex String matching

These functions are exported by the @code{rep.regexp} module.

@defun quote-regexp string
Return a version of @var{string}, such that when used as a regexp, it
will match the original contents of @var{string} verbatim, and nothing
else. This involves quoting regexp meta-characters.

@lisp
(quote-regexp "abc")
    @result{} "abc"

(quote-regexp "a+c")
    @result{} "a\\+c"
@end lisp
@end defun

@defun string-match regexp string @t{#!optional} start ignore-case
Returns true if the string @var{string} matches the regular
expression @var{regexp}. The string matches if executing the regexp at
@emph{any} position in the string succeeds.

When defined, @var{start} is the index of the first character to start
matching at (counting from zero). When @var{ignore-case} is
true the case of matched strings are ignored. Note that
character classes are still case-significant.

@lisp
(string-match "ab+c" "abbbc")
    @result{} t

(string-match "ab+c" "xxxabbbcyyy")
    @result{} t
@end lisp
@end defun

@defun string-looking-at regexp string @t{#!optional} start ignore-case
Similar to @code{string-match}, but only returns true if
@var{string} matches @var{regexp} starting at the character at index
@var{start} in the string (or the first character if @var{start} is
undefined).

@lisp
(string-looking-at "ab+c" "abbbc" 0)
    @result{} t

(string-looking-at "ab+c" "xxxabbbcyyy" 0)
    @result{} ()

(string-looking-at "ab+c" "xxxabbbcyyy" 3)
    @result{} t
@end lisp
@end defun

@defun match-start @t{#!optional} n
Returns the position at which the @var{n}'th parenthesised expression
started in the last successful regexp match. If @var{n} is false
or zero the position of the start of the whole match is returned
instead.

When matching strings, all positions are integers, with the first
character in the string represented by zero. However, extensions that
allow regexps to be matched against other textual inputs may return
different position values.

@lisp
(string-match "x*(foo|bar)y" "xxxbary")
    @result{} t

(match-start 1)
    @result{} 3
@end lisp
@end defun

@defun match-end @t{#!optional} n
Similar to @code{match-start}, but returns the position of the
character following the matched item.

@lisp
(string-match "x*(foo|bar)y" "xxxbary")
    @result{} t

(match-end 1)
    @result{} 6
@end lisp
@end defun

A common use of regular expressions is to match a string, then replace
certain portions of the string with other text.

@defun expand-last-match template
Expand the @var{template} substituting the parenthesised expressions
from the most recent successfully matched regular expression.

@var{template} may contain the following substitution-inducing escape
sequences:

@table @samp
@item \0
@itemx \&
Substitute the whole string matched by the last regexp

@item \@var{n}
Substitute the @var{n}'th parenthensised expression, where 1 <= N <= 9.

@item \\
Substitute a single backslash character.
@end table

@lisp
(string-match "x*(foo|bar)y" "xxxbary")
    @result{} t

(expand-last-match "test-\\1-ing")
    @result{} "test-bar-ing"
@end lisp

Note that double backslashes are required due to the read syntax of
strings (@pxref{Strings}).

If you call @code{expand-last-match} after a failed match, the
returned value is not predictable.
@end defun

@defun string-replace regexp template string
Returns the string created by replacing all matches of @var{regexp} in
@var{string} with the result of expanding @var{template} using the
@code{expand-last-match} function.

@lisp
(string-replace "-" "_" "foo-bar-baz")
    @result{} "foo_bar_baz"

(string-replace "&(optional|rest)" "#!\\1" "(a &optional b &rest c)")
    @result{} "(a #!optional b #!rest c)"
@end lisp
@end defun

@defun string-split regexp string
Return a list of substrings of @code{string}, each delimited by
@code{regexp}.

@lisp
(string-split ":" "paths/are:often/seperated:by/colon")
    @result{} ("paths/are/" "often/seperated" "by/colon")
@end lisp
@end defun

@node Time and Date, System Information, Regular Expressions, The language
@section Time and Date
@cindex Time and date
@cindex Date and time
@cindex Calendar date and time

This section describes how time and date values are handled in
Librep. These function are exported by the @code{rep.system} module:

@menu
* Timestamps::                  Internal representation of time
* Formatting Dates::            Creating strings from timestamps
* Parsing Dates::               Reading textual dates
@end menu


@node Timestamps, Formatting Dates, , Time and Date
@subsection Timestamps
@cindex Timestamps
@cindex Date and time, timestamps

As in UNIX, Librep measures time as the number of seconds since
January 1st, 1970 (known as the @dfn{epoch}). 

For historical reasons Librep stores ``timestamp''s as a pair of integers,
using a cons cell. The first integer records the number of whole days
since the epoch, the second records the number of seconds since the
start of the day (in universal time).

@defun current-time
Return the number of seconds since the epoch, in a cons-cell.

@lisp
(current-time)
    @result{} (10744 . 61063) 
@end lisp
@end defun

@defun fix-time timestamp
Ensure that the two parts of @var{timestamp} (a pair or integers) are
consistent, simply that the number of seconds is less than the number
of seconds in a whole day. If not, the timestamp is adjusted to meet
this constraint.
@end defun

@defun time-later-p timestamp-1 timestamp-2
Returns true if @var{timestamp-1} is later than @var{timestamp-2}.
@end defun

On the plus side, this scheme won't wrap around as quickly as UNIX's
@code{time_t} will ;-)

The @code{rep.util.time} module also provides some functions for
manipulating timestamps:

@defun time->seconds timestamp
Convert @var{timestamp} to an integer, the number of seconds since the
epoch that it represents.
@end defun

@defun seconds->time seconds
Convert from an integer @var{seconds} to a timestamp object.
@end defun

@defun time- timestamp-1 timestamp-2
Return the number of seconds difference between @var{timestamp-1} and
@var{timestamp-2}.
@end defun

@defvr Constant seconds-per-day
The number of seconds in a 24-hour day.
@end defvr


@node Formatting Dates, Parsing Dates, Timestamps, Time and Date
@subsection Formatting Dates
@cindex Formatting dates
@cindex Dates, formatting as strings
@cindex Time, formatting as strings

Given a timestamp value it is possible to format it as a string, in
many different formats.

@defun current-time-string @t{#!optional} timestamp format
Return a string defining @var{timestamp} according to the string
@var{format}. If @var{timestamp} is undefined, the current time is
used.

The @var{format} string may include any of the formatting characters
from the C library's @code{strftime(3)} function. If undefined a
standard, fixed-width, format is used:

@lisp
(current-time-string)
    @result{} "Wed Jun  2 18:07:53 1999"
@end lisp

Some of the possible formatting substitutions include (this is copied
from the GNU libc manual, @pxref{(libc)Formatting Date and Time}):

@table @samp
@item %a
The abbreviated weekday name according to the current locale.

@item %A
The full weekday name according to the current locale.

@item %b
The abbreviated month name according to the current locale.

@item %B
The full month name according to the current locale.

@item %c
The preferred date and time representation for the current locale.

@item %d
The day of the month as a decimal number (range @code{01} to @code{31}).

@item %H
The hour as a decimal number, using a 24-hour clock (range @code{00} to
@code{23}).

@item %I
The hour as a decimal number, using a 12-hour clock (range @code{01} to
@code{12}).

@item %j
The day of the year as a decimal number (range @code{001} to @code{366}).

@item %m
The month as a decimal number (range @code{01} to @code{12}).

@item %M
The minute as a decimal number.

@item %p
Either @samp{am} or @samp{pm}, according to the given time value; or the
corresponding strings for the current locale.

@item %S
The second as a decimal number.

@item %U
The week number of the current year as a decimal number, starting with
the first Sunday as the first day of the first week.

@item %W
The week number of the current year as a decimal number, starting with
the first Monday as the first day of the first week.

@item %w
The day of the week as a decimal number, Sunday being @code{0}.

@item %x
The preferred date representation for the current locale, but without the
time.

@item %X
The preferred time representation for the current locale, but with no date.

@item %y
The year as a decimal number, but without a century (range @code{00} to
@code{99}).

@item %Y
The year as a decimal number, including the century.

@item %Z
The time zone or name or abbreviation (empty if the time zone can't be
determined).

@item %%
A literal @samp{%} character.
@end table

@lisp
(current-time-string nil "%Y-%m-%d")
    @result{} "1999-06-02"
@end lisp
@end defun


@node Parsing Dates, , Formatting Dates, Time and Date
@subsection Parsing Dates
@cindex Parsing dates
@cindex Dates, parsing
@cindex Time, parsing

The @code{date} Lisp library provides rudimentary support for parsing
date and time descriptions to their individual components, and to
timestamps. Evaluate the form @code{(require 'date)} to load this
library.

@defun parse-date string @t{#!optional} start
Returns a vector encoding the date described by @var{string}. If
@var{start} is defined, it specifies the index of the character in the
string to start parsing from.

Each element of the vector contains a separate component of the overall
point in time described by the string. The indices of these elements
are defined by the following constants:

@table @code
@item date-vec-day-abbrev
@vindex date-vec-day-abbrev
The abbreviated name of the day of the week.

@item date-vec-day
@vindex date-vec-day
The numeric day of the month, counting from one.

@item date-vec-month-abbrev
@vindex date-vec-month-abbrev
The abbreviated name of the month.

@item date-vec-month
@vindex date-vec-month
The numeric month of the year, counting from January equals one.

@item date-vec-year
@vindex date-vec-year
The numeric year.

@item date-vec-hour
@vindex date-vec-hour
The numeric hour of the day.

@item date-vec-minute
@vindex date-vec-minute
The numeric minute of the hour.

@item date-vec-second
@vindex date-vec-second
The numeric second of the minute.

@item date-vec-timezone
@vindex date-vec-timezone
If true, a string defining the timezone.

@item date-vec-epoch-time
@vindex date-vec-epoch-time
The timestamp (@pxref{Timestamps}), including the effects of the
timezone, if given.
@end table

@lisp
(current-time-string)
    @result{} "Wed Jun  2 18:37:17 1999"

(parse-date (current-time-string))
    @result{} ["Wed" 2 "Jun" 6 1999 18 37 17 0 (10744 . 67037)]

(parse-date "1999-06-02")
    @result{} ["Tue" 2 "Jun" 6 1999 0 0 0 0 (10744 . 0)]

(parse-date "June 6, 1999")
    @result{} ["" 0 "Jun" 6 1999 0 0 0 0 (10742 . 0)]

(aref (parse-date "June 6, 1999") date-vec-epoch-time)
    @result{} (10742 . 0)
@end lisp
@end defun

XXX provide more information on accepted formats, outputs for
incomplete descriptions, etc@dots{}


@node System Information, User Information, Time and Date, The language
@section System Information
@cindex System information

These definitions are all exported by the @code{rep.system} module.

@defvar operating-system
A symbol naming the current operating system. The only current option
is @code{unix}.
@end defvar

@defun system-name
This function returns a string naming the host that the interpreter is
running on. When possible this be a fully-qualified name (i.e.
including the domain)
@end defun

@defvar rep-build-id
A string describing the environment under which Librep was
built. This will always have the format @samp{@var{date} by
@var{user}@@@var{host}, for @var{arch}.}.

@lisp
rep-build-id
    @result{} "Mon May 17 1999 by john@@tizer.dcs.warwick.ac.uk, for sparc-sun-solaris2.6."
@end lisp
@end defvar

@defvar rep-version
A string describing the current release of Librep.

@lisp
rep-version
    @result{} "1.0"
@end lisp
@end defvar

@node User Information, Environment Variables, System Information, The language
@section User Information
@cindex User information

These functions are exported by the @code{rep.system} module.

@defun user-login-name
This function returns a string containing the login name of the user.

@lisp
(user-login-name)
    @result{} "john"
@end lisp
@end defun

@defun user-full-name @t{#!optional} real-name
This function returns a string containing the `real' name of the user; the
format of the string will depend on the host system.

If @var{real-name} is a string, it defines the name that will be
returned by subsequent calls to this function.

@lisp
(user-full-name)
    @result{} "John Harper"
@end lisp
@end defun

@defun user-home-directory @t{#!optional} user
This function returns the home directory of the user whose login name is
@var{user}, or the current user if @var{user} is undefined. The
returned string will be as returned by @code{file-name-as-directory}
(i.e. terminated by a @samp{/} character under UNIX)

@lisp
(user-home-directory)
    @result{} "/home/john/"
@end lisp
@end defun

@node Environment Variables, Command Line Options, User Information, The language
@section Environment Variables
@cindex Environment variables

These functions are exported by the @code{rep.system} module.

@defun getenv variable-name
This function returns the value (a string) of the environment variable
called @var{variable-name}. If the specified variable doesn't exist
false is returned.

@lisp
(getenv "OSTYPE")
    @result{} "Linux"
@end lisp
@end defun

@defun setenv variable-name new-value
This function sets the value of the environment variable called
@var{variable-name} to @var{new-value}. @var{new-value} can either be a
string containing the new contents of the variable or false, in
which case the environment variable is deleted.
@end defun

@defun unsetenv variable-name
Deletes any variable in @code{process-environment} named
@var{variable-name}.
@end defun

See also @ref{Process Objects} for the description of the
@code{process-environment} variable.

@node Command Line Options, Timers, Environment Variables, The language
@section Command Line Options
@cindex Command line options
@cindex Options, command line
@cindex Arguments, command line

As noted earlier any unused command line arguments are made available
to scripts through the @code{command-line-args} variable
(@pxref{Invocation}).

@defvar command-line-args
The list of unused command line arguments, in their original order.
@end defvar

The @code{get-command-line-option} function may be used to scan this
list of arguments. The @code{rep.system} module exports this function.

@defun get-command-line-option option @t{#!optional} requires-arg
Returns t if @var{option} was specified on the command line
(@var{option} is typically a phrase beginning with @samp{--}).

If @var{requires-arg} is true, the option requires a
parameter, the value of which is returned. If a parameter isn't
supplied an error is signalled.
@end defun

@lisp
(setq command-line-args '("--foo" "bar"))
    @result{} ("--foo" "bar")
(get-command-line-option "--foo" t)
    @result{} "bar"
command-line-args
    @result{} ()

(setq command-line-args '("--foo=bar"))
    @result{} ("--foo=bar")
(get-command-line-option "--foo" t)
    @result{} "bar"
command-line-args
    @result{} ()
@end lisp

@node Timers, Sleeping, Command Line Options, The language
@section Asynchronous Timers
@cindex Asynchronous timers
@cindex Timers, asynchronous

The @code{rep.io.timers} module (@pxref{Modules}) allows a Lisp program
to create multiple asynchronous timers, primed to call a specified
function after some time. 

A timer is not a thread. It works when the event loop is being used,
i.e. at least one @code{recursive-edit} is currently in progress. A
timer is called between cycles of event loop.

@defun make-timer function @t{#!optional} seconds milliseconds
Create and return a new timer object. It will be set to call the Lisp
function @var{function} after @var{seconds} seconds plus
@var{milliseconds} milliseconds. @var{function} will be called with a
single argument, the timer object that has just fired.

If both @var{seconds} and @var{milliseconds} are undefined, or zero,
the timer will be created but won't call @var{function}.

After the time interval has passed, and @var{function} has been called,
the timer @emph{will not} be restarted. Use the @code{set-timer}
function to reset it.
@end defun

@defun delete-timer timer
Prevent the timer object @var{timer} from calling the Lisp function
associated with it. Use the @code{set-timer} function to reset it.
@end defun

@defun set-timer timer @t{#!optional} seconds milliseconds
Reset the timer object @var{timer}. If either/both of @var{seconds} and
@var{milliseconds} are defined the interval of the timer will be set to
the specified time period. If neither are defined then the current
interval of the timer is preserved.
@end defun

@node Sleeping, Beeping, Timers, The language
@section Sleeping
@cindex Sleeping

@defun sleep-for seconds @t{#!optional} milliseconds
Pause for a @var{seconds} (plus the optional @var{milliseconds}
component) long period of time. Input becoming available will
@emph{not} break the sleep (@pxref{Process I/O}).

This function is exported by the @code{rep.system} module.
@end defun


@node Beeping, i18n, Sleeping, The language
@section Beeping
@cindex Beeping

Use this function to attract the user's attention.

@defun beep
Ring a bell somewhere.
@end defun

@node i18n, Messages, Beeping, The language
@section Internationalisation
@cindex Internationalisation

Librep has support for internationalisation (or i18n) of text
messages, using the GNU @code{gettext} implementation (@pxref{Top, ,
Overview, gettext, The GNU gettext Manual}), a run-time library
managing the mapping between text strings in the programmer's native
language and in the language of the end user.

Three functions are provided to access the message catalogues
maintained by GNU @code{gettext}. Import the @code{rep.i18n.gettext}
module to load them.

@defun _ string
Attempt to find a native language equivalent of @var{string}. If no
equivalent is found the original string is returned.

Note that this function is always defined, even if the @code{gettext}
module hasn't been required. In this case it always returns the
original string.
@end defun

@defun bindtextdomain domain directory
Tell @code{gettext} that message catalogues for message domain
@var{domain} (a string) can be found under the directory called
@var{directory}.
@end defun

@defun textdomain domain
Note that any strings that are to be translated in the future (until
the next call to @code{textdomain}) are in the domain called
@var{domain} (a string).
@end defun

The usual method of constructing message catalogue templates
(@file{.pot} files) is to run @code{xgettext} on the C source files of
the program (that have been annotated for i18n). librep provides the
@code{rep-xgettext} program to perform the same task for files of Lisp
code.

@node Messages, Debugging, i18n, The language
@section Messages
@cindex Messages

The @code{message} function will show the user a small message
(typically no more than a single column of text). In graphical
applications it @emph{won't} bring up a separate window, only
displaying the text in a status bar or something similar. In a
console-based environment, the message will be printed to the
@code{stderr} stream, followed by a line break.

@defun message @t{#!optional} display-now
Displays a one-line message, the string @var{message}. If
@var{display-now}, every effort will be made to display the message as
soon as possible, possibly before the next scheduled screen update (if
applicable).

This function is exported by the @code{rep.system} module.
@end defun


@node Debugging, Tips, Messages, The language
@section Debugging
@cindex Debugging

When you have written a Lisp program you will have to debug it (unless
all your programs work first time?). There are two main classes of
errors; syntax errors and semantic errors.

Syntax errors occur when the text you've typed out to represent your
program is not a valid representation of a Lisp object (since a program
is simply an ordered set of Lisp objects). When you try to load your
program the Lisp reader will find the syntax error and tell you about,
unfortunately though it probably won't be able to tell you exactly
where the error is.

The most common source of syntax errors is too few or too many
parentheses; the Jade or Emacs @kbd{Ctrl-Meta-f} and @kbd{Ctrl-Meta-b}
commands can be used to show the structure of the program as the Lisp
reader sees it.

Semantic errors are what we normally call bugs---errors in logic, the
program is syntactically correct but doesn't do what you want it to.
For these types of errors librep provides hooks to allow interactive
debugging. The debugger supplied with librep uses these hooks to
implement a simple command line debugger; programs using librep as an
extension language may provide their own debugger interface.

There are several ways to enter the Lisp debugger; functions can be
marked so that they cause the debugger to be entered when they are
called, breakpoints can be written in functions or it can be called
explicitly with a form to step through.

@deffn Command trace symbol
This command marks the symbol @var{symbol} so that each time its value
is dereferenced the debugger is entered when the next form is
evaluated. This can be used to set breakpoints on functions (or
variables).

When called interactively @var{symbol} is prompted for.
@end deffn

@deffn Command untrace symbol
The opposite of @code{trace}---unmarks the symbol.
@end deffn

@defun break
This function causes the debugger to be entered immediately. By putting
the form @code{(break)} at suitable points in your program simple
breakpoints can be created.
@end defun

@deffn Command step form
This function invokes the debugger to step through the form @var{form}.

When called interactively @var{form} is prompted for.
@end deffn

@defun backtrace @t{#!optional} stream
Prints a description of the current Lisp function call stack to
@var{stream} (or @code{standard-output} if @var{stream} is undefined).

@lisp
(backtrace (current-buffer))
     @print{} #<subr backtrace> ((current-buffer)) nil
     @print{} #<closure eval-and-print> ((backtrace (current-buffer))) t
     @result{} t
@end lisp

Each line represents a stack frame, the first item is the called
function, the second is the list of arguments applied to it. The
third item is true if the list of arguments as displayed has
already been evaluated.
@end defun

Whenever the Lisp debugger is entered the form waiting to be evaluated
is printed, preceded by the current depth of execution in angular
brackets. At this point the special debugger commands available are,

@table @samp
@item step
@itemx s
Step into the current form; this means that in a list form the debugger
is used to evaluated each argument in turn.

@item next
@itemx n
Continue evaluating forms normally until the next form at the current
level is entered, then re-enter the debugger.

@item continue
@itemx c
Continue execution normally. Note that this command is the one to use
when an error has been trapped.

@item return @var{form}
@itemx r @var{form}
Evaluate @var{form} then return this value as the result of the current
form.

@item print @var{form}
@itemx p @var{form}
Evaluate @var{form}, then print its value.

@item form
@itemx f
Print the form being debugged.

@item backtrace
@itemx b
Print a backtrace of the current Lisp call stack.
@end table

Entering a null string repeats the previous @samp{next}, @samp{step},
or @samp{continue} command.

After the form has been evaluated (i.e. after you've typed one of the
commands above) the value of the form is printed in the buffer,
prefixed by the string @samp{=> }.

Note that it is also possible to make certain types of errors invoke
the debugger immediately they are signalled, see @ref{Errors}. Also
note that the debugger is unable to step through compiled Lisp code.


@node Tips, , Debugging, The language
@section Tips
@cindex Tips

This section of the manual gives advice about programming in
Librep.

For advice on getting the most out of the compiler, see
@ref{Compilation Tips}.

@menu
* Comment Styles::              Different types of comments
@end menu

@node Comment Styles, , , Tips
@subsection Comment Styles
@cindex Comment styles
@cindex Tips, comment styles
@cindex Style, comments

As already described, single-line comments in Lisp are introduced by a
semi-colon (@samp{;}) character. By convention a different number of
semi-colons is used to introduce different types of comments,

@table @samp
@item ;
A comment referring to the line of Lisp code that it occurs on,
comments of this type are usually indented to the same depth, on the
right of the Lisp code. When editing in Jade's Lisp mode the command
@kbd{Meta-;} can be used to insert a comment of this type.

For example,

@lisp
(defconst op-call #x08)         ;call (stk[n] stk[n-1] ... stk[0])
                                ; pops n values, replacing the
                                ; function with the result.
(defconst op-push #x10)         ;pushes constant # n
@end lisp

@item ;;
Comments starting with two semi-colons are written on a line of their
own and indented to the same depth as the next line of Lisp code. They
describe the following lines of code.

For example,

@lisp
(let
    ((fname (concat file-name ?c)))
  ;; Be sure to remove any partially written dst-file.
  (when (file-exists-p fname)
    (delete-file fname)))
@end lisp

Comments of this type are also placed before a function definition
to describe the function. This saves wasting memory with a documentation
string in a module's internal functions.

For example,

@lisp
;; Compile a form which occurred at the `top-level' into a
;; byte code form.
;; defuns, defmacros, defvars, etc... are treated specially.
;; require forms are evaluated before being output uncompiled;
;; this is so any macros are brought in before they're used.
(defun comp-compile-top-form (form)
  @dots{}
@end lisp

@item ;;;
This type of comment always starts in the first column of the line, they
are used to make general comments about a program and don't refer to any
function or piece of code in particular.

For example,

@lisp
;;; Notes:

;;; Instruction Encoding
;;; ====================
;;; Instructions which get an argument (with opcodes of zero up to
@dots{}
@end lisp

@item ;;;;
Each program should have a comment of this type as its first line, the
body of the comment is the name of the file, two dashes and a brief
description of what the program does. They always start in the first
column.

For example,

@lisp
;;;; compiler.jl -- Simple compiler for Lisp files/forms
@end lisp
@end table

If you adhere to these standards the indentation functions provide by
the Lisp mode will indent your comments to the correct depth.
