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

   Copyright 1999-2000 John Harper.

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

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

   This document describes `librep', a simple, but powerful, Lisp
dialect intended both as an embedded extension language, and as a
stand-alone programming language.

   This is Edition 1.2 of its documentation, last updated 8 September
2000 for librep version 0.13.

Copying
*******

   `librep' is distributed under the terms of the GNU General Public
License, this basically means that you can give it to anyone for any
price as long as full source code is included; you also have the right
to distribute modified copies in the same way. For the actual legalese
see the file `COPYING' in the distribution (or Copying (emacs)).

   In case it isn't obvious, scripts written to use librep are not
considered derived works, and therefore may be licensed however the
author wishes. However, the ability of scripts to dynamically load
external libraries may complicate this situation.

   The distribution includes the following code from other packages:

   * Henry Spencer's `regexp' implementation, with many modifications.
     This is distributed under the terms of his copyright, see the file
     `src/README.regexp' in the distribution.

   * The public domain `sdbm' database library by Ozan Yigit.

   * The backquote package from Emacs version 19, written by Rick
     Sladkey.

   * The GNU `gettext' implementation for internationalized message
     catalogues.

   Be aware that there is absolutely NO WARRANTY for this program, you
use it at your own risk. Obviously I hope there are no bugs, but I make
no promises regarding the reliability of this software.

Introduction
************

   `librep' is a dialect of Lisp, designed to be used both as an
extension language for applications and as a general purpose
programming language. It was originally written to be mostly-compatible
with Emacs Lisp, but has subsequently diverged markedly. Its aim is to
combine the best features of Scheme and Common Lisp and provide an
environment that is comfortable for implementing both small and large
scale systems. It tries to be a "pragmatic" programming language.

   The author has used `librep' in its various forms in many projects
since 1993. This includes two large programs which use it as an
extension language, and many stand-alone programs.

   `rep' stands for "Read, Eval, Print", the three main components of
any Lisp system.

   Some of the features of `librep' are:

   * Lexically scoped (with special variables from CL)

   * Clean module system

   * Tail-call elimination

   * Compiles to byte-code

   * First-class continuations

   * Uses GNU MP for fast bignums/rationals

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

   * Mostly-Perl-like regular expressions

   * Spawn and control subprocesses

   * Dynamically loads shared libraries (a.k.a. "plugins")

   * Extensible type, I/O, and file handling

Invocation
**********

   The `rep' program may be used to launch the stand-alone `librep'
environment:

     usage: rep [REP-OPTIONS...] [SCRIPT [SCRIPT-OPTIONS...]]

Where REP-OPTIONS may be any of the following:

`--init FILE'
     Use FILE to boot the Lisp system from, instead of `init.jl'.

`--version'
     Print the current version number and exit

`--batch'
     Tell the interpreter that it is running non-interactively, this
     reduces the number of messages output to the console

`--interp'
     Interpreted mode. Never load compiled Lisp files: this can be
     useful when using the debugger.

`--no-rc'
     Don't load the user's `~/.reprc' script, or the `site-init.jl'
     script

`-f FUNCTION'
     Invoke the Lisp function FUNCTION (with no arguments)

`-l SCRIPT'
     Try to load the Lisp file SCRIPT, this is equivalent to evaluating
     the form `(load "SCRIPT")'.

`-q'
     Terminate the Lisp process and exit.

   If SCRIPT is given, it names the Lisp file to load, equivalent to
the `-l' option, except that `--batch-mode' is implied. Any
SCRIPT-OPTIONS will be made available to the script (in the
`command-line-args' variable).

   After any arguments have been processed a banner message will be
displayed before entering an interactive read-eval-print loop, unless
`--batch-mode' was specified, in which case the interpreter exits.

   The read-eval-print loop simply reads complete Lisp forms (see The Lisp Reader),
evaluates them, before printing the result back to the
console; this continues ad infinitum, or until you force an EOF (i.e.
enter `C-d').

Implicitly Interpreting `rep' Scripts
.....................................

   The `rep' interpreter also supports automatic invocation of scripts,
using the oeprating system's support for `#!' interpreter invocation
(i.e. if the first line of an executable text file contains `#! PROG',
the program PROG is used to execute the script.

   However there is a problem with this method, in that the `PATH'
environment variable is not searched for the location of the
interpreter, and thus the full file name of the interpreter program
must be hard-coded into the script. To work around this problem `rep'
supports a slightly different method of invocation.

   If the first two characters of a loaded Lisp file are `#!', then
everything is treated as a comment until the first occurrence of the
string `!#'. This allows the first part of the script to be executed as
a shell script invoking the `rep' interpreter.

   What this means, is that you want to put something like the following
at the start of any scripts you want to execute implicitly (and `chmod
+x' the file as well):

     #!/bin/sh
     exec rep "$0" "$@"
     !#

     ;; Lisp code follows...

The language
************

   This chapter of the manual is a full guide to the librep Lisp
programming language, including documentation for most of the built-in
functions.

Fundamental data types.

The core language.

Data structures and I/O.

Miscellaneous features.

   This manual still fails to document the following functions:
default-boundp, default-value, recursive-edit, regexp-cache-control,
sdbm-close, sdbm-delete, sdbm-error, sdbm-fetch, sdbm-firstkey,
sdbm-nextkey, sdbm-open, sdbm-rdonly, sdbm-store, sdbmp, set-default,
setq-default,

Introduction
============

   As you have probably gathered by now, `librep' provides a dialect of
the Lisp programming language--a dialect originally inspired by Emacs
Lisp, but later adapted to include many features from various Scheme
implementations and Common Lisp. The language dialect aims to be
convenient for both extending applications and writing large
stand-alone programs.

   All programs written using only the information in this manual should
be compatible with future revisions of `librep'.

   This following sections explain some of the most important Lisp
concepts and the conventions I've used in this manual.

nil and t
---------

   In the rep Lisp dialect there is a single data value representing
boolean "false"--the empty list, written as `()'. All other values are
considered "not-false", i.e. "true".

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

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

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

     (append '() '()) => ()          ;Emphasize use of empty lists

     (not nil) => t                  ;Emphasize use as boolean false

     (get 'nil 'color)               ;Use the symbol `nil'

   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.

The Lisp Reader
---------------

   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.

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

   See Data Types.

Notation
--------

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

     (+ 1 2)
         => 3

The glyph `=>' is used to show the computed value of a form. (1)

   When two forms are shown as being exactly equivalent to one another
the glyph `==' is used, for example,

     (car some-variable) == (nth 0 some-variable)

   Evaluating some forms result in an error being signalled, this is
denoted by the `error-->' glyph.

     (open-file "/tmp/foo" 'read)
         error--> File error: No such file or directory, /tmp/foo

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

   (1) In this case the list `(+ 1 2)' (i.e. the list containing three
elements, the symbol `+' 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 `+' function adds a series of numbers, the above function
call is actually performing the computation `1 + 2'.

Descriptions
------------

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

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

   Hooks (see Hooks) are also described in this format, the only
difference is that `Variable:' is replaced by `Hook:'.

   Functions (see Functions) and macros (see 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: `#!optional', `#!key' and
`#!rest'. They have the same meaning as when used in the lambda-list of
a function definition (see Lambda Expressions). That is,
`#!optional' means that all further parameters are optional, and
`#!rest' means that the following parameter actually receives a list of
any unused argument values.

   An example function definition follows.

 - Function: useless-function first `#!optional' second `#!rest' tail
     This function returns a list consisting of the values SECOND (when
     undefined the number 42 is used), all the items in the list TAIL
     and FIRST.

          (useless-function 'foo 'bar 'xyz 20)
              => (bar xyz 20 foo)

          (useless-function '50)
              => (42 50)

   Macros and interactive commands are defined in the same way with
`Macro:' or `Command:' replacing `Function:'.

   Special forms (see 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
(`[OPTIONAL-ARG]') and three dots (`REPEATED-ARG...') indicate where
zero or more arguments are allowed.

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
"value") has two basic attributes: the data and the _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 "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 (see
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... 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
`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.

Types Summary
-------------

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

"Numbers"
     Numbers: fixnums, bignums, rationals and floats. See Numbers.

"Cons cell"
     An object referring to two other Lisp objects. See Cons Cells.

"List"
     A sequence of objects, in Lisp lists are not primitive types,
     instead they are made by chaining together Cons cells. See
     Lists.

"Vector"
     A one-dimensional array of objects. See Vectors.

"String"
     A vector of characters. See Strings.

"Array"
     An ordered sequence of objects which can be accessed in constant
     time, either a vector or a string. See Sequences.

"Sequence"
     An ordered sequence of objects, either a list or an array.  See
     Sequences.

"Symbol"
     A symbol is a named object; they are used to provide named
     variables and functions. See Symbols.

"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. See
     Files.

"Process"
     An object through which processes may be created and controlled.
     See Processes.

"Stream"
     Serial data sinks and sources. These may include files, functions,
     and processes. See Streams.

"Void"
     The empty type, only used in symbols to represent an undefined
     value.  Note that this is not the same as `()', which is the empty
     list, or false truth value.

Read Syntax
-----------

   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.

   Single line comments are introduced by a semi-colon character (`;').
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 `#|' and terminated by `|#'.  See Comment Styles.

   The "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.

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

          42
              => 42

          #o177
              => 127

          #x-ff
              => -255

          3/2
              => 3/2

          1.23
              => 1.23

Strings
     The read syntax of a string is simply the string with a
     double-quote character (`"') at each end, for more details see
     Strings.

          "This is a string"

Cons cells
     A cons cell is written in what is known as "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:

          ("car" . "cdr")

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:

          (0 1 2 3)

          ("foo" ("bar" "baz") 100)

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

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

          [0 1 2 3]

Symbols
     The read syntax of a symbol is its name, for example the read
     syntax of the symbol called `my-symbol' is,

          my-symbol

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 "printed
representation" of the object, and will usually be very similar to the
read syntax of the object (see Read Syntax).

   Objects which do not have a read syntax _do_ have a printed
representation, it will normally be of the form,

     #<RELEVANT-TEXT>

where the 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 `#<...>'.

Equality Predicates
-------------------

 - Function: eq arg1 arg2
     Returns true when ARG1 and 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,

          (eq "foo" "foo")        ;the objects are distinct
              => ()

          (eq t t)                ;the same object -- the symbol `t'
              => t

     Note that the result of `eq' is undefined when called on two
     integer objects with the same value, see `eql'.

 - Function: equal arg1 arg2
     The function `equal' compares the structure of the two objects
     ARG1 and ARG2. If they are considered to be equivalent then
     returns true, otherwise returns false.

          (equal "foo" "foo")
              => t

          (equal 42 42)
              => t

          (equal 42 0)
              => ()

          (equal '(x . y) '(x . y))
              => t

 - Function: eql arg1 arg2
     This function is a cross between `eq' and `equal': if ARG1 and
     ARG2 are both numbers then the value of these numbers are
     compared. Otherwise it behaves in exactly the same manner as `eq'
     does.

          (eql 3 3)
              => t

          (eql 1 2)
              => ()

          (eql "foo" "foo")
              => ()

          (eql 'x 'x)
              => t

Comparison Predicates
---------------------

   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 `eql' function, inexact and exact numbers will be
compared by first coercing the exact number to be inexact.

 - Function: = arg1 arg2 arg3 ... argn
     Returns true if all arguments represent the same value.

 - Function: /= arg1 arg2 arg3 ... argn
     Returns true if no two arguments represent the same value.

 - Function: > arg1 arg2 arg3 ... argn
     Returns true when ARG1 is `greater than' ARG2, and ARG2 is greater
     than ARG3, and so on, upto ARGN.

 - Function: >= arg1 arg2 arg3 ... argn
     Similar to `>', but for the "greater than or equal to" relation.

 - Function: < arg1 arg2 arg3 ... argn
     Similar to `>', but for the "less than" relation.

 - Function: <= arg1 arg2 arg3 ... argn
     Similar to `>', but for the "less than or equal to" relation.

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

 - Function: max #!rest args
     Return the maximum value from the list of ARGS. When comparing
     numbers, any inexact arguments cause the result to be inexact.

 - Function: min #!rest args
     Return the minimum value from the list of ARGS. When comparing
     numbers, any inexact arguments cause the result to be inexact.

Type Predicates
---------------

   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.

`integerp', `numberp', `null', `consp', `listp', `vectorp', `subrp',
`functionp', `sequencep', `stringp', `symbolp', `processp', `filep'.

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

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 "stale",
that is, no references to it exist and it can therefore be reused.

   The "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 Guardians)

 - Function: garbage-collect
     Runs the garbage collector, usually this function doesn't need to
     be called manually.

 - Variable: 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.

 - Variable: 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 `garbage-threshold' since
     the small delay caused by garbage collection is unnoticeable if the
     system is already idle.

 - Variable: after-gc-hook
     A hook (see Normal Hooks) called immediately after each
     invocation of the garbage collector.

Numbers
=======

   `Librep' distinguishes between numbers that are represented exactly
and numbers that may not be. This is similar to the Scheme dialect of
Lisp. Quoting from the Scheme standard:

     ... numbers are either _exact_ or _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.

   Exact numbers include both integers and rational numbers, there is no
theoretical limit to the range of the values that may be represented
(1). Inexact numbers are currently implemented using double precision
floating point values.

   The read syntax of any number is: `[PFX...][SGN]DATA...', where the
optional SGN is one of the characters `-' or `+', DATA is the
representation of the number, and PFX is zero or more of the following
prefix strings:

`#b'
`#B'
     Integers are described in binary,

`#o'
`#O'
     Integers are in octal,

`#d'
`#D'
     Integers are in decimal (the default),

`#x'
`#X'
     Integers are in hexadecimal,

`#e'
`#E'
     Coerce the number to an exact representation after parsing it,

`#i'
`#I'
     Coerce to an inexact representation.

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
`42', `#x2a', `#o52', `#o+52', ...

   The representation of a rational number is two sequences of digits,
separated by a `/' character. For example, `3/2' represents the
rational number three divided by two.

   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 `e' and a decimal exponent multiplying the first part of the
number by that power of ten. For example, `10.0', `10.' and `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 `/' character. Inexact
numbers are printed in their decimal form.

 - Function: numberp object
     Returns true if OBJECT is a number.

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

   (1) However, depending on implementation restrictions, very large
integers may be coerced to an inexact representation.

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.

 - Function: + number1 #!rest numbers
     This functions adds its arguments then returns their sum.

 - Function: - number1 #!rest numbers
     If this function is just given one argument (NUMBER1) that number
     is negated and returned. Otherwise each of NUMBERS is subtracted
     from a running total starting with the value of NUMBER1.

          (- 20)
              => -20

          (- 20 10 5)
              => 5

 - Function: * number1 #!rest numbers
     This function multiplies its arguments then returns the result.

 - Function: / number1 #!rest numbers
     This function performs division, a running-total (initialised from
     NUMBER1 is successively divided by each of NUMBERS then the result
     is returned.

          (/ 100 2)
              => 50

          (/ 200 2 5)
              => 20

          (/ 3 2)
              => 3/2

          (/ 3.0 2)
              => 1.5

 - Function: 1+ number
     This function returns the result of adding one to NUMBER.

          (1+ 42)
              => 43

 - Function: 1- number
     Returns NUMBER minus one.

Integer Functions
-----------------

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

 - Function: quotient dividend divisor
     Return the integer part of dividing DIVIDEND by DIVISOR.

 - Function: remainder dividend divisor
     Returns the integer remainder from dividing the DIVIDEND by
     DIVISOR. The remainder is either zero or has the same sign as
     DIVIDEND.

 - Function: modulo dividend divisor
 - Function: mod dividend divisor
     Return the value of DIVIDEND modulo DIVISOR. Unlike the
     `remainder' function the `modulo' function always has the sign of
     the DIVISOR, not of the DIVIDEND

 - Function: gcd args...
     Returns the greatest common divisor of the integers ARGS...  If no
     arguments are given, returns zero.

 - Function: lcm args...
     Return the lowest common multiple of the integers ARGS... If no
     arguments are given, returns one.

Rational Functions
------------------

   These functions operate on rational numbers.

 - Function: numerator x
     Returns the exact numerator of X.

 - Function: denominator x
     Returns the exact denominator of X.

 - Function: exact->inexact x
     Returns an inexact version of rational number X.

Real Number Functions
---------------------

 - Function: abs x
     Returns the magnitude of X.

 - Function: floor x
     Round X downwards to the nearest integer less than or equal to X.

 - Function: ceiling x
     Round X upwards to the nearest integer less than or equal to X.

 - Function: truncate x
     Round X to the nearest integer between X and zero.

 - Function: round x
     Round X to the nearest integer. Halfway cases are rounded to the
     nearest even integer.

 - Function: inexact->exact x
     Returns an exact representation of X. This may involve a loss of
     accuracy.

Mathematical Functions
----------------------

 - Function: exp x
     Return `e' (the base of natural logarithms) raised to the power X.

 - Function: log x
     Return the natural logarithm of X. An arithmetic error is
     signalled if X is less than zero.

 - Function: sin x
     Return the sine of angle X; x is in terms of radians.

 - Function: cos x
     Return the cosine of angle X.

 - Function: tan x
     Return the tangent of angle X.

 - Function: asin x
     Return the arc sine of X (the value whose sine is X), in radians.

 - Function: acos x
     Return the arc cosine of X.

 - Function: atan x
     Return the arc tangent of X.

 - Function: sqrt x
     Return the non-negative square root of X. Currently, if X is
     negative, an arithmetic error is signalled.

 - Function: expt x y
     Returns X raised to the power Y.

     If X is negative and Y is a non-integer, then an arithmetic error
     is signalled (mathematically should return a complex number).

Bitwise Functions
-----------------

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

 - Function: lsh number count
     This function shifts the integer NUMBER COUNT bits to the left, if
     COUNT is negative NUMBER is shifted to the right instead.

          (lsh 1 8)
              => 256

          (lsh 256 -8)
              => 1

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

          (logand 15 8)
              => 8

          (logand 15 7 20)
              => 4

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

          (logior 1 2 4)
              => 7

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

          (logxor 7 3)
              => 4

 - Function: lognot number
     This function inverts all the bits in NUMBER.

          (lognot 0)
              => -1

          (lognot 2)
              => -3

          (lognot -1)
              => 0

Numeric Predicates
------------------

   For the documentation of the functions `=', `/=', `>', `<', `>=',
`<=', `max' and `min', see Comparison Predicates.

 - Function: exactp object
     Returns true when OBJECT is an exact number.

 - Function: inexactp object
     Returns true when OBJECT is an inexact number.

 - Function: integerp object
     Returns true when OBJECT is an integer.

 - Function: rationalp object
     Returns true when OBJECT is a rational number (including integers).

 - Function: realp object
     Returns true when OBJECT is a real number.

 - Function: oddp x
     Return true if X is an odd number.

 - Function: evenp x
     Return true if X is an even number.

 - Function: positivep x
     Return true if X is a number greater than zero.

 - Function: negativep x
     Return true if X is a number less than zero.

 - Function: zerop x
     Returns true if X is equal to zero.

Pseudo-Random Numbers
---------------------

   The `random' function allows pseudo-random numbers to be generated.

 - Function: random #!optional limit
     Return a pseudo-random number between zero and LIMIT-1 inclusive.
     If LIMIT is undefined, it is taken as being the largest positive
     integer representable in a fixnum.

     Calling `random' with LIMIT equal to the symbol `t' seeds the
     generator with the current time of day.

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

     ?a
         => 97

     ?\n
         => 10

     ?\177
         => 127

 - Function: alpha-char-p character
     This function returns true when CHARACTER is one of the alphabetic
     characters.

          (alpha-char-p ?a)
              => t

 - Function: upper-case-p character
     When CHARACTER is one of the upper-case characters this function
     returns true.

 - Function: lower-case-p character
     Returns true when CHARACTER is lower-case.

 - Function: digit-char-p character
     This function returns true when CHARACTER is one of the decimal
     digit characters.

 - Function: alphanumericp character
     This function returns true when CHARACTER is either an alphabetic
     character or a decimal digit character.

 - Function: space-char-p character
     Returns true when CHARACTER is a white-space character (space, tab,
     newline or form feed).

 - Function: char-upcase character
     This function returns the upper-case equivalent of CHARACTER. If
     CHARACTER is already upper-case or has no upper-case equivalent it
     is returned unchanged.

          (char-upcase ?a)
              => 65                       ;`A'

          (char-upcase ?A)
              => 65                       ;`A'

          (char-upcase ?!)
              => 33                       ;`!'

 - Function: char-downcase character
     Returns the lower-case equivalent of the character CHARACTER.

Sequences
=========

   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.

 - Function: sequencep object
     This function returns true if OBJECT is a sequence.

Cons Cells
----------

   A "cons cell" is an ordered pair of two objects, the "car" and the
"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 `foo' would be written as,

     (10 . "foo")

 - Function: cons car cdr
     This function creates a new cons cell. It will have a car of CAR
     and a cdr of CDR.

          (cons 10 "foo")
              => (10 . "foo")

 - Function: consp object
     This function returns true if OBJECT is a cons cell.

          (consp '(1 . 2))
              => t

          (consp '())
              => ()

          (consp (cons 1 2))
              => t

   The strange syntax `'(1 . 2)' is known as "quoting" (see
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.

   In Lisp an "atom" is any object which is not a cons cell (and is,
therefore, atomic).

 - Function: atom object
     Returns true if OBJECT is an atom (not a cons cell).

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

 - Function: car cons-cell
     This function returns the object which is the car (first element)
     of the cons cell CONS-CELL.

          (car (cons 1 2))
              => 1

          (car '(1 . 2))
              => 1

 - Function: cdr cons-cell
     This function returns the cdr (second element) of the cons cell
     CONS-CELL.

          (cdr (cons 1 2))
              => 2

          (cdr '(1 . 2))
              => 2

 - Function: rplaca cons-cell new-car
     This function sets the value of the car (first element) in the cons
     cell CONS-CELL to NEW-CAR. The value returned is CONS-CELL.

          (setq x (cons 1 2))
              => (1 . 2)
          (rplaca x 3)
              => (3 . 2)
          x
              => (3 . 2)

 - Function: rplacd cons-cell new-cdr
     This function is similar to `rplacd' except that the cdr slot
     (second element) of CONS-CELL is modified.

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... very easily.

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

 - Function: listp arg
     This functions returns true when its argument, ARG, is a list
     (i.e. either a cons cell or `()').

 - Function: null arg
     Returns a true value if ARG is the empty list.

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 `()'. A list of zero elements is represented by
`()'.

   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.

     (0 1 2 3 4)

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

     (0 1 2 . (3 4))

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

     +-----+-----+
     |  o  |  o----> cdr
     +--|--+-----+
        |
         --> car

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

     +-----+-----+   +-----+-----+   +-----+-----+   +-----+-----+
     |  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |  o----> ()
     +--|--+-----+   +--|--+-----+   +--|--+-----+   +--|--+-----+
        |               |               |               |
         --> 1           --> 2           --> 3           --> 4

   A more complex example, the list `((1 2) (foo bar))' can be drawn as,

     +-----+-----+                          +-----+-----+
     |  o  |  o---------------------------> |  o  |  o----> ()
     +--|--+-----+                          +--|--+-----+
        |                                      |
     +-----+-----+   +-----+-----+          +-----+-----+   +-----+-----+
     |  o  |  o----> |  o  |  o----> ()     |  o  |  o----> |  o  |  o----> ()
     +--|--+-----+   +--|--+-----+          +--|--+-----+   +--|--+-----+
        |               |                      |               |
         --> 1           --> 2                  --> foo         --> bar