This is librep.info, produced by makeinfo version 4.8 from librep.texi.

INFO-DIR-SECTION Programming Languages
START-INFO-DIR-ENTRY
* librep: (librep).		"Liberp" lisp language
END-INFO-DIR-ENTRY

   This is `The librep Manual', for librep.

   Copyright 1999-2000 John Harper.  Copyright 2009-      Sawfish
community.  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.


File: librep.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

   This document describes `librep' Lisp dialect.

* Menu:

* Copying::                     Distribution conditions
* Introduction::                Brief introduction to librep
* News::                        History of user-visible changes

* Invocation::                  How to start the interpreter
* The language::                The Lisp manual of librep
* librep Internals::		Embedding librep in other programs

* Function index::              Menu of all documented functions
* Variable index::              All variables which have been mentioned
* Concept index::               Main index, references to all sections


File: librep.info,  Node: Copying,  Next: Introduction,  Prev: Top,  Up: Top

1 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 *note (emacs)Copying::).

   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.


File: librep.info,  Node: Introduction,  Next: News,  Prev: Copying,  Up: Top

2 Introduction
**************

* Menu:

* About::
* Reporting bugs/patches/etc::  How to contact the maintainers
* Acknowledgment::


File: librep.info,  Node: About,  Next: Reporting bugs/patches/etc,  Up: Introduction

2.1 About
=========

Librep offers a Lisp system to Sawfish window manager, and practically
that's all. Some bugs are known, but Librep is quite stable.

Maintainer until Aug 2008: John Harper
Maintainer since Aug 2008: Christopher Bratusek

   For more see: `http://sawfish.wikia.com/'.

   For compilation instructions, read `README'.

   For Lisp features, see *Note Rep's Lisp Introduction::.

   There used to be an editor "Jade" written in Librep, too.

   Original introduction by John Harper:

   `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, John Harper, 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.


File: librep.info,  Node: Reporting bugs/patches/etc,  Next: Acknowledgment,  Prev: About,  Up: Introduction

2.2 Reporting bugs/patches/etc
==============================

Known bugs are listed in the file `TODO'.

   If the `librep' interpreter crashes it's probably a bug (unless
you're using the `rep-gtk' binding, in which case creating invalid GTK
widget hierarchies can easily crash the Lisp system). If the
interpreter hangs such that sending it interrupt signals doesn't fix
the problem, that's probably also a bug.

   When reporting any bugs, please try to collect as much meaningful
information as possible. This will hopefully include stack backtraces
(of both the C and Lisp stacks if possible), what features are loaded,
what you did immediately before triggering the bug, a description of
your the system, etc...

   Please send any bug reports to the mailing list:
<sawfish-list@gnome.org>.

   To make a patch, please use `git diff' or `diff -u'.


File: librep.info,  Node: Acknowledgment,  Prev: Reporting bugs/patches/etc,  Up: Introduction

2.3 Acknowledgment
==================

Thanks to:

   * Henry Spencer for his excellent regexp matcher

   * Ozan Yigit for SDBM

   * Rick Sladkey for the Emacs backquote implementation

   * Jamie Zawinski for the Emacs peephole optimiser patterns

   * Yukihiro Nakai for the first rep-gettext implementation

   * Mikolaj J. Habryn for being the first 64-bit guinea-pig, and for
     building Debian packages

   * Aron Griffis for porting to Tru64

   * numerous other people for bug-reports and patches


File: librep.info,  Node: News,  Next: Invocation,  Prev: Introduction,  Up: Top

3 News
******

0.91.0
======

   * Update note [important]:

     You need to rebuild rep-gtk and sawfish against this version of
     librep, because of an ABI-change.

     Your lisp files have to be byte-compiled again, too.

   * Halfway improved `debug-on-error' and `backtrace-on-error' [Teika
     Kazura]

     Previously, setting these values to `t' triggered the debugger /
     backtracer even if the error was signalled inside of
     `condition-case'.  This behavior can still be obtained by setting
     them to the symbol `always'.

     Now, if they're `t', the debugger / backtracer is invoked only if
     the control is not inside of any `condition-case'. Notice that the
     condition is NOT if the error is actually handled by an error
     handler. It is not the best, but we can't improve it.

     The default value of `backtrace-on-error' is now `t'.

   * When you evaluate a closure interactively, the module it belongs
     to is printed, too. [Teika kazura]

   * Improved functions' docstring support [Teika Kazura]

     Handling of functions' docstring is improved. The revised
     `documenation' function is ensured to return the docstring of
     functions, macros, and special forms (*note Docstrings::).

     Previously, fuctions' docstrings of byte-compiled user-files (eg:
     pager.jlc) were lost, but not now.

   * New function `subr-structure' [Teika Kazura]
     It returns the module a subr belongs to.

   * Major documentation revision [Teika kazura]

     Reorganized documentation files. Many capital letter name files
     were updated or merged into the info.

     New entries: *Note Crash course for Elisp users::, *Note
     Closures::, on leading tilde in a filename and tarball access
     (*note File Handlers::), fully revised the module section (*note
     Modules::), improved description on invocation (*note
     Invocation::), improved "fluid" and `let' descriptions (*note
     Fluid Variables::, and *note Local Variables::), improved the read
     syntax of character (*note Characters::). Module names are
     supplied for all functions.

     Supplied documentation to some functions: Input stream functions
     `peek-char', `read-char' (*note Input Functions::), list functions
     `remove-if', `remove-if-not' (*note Mapping Functions::),
     `table-size' (*note Hash Tables::), `setcar', `setcdr' and `cdddr'
     family (*note Cons Cells::), `assoc-regexp' (*note Association
     Lists::).

   * `define-special-variable' is replaced by `defvar-setq' [Teika
     kazura]

     The former is still valid, but it's a very confusing name,
     therefore the latter is introduced.

   * Makefile's uninstall rule has been fixed [Christopher Bratusek]

0.90.6
======

   * renamed `file-uid-p' to `file-uid' and `file-gid-p' to `file-gid'
     [Christopher Bratusek]

   * Minor doc improvements [Teika Kazura]

     Describes functions `signal' and `string-split'. Correction in
     suffix handling of `load' function. More details on the function
     `require'.

   * improved specfile [Kim B. Heino]

   * Process execution failure emits better message. [Teika Kazura]

0.90.5
======

   * Byte compiler bugfix in docstring loss [Teika Kazura]

     Practical effect: Previously, if a user byte-compile files, then
     the docstring is lost in sawfish-config. This is fixed.

     Details: Loss of docstring happened only if (1) byte compiler is
     not given `--write-docs', so only byte-compilation by user (2)
     defvar is invoked within macro definition, including `defcustom' in
     Sawfish. Plain defvar was not affected by this bug.  It was
     because in 'trans-defvar' in lisp/rep/vm/compiler/rep.jl, the
     docstring is stored in a wrong property `variable-documentation'.
     It is corrected to `documentation'.

     Symbol `variable-documentation' is not used elsewhere, including
     Sawfish and emacs' sawfish-mode.

   * Our own implementation of dlmalloc is disabled since 2002, as it
     breaks librep on several architectures. From this version on, we
     don't ship it.  [Kim B. Heino]

   * Our own implementation of alloca/memcmp is not needed, rely on
     libcs instead.  [Kim B. Heino]

   * Majorly improved the debian and rpm packaging scripts [Christopher
     Bratusek] [Kim B. Heino]

   * Install headers to $includedir/rep/ instead of $includedir/
     [Christopher Bratusek]

   * Autotools improvements (Makefile, autogen.sh & Co.)  [Christopher
     Bratusek]

   * Added `file-gid-p' function for getting the gid of a file
     [Christopher Bratusek]

   * Added `file-uid-p' function for getting the uid of a file
     [Christopher Bratusek]

0.90.4
======

   * Library version bumped to 9.4.1

   * Use $prefix/lib instead of $prefix/libexec

   * Fixups for OpenBSD [Jasper Lievisse Adriaanse]

   * Don't hardcode /usr in manpage installation path

0.90.3
======

   * Added `file-executable-p' function

   * Improved spec-file [Kim B. Heino]

   * Improved ebuild [Fuchur, Christopher Bratusek]

   * Fallback check for ffi, if there's no libffi.pc [Vincent Untz]

   * Removed rep-config script (use librep.pc instead)

   * Added man-pages for `rep', `repdoc', `rep-remote' and
     `rep-xgettext' [Debian]

   * Added debian packaging scripts based on the official ones

0.90.2
======

   * Fixed a major defunct with prin1 + utf8 [Timo Korvola]

   * Fixed descriptions of formats %s and %S in streams.c

0.90.1
======

   * Properly terminate the rep interpreter [Jürgen Hötzel]

   * Use readline history in interactive mode [Jürgen Hötzel]

   * Tar file-handler does now support XZ compressed tarballs

   * Tar file-handler does now support LZMA compressed tarballs

   * Improved regex for parsing tar output in the file-handler [Alexey
     I. Froloff]

   * We do now correctly check for libffi

   * Improved libffi-binding [Alexey I. Froloff]

   * Updated librep.sym for missing entries [Alexey I. Froloff]

   * Fixed an incomplete definition

   * Added -L$prefix to libs section of the .pc file

   * No C++ style comments in C code

0.90.0
======

   * Added UTF-8 Support! [Wang Diancheng]

   * Remove scheme and unscheme modules

   * Going on with code-cleanup

0.17.4
======

   * Don't ignore datarootdir setting

   * Fixed an aclocal warning from configure.in

   * Improved configures ending message

   * Doc update in 'Numbers' section. Lacking description on machine
     dependence is added. [Teika]

   * Remove tar target from Makefile [Ritz]

0.17.3
======

   * Updated MAINTAINERS

   * Dropped rep.m4 - use librep.pc instead

   * Improved librep.pc

   * Updated librep.spec

   * Add -L/lib$libsuff to READLINE_LIBS [T2 Patch]

   * Fix compilation on PPC64 [Marcus Comstedt]

   * Small fixup in src/fake-libexec [SuSE]

   * No rpath in src/rep-config.sh [Fedora]

   * Added ebuild [Harald van Dijk]

   * Improved Makefile's distclean rule

   * Reworked autogen.sh

   * Reworked configure.in

   * Major rework of the spec-file

   * Improved configure's ending message

   * Fixed configure.in's templates for autoheader

   * BSD-Tar is not supported by librep, give users a usefull warning
     message [Mark Diekhans]

0.17.2
======

   * fixups for configure.in

   * updated BUGS, HACKING and README

   * define inline if undefined (fixes compiler warnings)

   * create the destination directory for the .pc file before
     installing it

   * fixed in issue with FreeBSD in numbers.c [FreeBSD patch]

   * improved a function of numbers.c [FreeBSD patch]

   * rep_file_fdopen has not been listed in librep.sym

   * added -tag=CC to libtool in several places

   * don't ignore $LDFLAGS upon build

   * dropped some useless code in sdbm.c

   * make sure inline is defined


0.17.1
======

   * started code-cleanup

   * added a .pc file

   * added -no-split to makeinfo [FreeBSD patch]

   * added -enable-paranoia to configure [compile with CFLAGS+="-Wall
     -ansi"]

   * updated the spec file

   * replaced a static void by a void in main.c [Debian patch]

   * use correct shebang in rep-xgettext.jl [ALT-Linux patch]

   * trim trailing / to mkdir(2) [NetBSD patch]


0.17
====

   * Added `rep.ffi' module (Foreign Function Interface). Uses gcc's
     libffi. Very untested.

   * Partial implementation of guile's `GH' interface.

   * Bug fixes:

        - Don't hang in select for a second when starting processes via
          the `system' function (race condition that only seems to show
          up on Linux 2.6 kernels)

        - Miscellaneous fixes for Mac OS X.

        - Don't return a reversed list of items from the XML parser.
          (Alexander V. Nikolaev)

        - Fixes to string capitalization functions. (Charles Stewart)


0.16
====

   * New modules `rep.data.trie', `rep.threads.proxy'

   * Also added `rep.xml.reader' and `rep.xml.printer', though these
     should probably be used with extreme caution

   * Appending to queues is now O(1) not O(n)

   * Many changes to `rep.net.rpc' module, protocol is incompatible
     with previous version. Should be more robust

   * `rep.i18n.gettext' module exports the `bindtextdomaincodeset'
     function (Christophe Fergeau)

   * Slightly more secure way of seeding the rng

   * `inexact->exact' can now convert floating point numbers to
     rationals (though not optimally). This means that `numerator' and
     `denominator' also work better with floats now

   * New function `file-ttyp'

   * Some random bug fixes


0.15
====

   * Parser can now associate lexical location (file name and line
     number) with parsed objects. Added `call-with-lexical-origins' and
     `lexical-origin' functions. This adds memory overhead but is only
     enabled in interpreted mode, or other times it could be useful
     (e.g.  when compiling)

   * The compiler enables line-numbering, and uses the information when
     it prints errors. It also prints errors in a more standard format
     (intended to mimic GCC), and distinguishes warnings from errors

   * Debugger is much improved, and supports emacs-style emission of
     line number tokens. Use the included `rep-debugger.el' elisp code
     to source-debug rep programs in Emacs!

   * New command line option `--debug'. When given, rep starts up in
     the debugger

   * Reformatted backtrace output. Also backtraces only ever include
     evaluated argument lists now. They also include lexical information
     when possible

   * Syntax errors include error description and line number

   * Now supports weak reference objects. New functions
     `make-weak-ref', `weak-ref', `weak-ref-set'. A weak reference is a
     pointer to another object. When that object is garbage collected,
     the pointer in the weak reference is set to false.

   * New `error helper' module. When an error is handled, this module
     is called and tries to print a human-understandable message
     explaining why the error may have occurred

   * REPL commands may now be specified by their shortest unique set of
     leading characters, e.g. `,o' instead of `,open'

   * Added an `#undefined' value. Returned by `%define' and the macros
     using it (`defun', `defmacro', etc...)

   * New function `table-size' in module `rep.data.tables'

   * `thread-suspend' returns true iff the timeout was reached (i.e.
     return false if `thread-wake' was used to unsuspend the thread)

   * Objects defined using the `object' macro now have an implicit
     `self' binding - the object representing their self (or their most
     derived self)

   * Added TIMEOUT parameter to `condition-variable-wait' and
     `obtain-mutex' functions

   * New `rep.threads.message-port' module, implements a simple message
     queue for threads

   * `log' function now optionally accepts a second argument, the base
     of the logarithm

   * Use gmp to generate random numbers when possible (if at least
     version 3 of gmp is found) [disabled in librep 0.15.1 - gmp seems
     to be buggy?]

   * The `string-replace' function may now be given a function as its
     TEMPLATE parameter

   * Bug fixes:

        - Signal an error if writes don't write all characters they were
          asked to. Also, some functions could write fewer characters
          than they were supposed to even if no errors occurred

        - Remembered that file sizes may not fit in fixnums

        - Don't preserve trailing slashes in results of
          canonical-file-name (to make the path canonical)

        - Don't signal an error when end of file is encountered
          immediately after reading `#\X' syntax

        - `current-thread' and `all-threads' will create a thread
          object for the implicit thread if there isn't one already

        - In C subrs that take optional integer arguments, signal an
          error if the given value isn't an integer or undefined
          (false). Also, accept all types of numbers where it makes
          sense to do so

        - Signal an error if end of file is read while parsing a block
          comment

        - Don't ever return a null object from `current-time-string'

        - Catch errors signalled during command line option processing,
          and pass them to the standard error handler

        - Right hand side of `letrec' bindings may now have more than
          one form

        - The `object' macro now evaluates its BASE-OBJECT parameter
          exactly once

        - Finally removed `define-value'

        - Ignore null lines (or lines which only have comments) in the
          repl

        - In the compiler, don't expand macros which have have been
          shadowed by local bindings

        - Don't print some compiler errors/warnings twice

        - Fixes for `mips-compaq-nonstopux' architecture (Tom Bates)

        - Fixed `,reload' and `,unload' repl commands not to try to
          remove non-existent structures


0.14
====

   * New module `rep.util.md5', has two functions for generating MD5
     message digests (of files or strings)

   * Changes to the `rep.io.sockets' function:

     In the `socket-server' function the HOST and/or PORT arguments may
     be false, meaning to listen on all addresses and to choose a
     random unused port.

     New functions `socket-peer-address' and `socket-peer-port', these
     always returns the details of the far end of the connetion.
     `socket-address' and `socket-port' have been changed to always
     return the details of the local connection point.

   * New function in `rep.system' module, `crypt'. A wrapper for the
     system's `crypt' function (if it has one)

   * New function in `rep.threads' mdoule, `make-suspended-thread'

   * New module `rep.net.rpc', provides a text-stream based RPC
     mechanism for Lisp programs. Similar in some ways to untyped CORBA.
     (This is still in the experimental stage - its interface may
     change in forthcoming releases)

   * New functions in `rep.data' module, `list->vector' and
     `vector->list'

   * New macro `define-special-variable'. A combination of `defvar' and
     `setq' - it always makes the variable special and it always sets
     it to the given value

   * New module `rep.test.framework' implementing `assert', `check' and
     `test' macros. This provides a framework for implementing unit
     tests in Lisp modules (such that running the interpreter with the
     `--check' option will run all tests that have been set up to be
     autoloaded

   * Bug fixes:

        - When reading from strings, don't choke on zero bytes

        - When writing into sockets, be aware that the socket is in
          non-blocking mode

        - SDBM and GDBM modules now close any open databases before the
          interpreter exits

        - Fixed the `rep_parse_number' function not to require a
          terminating null character in the string when parsing bignums

        - Only define `Qrep_lang_interpreter' once

        - Don't assign vm registers to physical registers on 68000
          architectures - it's been reported to crash

        - When running asynchronous subprocesses, open and initialize
          the pty slave before forking to avoid a race condition with
          the child process

        - Flush symbols from the module cache at another point

        - Fixes for Unixware

        - When compiling non-top-level `defvar' forms, add any doc
          string they have to the database


0.13.5
======

   * Tar file handling no longer requires GNU tar

   * The `defvar' special form can now take only a single argument

   * The reader now treats `#\return' characters as white space

   * Other miscellaneous bug fixes...


0.13.4
======

   * Don't restrict symbols exported from plugin libraries, some need
     to export symbols to work properly (this bug only seemed to appear
     on Solaris systems)

   * Added `rep_file_type' and `rep_guardian_type' to the list of
     symbols exported from librep

   * Fixed the `install-aliases' script (Peter Teichman)

   * New module `rep.threads.condition-variable'

   * Added `string-split' and `string-replace' to the gaol


0.13.3
======

   * Try to only export public symbols from `librep.so' and modules

   * When expanding file names translate `/..' to `/'

   * Set an upper bound on the allowed recursion depth when regexp
     matching, prevents the stack from overflowing in pathological cases

   * Added optional second arg to `readline' function, a function to
     call to generate completions. The `rl-completion-generator' method
     of supplying this function is deprecated

   * Fixed bugs when handling character-case in regexp module (Andrew
     Rodionoff)

   * Added an `premature-end-of-stream' error. This is signalled
     instead of `end-of-stream' when reading characters in the middle
     of a syntax form. The `end-of-stream' error is only signalled when
     the end of the stream is reached before encountering anything other
     than whitespace characters

   * Fixed bug of expanding declarations in the `define' macro expansion


0.13.2
======

   * Fix `define' so that it tracks bound variables and ignores
     shadowed keywords when traversing code

   * Added checks to compilation process for the kind of missing
     shared-library problems that many people see

   * Fixed the `install-aliases' shell script

   * New configure option: `--enable-full-name-terminator'


0.13.1
======

   * Added functions `remove-if' and `remove-if-not'

   * Various bug-fixes for non-linux or solaris systems (John H.
     Palmieri, Philippe Defert)

   * `#f', `#t', `#!optional', `#!key' and `#!rest' are now uninterned
     symbols. Keywords are interned in a separate obarray

   * Fixed bug of caching regexps even when their string has been
     modified

   * Fixed some bugs in the ftp remote file handler and the
     `pwd-prompt' function

   * Fixed `define' to ignore `structure' and `define-structure' forms


0.13
====

   * The end-of-list / boolean-false object is no longer the symbol
     `nil'. Instead there is a special object `()' fulfulling these two
     roles. For modules importing the `rep' module, the symbol `nil'
     evaluates to `()'. This allows the `scheme' module to be more
     compliant with the Scheme standard

   * Parameter list changes:

        - Deprecated `&optional' and `&rest', in favour of `#!optional'
          and `#!rest'.

        - Added keyword parameters. Use `#!key' to declare them.
          Keyword syntax is `#:PARAM'. For example:

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

        - `#!optional' and `#!key' parameters may now have default
          values, syntax is `(VAR DEFAULT)'. For example:

               ((lambda (#!optional (a 1)) a)) => 1

   * The module namespace is now hierarchical. `.' characters in module
     names denote directory separators, e.g. `foo.bar' translates to
     the file `foo/bar'

     All module names prefixed with `rep.' are reserved for librep,
     other top-level names should be picked to be as unique as possible

     The existing modules have been renamed to fit this scheme (see the
     file `TREE' in the distribution for the hierarchy details).
     However, old module names will still work for the time being

   * The `rep' module no longer includes the `rep.regexp',
     `rep.system', `rep.io.files', `rep.io.processes' or
     `rep.io.file-handlers' modules. These need to be imported
     explicitly

   * Doc strings are now indexed by module name as well as symbol name.
     The `define' macro now takes a doc string as its optional third
     parameter

   * Record constructors may include all lambda-list keywords (e.g.
     keywords and/or default values)

   * Incompatible virtual machine changes, hence bytecode files will
     need to be recompiled. Improvements include:

        - Only heap-allocate variables when absolutely necessary

        - Closure analysis to allow inlining of some types of `letrec'
          expressions

        - Added a `safe' virtual machine, which makes no assumptions
          regarding validity of bytecode, so is safe for untrusted code

   * Added an `unscheme' module. Another Scheme implementation, but the
     goal of this one is to integrate cleanly with the librep runtime
     environment, even if this is at the expense of R4RS compliance

     For example, in `unscheme' code, `#f => ()' and `#t => t'. This
     allows rep and unscheme functions to call each other without
     needing to convert any data

   * By default, it is now illegal to modify top-level variables that
     have not previously been defined

   * New macro `define-structures' to export multiple views of a single
     underlying environment

   * The librep runtime no longer handles the `--help' option itself,
     this should be done by scripts

   * Don't search `$LD_LIBRARY_PATH' for plugins, but prepend all
     directories in colon-separated `$REP_DL_LOAD_PATH' to
     `dl-load-path'. Similarly, the contents of `$REP_LOAD_PATH' is
     prepended to `rep-load-path'

   * `(/ X) => (/ 1 X)'

   * Extra string-manipulation functions: `string-replace',
     `string-split' (in the `rep.regexp' module)

   * `#f' and `#t' are now primitive symbols, not special objects

   * Special case tail-recursive calls to `apply', to ensure they get
     eliminated

   * The `0x123' and `0123' read syntaxes have been deprecated, use
     `#x123' and `#o123' instead

   * `#| ... |#' comments now nest correctly

   * New modules: `rep.i18n.gettext', `rep.vm.safe-interpreter',
     `rep.vm.assembler', `unscheme', `rep.data.objects',
     `rep.www.quote-url', `rep.www.fetch-url', `rep.util.ispell',
     `rep.util.base64', `rep.util.autoloader', `rep.io.sockets',
     `rep.util.time', `rep.net.domain-name'

   * Bug fixes, including:

        - Find size of `long long' type on AIX, IRIX and Solaris (Dan
          McNichol, Albert Chin-A-Young)

        - Never allow macros to be called as functions

        - Make bitfields unsigned (Albert Chin-A-Young)

        - Fixed bounds-checking when parsing non-base-10 fixnums

        - Thread fixes (and much lower thread-switch latency in many
          cases)

        - Fixed `DEFUN' macro for C++ (Matt Tucker); also fixed header
          files to avoid C++ keywords

        - Make error message for bytecode version mismatches more
          meaningful

        - Fixed: `default-boundp', `continuation-callable-p'

        - Only the evaluate the value of `defvar' forms if the symbol
          isn't already bound

        - Compile else-less `case' expressions correctly; eliminate
          tail-recursion in `cond' forms when possible

        - Various fixes in `scheme' module

0.12.4
======

   * Support building without GNU MP, `--without-gmp' option to
     configure. Use `long long' for non-fixnum integers (promote to
     floats when out of range); no exact rationals. There's also an
     option to disable continuations/threading
     (`--disable-continuations')

   * Sanitized function inlining:

        - Use `(declare (inline NAMES...))' to tell the compiler that
          it might be useful to inline the named functions

        - Don't even think about inlining across module/file boundaries
          (for now anyway)

   * Cleaned up the `gaol' module. Interface is essentially:
     `gaol-define', `gaol-define-special', `gaol-define-file-handler'.
     Added `gaol-open' to import complete modules. Still supports old
     interface

   * Be a lot more efficient when printing quoted strings and symbol
     names (for some streams there used to be a system-call per
     character!)  Also, when quoting weird symbol names, be more
     intelligent

   * Removed code to autoload from modules (which didn't really work
     anyway)

   * Be more intelligent about deciding when to flush the module cache

   * Build fixes for IRIX (David Kaelbling)

   * Other miscellaneous bug-fixes and performance tweaks


0.12.3
======

   * New function `thread-join', waits for a specified thread to exit,
     then returns the value of the last form it evaluated

   * Added a rudimentary profiler (`,profile FORM' command in repl)

   * Reorganized `ring' module, sanitized the interface (preserving
     compatibility with old functions), also added a `ring->list'
     function

   * `rplaca' and `rplacd' (but not `setcar' and `setcdr') functions
     now return the cell being modified, not the value being stored
     into it, for compatibility with CL (Karl Hegbloom)

   * `unwind-protect', `catch', `condition-case': these special forms
     are now macros

   * When signalling `bad-arg' or `missing-arg' errors, try to include
     the function as the first element of the error data

   * `load' function now _only_ loads files without suffixes if
     NO-SUFFIX arg is non-`nil' (prevents picking up un-suffixed files
     by mistake, e.g. from the current directory)

   * Fixed some bugs when reading rationals

   * Fixed bug of `gettext' module not redefining `_' binding in `rep'
     module

   * Fixed bug when building `rep-config' script (Mark Hewitt, Dan
     Winship)

   * Fixed bug of `rep_INTERN_SPECIAL' macro not looking for default
     values of special variables

   * Fixed interpreted versions of `min' and `max' when operating on
     non-numeric values

   * If unable to allocate heap space, just print an error and
     terminate the program (the low-memory handling doesn't currently
     work properly)

   * Fixed bug when extracting doc strings from `define' forms

   * Fixed bug when compiling structure definitions in non-top-level
     environments

   * Fixed bug of being unable to `load' empty files

   * When recursively macro-expanding, dereference identifiers in the
     correct module


0.12.2
======

   * The tar file-handler now caches the unpacked archive (wins big
     when loading sawfish themes)

   * The `gaol' module can now create multiple gaols, each with it's
     own namespace

   * More performance tweaks

   * Miscellaneous bug-fixes (more vm stack smashing, `defconst' never
     evaluates its constant)


0.12.1
======

   * Some virtual machine performance tweaks

   * Fixed nasty stack smashing bug (when using compiler declarations)

   * Some 64-bit cleanups (George Lebl)

   * Fixed non-ANSI C syntax (Sam Falkner)


0.12
====

   * Added a basic module system.

     Modelled after the Scheme48 system, but simpler. At its simplest,
     include a `define-structure' form in each file representing a
     module:

          (define-structure NAME INTERFACE CONFIG BODY...)

     The external definitions of this module can then be imported by
     other modules through their CONFIG statements, e.g. `(open
     NAMES...)'. Most modules will open `rep' to get the standard
     language definitions.

     `foo#bar' reads as `(structure-ref foo bar)'

     The `timers', `tables', `sdbm', `gdbm', `readline', `gettext',
     `ring', `mutex', `memoize', `lisp-doc', `disassembler', `compiler',
     `date', `cgi-get', `gaol' features are all now modules (this is
     backwards compatible, since modules may be imported using
     `require')

     See the "Modules" section of the manual for more details.

   * The repl now contains meta-commands for inspecting and configuring
     the module system (amongst other things)

   * Added a facility for creating new primitive types: `make-datum',
     `datum-ref', `datum-set', `has-type-p', `define-datum-printer'

   * Added an SRFI 9 compatible `define-record-type' macro for defining
     data structures (the `records' module)

   * Added fluid variables--a method of creating dynamically scoped
     bindings that fit well with lexically scoped definitions
     (`make-fluid', `fluid', `fluid-set', `with-fluids', `let-fluids')

   * Added a `queues' module providing a basic queue type

   * Added stream functions: `peek-char', `input-stream-p',
     `output-stream-p'

   * Interpreter now also eliminates tail-calls

   * Changed handling of inexact numbers to be compatible with the
     Scheme standard:

        - Many operations now produce inexact outputs if any of their
          inputs are inexact (e.g. `min', `max', `floor', `ceiling',
          `round', `truncate')

        - `eql' and `equal' no longer ignore exactness when comparing
          numbers. `=', `/=', `<', `>', `<=' and `>=' _do_ ignore
          inexactness. E.g.

               (eql 2 2.) => nil
               (= 2 2.) => t

   * Support most of Scheme's read-syntax for numbers (i.e. `#b', `#o',
     `#d', `#x' radix prefixes, and `#e', `#i' exactness prefixes).

   * Implemented Scheme's `string->number' and `number->string'
     functions

   * Included a basic R4RS Scheme implementation (module: `scheme'). Do
     `,new foo <RET> ,open scheme' to test it in the repl, use `(open
     scheme)' instead of `(open rep)' to use it within modules.

     The compiler also knows enough about Scheme to be able to compile
     it.  Also, use the `-s' or `--scheme' options to load a file of
     Scheme code.

   * The debugger works better (and can be used to walk the stack
     history somewhat)

   * Last arg of `append' and `nconc' may be a non-proper-list now

   * Implemented the Scheme `do' macro for iteration

   * `define' supports curried functions. E.g. `(define ((plus a) b) (+
     a b))', then `(plus 1)' evaluates to the function that adds one to
     its argument.

   * Many performance improvements:

        - Allocates less memory (so garbage collects less often)

        - Much faster at bytecode-to-bytecode function calling

        - Much reduced VM overhead (when compiled with GCC)

   * Compiler improvements:

        - Supports the `(declare CLAUSES...)' form. See the "Compiler
          Declarations" section of the manual for details on the actual
          declarations supported.

        - Is cleverer about detecting when to create new bindings when
          tail recursing, and when the old bindings can just be
          overwritten

        - Groks the module system, and the language of the module being
          compiled (so that it can compile both rep and Scheme code)

        - Splices bodies of top-level `progn' and `begin' forms
          themselves into the top-level (for when macros expand into
          multiple definitions)

        - Compiling already defined functions (or whole modules of
          functions) now (mostly) works

        - Coalesce and compile non-defining top-level forms

   * Many bug fixes (see ChangeLog files for details)


0.11.3
======

   * Fixed bug of throwing uninitialized errors when autoloading

   * Fixed bug of interpreting `(let () ...)' as a named let

0.11.2
======

   * Replaced many special forms by macros--`let', `let*', `function',
     `if', `and', `or', `prog2', `defmacro', `defun', `defconst',
     `define-value', `setq-default'

   * `let' now supports Scheme's named-let construct for iteration via
     tail recursion

   * Parse some standard Common Lisp and Scheme syntax: `#| ... |#'
     block comments, `#\C' or `#\NAME' characters (where NAME may be
     one of: `space', `newline', `backspace', `tab', `linefeed',
     `return', `page', `rubout'), and `#(...)' vectors

   * When comparing symbols, compare their names as strings

   * Implemented Scheme's `dynamic-wind' function

   * Fixed bug of sometimes evaluating function arguments in the
     environment of the callee not the caller

   * Fixed bug when calculating how long to sleep for when no threads
     are available

   * Fixed bugs in mutex implementation (Damon Anderson)

   * Work around bugs in Tru64 `RTLD_GLOBAL'; everything should work on
     Tru64 now (Aron Griffis)

   * Fixed bug of not saving current regexp state across continuations


0.11.1
======

   * The compiler now eliminates single-function tail calls (instead of
     leaving it to the virtual machine)

   * Updated to use libtool-1.3.4

   * Miscellaneous bug fixes and minor changes

0.11
====

   * Better support for numerical computing. Now supports bignums,
     rational numbers (numerator and denominator are bignums), and
     floating point values as well as the original fixnums. Many new
     numerical functions supporting these types. Promotes and demotes
     hopefully as you'd expect (never demotes an inexact number to an
     exact number).  Tries to follow the Scheme numeric system as much
     as possible

   * Supports "guardian" objects through the `make-guardian' function
     (as described in Dybvig's paper). These are a clean mechanism for
     allowing the programmer to control when arbitrary lisp objects are
     finally deallocated. Also added a new hook: `after-gc-hook'

   * The default error handler can now be redefined. If the variable
     `error-handler-function' contains a function then it will be
     called to handle the error, with arguments `(ERROR DATA)'.

   * New special form `case', switches on a key value and sets of
     constants

   * New function `call/cc' (also available through the alias
     `call-with-current-continuation'). Provides scheme-like
     continuation functions. Special variables are now deep-bound to
     support this correctly

   * Supports "soft" preemptive threads using continuations and a
     general "barrier" mechanism (used either for restricting control
     flow, or for receiving notification when control passes across a
     barrier)

   * Parameter lists in lambda expressions now support improper lists,
     as in scheme. E.g. `(lambda (x . y) ...)'

   * Implements the scheme `define' syntax, with support for inner
     definitions

   * The `tables' plugin implements hash tables, with extensible
     hashing and comparison methods; supports both strongly and weakly
     keyed tables

   * Included a GDBM binding; DOC files are now stored in GDBM files
     (SDBM has limits on datum sizes)

   * `put' and `get' functions now use `equal' to compare property names

   * Virtual machine / compiler improvements:

        - Variable references and mutations are classified by type:
          lexical bindings use (one-dimensional) lexically addressed
          instructions, global non-special bindings have their own
          instructions, everything else uses the original instructions.
          Similar classification when creating new bindings

        - Eliminate tail-recursive function calls wherever possible in
          compiled code (when the calling function has no dynamic state)

     Compiled lisp code will need to be rebuilt to run on the modified
     virtual machine.

   * When expanding macros, bind `macro-environment' to the macro
     environment it was called with. This allows macros to reliably
     expand inner macro uses

   * New hook `before-exit-hook'. Called immediately before exiting

   * `rep-xgettext' now has an option `--c'. This makes it output
     pseudo C code containing the string constants found

   * Fixed misfeature of interpreting filenames `FOO//BAR' as `/BAR'.
     Contiguous path separators are now merged (i.e. `FOO/BAR')


0.10
====

   * Updated support for dumping (freezing) lisp definitions to handle
     lisp-1 nature with closures. Also now generates C code instead of
     assembler for portability; creates a plugin that may be loaded
     through the REP_DUMP_FILE environment variable

   * Plugin `.la' files may now contain rep-specific settings:
     `rep_open_globally=yes' and `rep_requires='FEATURES...''

   * New function `define-value'. A combination of `set' and `defvar',
     but without implying dynamic scope

   * `load' scans AFTER-LOAD-ALIST for plugins as well as lisp libraries

   * `(if t)' now evaluates to `nil' not `t'

   * Fix regexp bug in matching simple non-greedy operators (Matt Krai)

   * Borrowed guile's bouncing parentheses for readline (Ceri Storey)

   * New C functions `rep_load_environment' and `rep_top_level_exit'

   * `defvar' allows symbols to be redefined in protected environments
     if they haven't also been defined by unprotected environments

   * Detect GCC's with broken `__builtin_return_address' functions
     (George Lebl)

   * Try to use libc `gettext' implementation, but only if it looks
     like it's the GNU implementation


0.9
===

   * Support for using GNU readline (give configure the
     `--with-readline' option)

   * New functions: `letrec', `caar', ..., `cddr', `caaar', ...,
     `cdddr', `in-hook-p', `make-variable-special'

   * Changed `unless' to have the Common Lisp semantics--return `nil'
     when the condition evaluates true, not the value of the condition

   * Fixed/added some compiler optimisations

   * Fixed `rep-xgettext' script to remove duplicated strings and to
     search exhaustively

   * `add-hook' forces the hook variable to be special (in case it
     wasn't declared using `defvar')


0.8.1
=====

Fixed some documentation bugs; fixed some build problems

0.8
===

   * Default scoping is now lexical, only variables declared using
     `defvar' are dynamically scoped.

   * There is now only a single namespace for symbols (excepting
     property lists), this means that the `fset', `symbol-function' and
     `fboundp' functions have been removed

     This allows all elements in procedure-call forms to be evaluated
     equally (as in scheme), so things like:

          ((if t + -) 1 2)

     now work. Related to this, function names (i.e. symbols and lambda
     expressions) are no longer dereferenced by any operations taking
     functions as arguments. Only built-in subroutines and closures are
     considered functions.

     This means that where before you'd write something like:

          (mapcar '+ '(1 2 3))

     this is now illegal; the `+' function must be evaluated:

          (mapcar + '(1 2 3))

   * `lambda' is now a special form evaluating to a closure (as in
     scheme); this means that the following are exactly equivalent:

          (lambda (x) x) == (function (lambda (x) x)) == #'(lambda (x) x)

     An alternative method of enclosing a lambda expression is to use
     the `make-closure' function.

   * `gaol' module providing semi-safe environment for untrusted code
     to evaluate in

   * Support for i18n through `gettext' module; also support for `%1$s'
     type format specifiers

   * New functions `string-equal' and `string-lessp'


0.7.1
=====

   * Added `--with-rep-prefix' option to autoconf AM_PATH_REP macro

   * Fixed bug when inserting a new timer before an existing timer

   * Fix the malloc tracking code

   * Fix dlmalloc for FreeBSD

   * Use install when installing, not cp

   * Some fixes for compiling with SUN's C compiler on Solaris


0.7
===

   * Added file handler for read-only access to the contents of tar
     archives, access files like `foo.tar.gz#tar/bar'

   * `process-id' function now returns pid of lisp interpreter when
     called with zero arguments

   * Added (untested) support for loading dynamic objects via
     `shl_load' (HP-UX)

   * Added (untested) support for systems that prefix symbol names in
     dynamic objects with underscores

   * Fix bug when compiling `last' function

   * Fix bug of not closing files in the `load' function


0.6.2
=====

   * Added `autoload-verbose' variable; set it to `nil' to turn off the
     messages when autoloading

   * Fix problems when `--prefix' option has a trailing slash

   * Updated libtool files to version 1.3.3

   * Initial (incomplete) support for building under Tru64, from Aron
     Griffis


0.6.1
=====

No new features; minor portability tweaks and build changes. Fix bug of
trying to load directories as Lisp scripts

0.6
===

   * Add `unsetenv' function

   * `system' now uses `process-environment'

   * Workaround compiler bug with GCC 2.95 on sparc

   * Fix build problem where libsdbm.la can't be located


0.5
===

   * New function `set-input-handler', registers an asynchronous input
     handler for a local file

   * Don't abort on receipt of unexpected `SIGCHLD' signals

   * Upgrade libtool to version 1.2f

   * The `rep' binary by default always loads a script named `rep', not
     named by it's `argv[0]' (this breaks under the newer libtool)


0.4
===

   * Sending a rep process a `SIGUSR2' prints all debug buffers

   * Added `--with-value-type', and `--with-malloc-alignment' configure
     options. Also added code to automatically detect the first of
     these options.

   * Fixed some 64-bit problems

   * Removed the difference between static and dynamic strings


0.3
===

   * New compiler command line option `--write-docs'


0.2
===

   * The variables `error-mode' and `interrupt-mode' control where
     errors and user-interrupts (i.e. `SIGINT' signals) are handled.
     The three possible values are: `top-level', `exit' and `nil'
     (denotes the current event loop).

   * Fixed bug where all dynamic types were erroneously `symbolp'.

   * `SIGINT', `SIGHUP' and `SIGTERM' signals should now be caught more
     successfully.

   * Added a new directory to `dl-load-path': `LIBEXECDIR/rep/ARCH' to
     contain third-party shared libraries.


0.1
===

First public release.


File: librep.info,  Node: Invocation,  Next: The language,  Prev: News,  Up: Top

4 Invocation
************

* Menu:

* Rep execution::
* Shebang invocation::  #!/usr/bin/rep
* Interactive environment::


File: librep.info,  Node: Rep execution,  Next: Shebang invocation,  Up: Invocation

4.1 Rep execution
=================

Call `rep' program to launch a stand-alone `librep' environment:

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

Where REP-OPTIONS may be any of the following:

`--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 FILE'
     Try to load the Lisp file FILE, this is equivalent to evaluating
     the form `(load "FILE")'.

`-q'
     Terminate the Lisp process and exit.

   If FILE is given, it names the Lisp file to load, and `--batch-mode'
is implied. Any SCRIPT-OPTIONS will be made available to the script in
the `command-line-args' variable.  See *Note Command Line Options::.

   After any arguments have been processed, it enters the interactive
environment, unless `--batch-mode' was specified. See *note Interactive
environment::.


File: librep.info,  Node: Shebang invocation,  Next: Interactive environment,  Prev: Rep execution,  Up: Invocation

4.2 Shebang invocation
======================

The `rep' interpreter also supports "Shebang", or `#!' interpreter
invocation, i.e. if the first line of an executable text file contains
`#!PROG', the program PROG is used to execute the script, using the
operating system's support.

   However with this method, the `PATH' environment variable is not
searched for the location of the interpreter, and thus the full file
name of the `rep' interpreter program must be hard-coded into the
script.

   To work around this problem `rep' supports a slightly different
method of invocation; first look at this example:

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

     ;; Lisp code follows...

   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.


File: librep.info,  Node: Interactive environment,  Prev: Shebang invocation,  Up: Invocation

4.3 Interactive enviroment
==========================

When you invoke the stand-alone librep interpreter without giving it a
script to execute the system is started in interactive mode. This means
that the "REPL" is entered--the read-eval-print loop.

   The read-eval-print loop simply reads complete Lisp forms (*note 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'), or until you enter `,quit' command.

   The REPL works as its name suggests. It reads Lisp forms from the
console, evaluates them, and then prints the result back to the
console. Here is an example REPL session:

     user> (+ 1 1)
     2
     user> (cons 'a 'b)
     (a . b)

The `user>' string is the prompt that the REPL prints when it is
waiting for an input form. This form may span several lines, e.g.:

     user> (cons 'a
     'b)
     (a . b)

The prompt above contains the string `user'. This is the name of the
module that the form will be evaluated in (*note Modules::).

   As well as allowing arbitrary Lisp forms to be entered and evaluated,
the REPL provides a rich set of meta-commands, these are used to
configure and inspect the state of the system, as well as providing
convenient shortcuts for common operations.

   A meta-command is differentiated from a normal Lisp form by preceding
it with a comma (`,') character. The name of the command should follow
the comma, with any argument forms after that. Note that unlike normal
Lisp forms, no parentheses are used to mark the command application.

   For example the `whereis' meta-command searches all loaded modules
for those exporting a particular symbol. It might be used as follows:

     user> ,whereis string-match
     string-match is exported by: rep.regexp

The following table lists all currently supported meta-commands:

`access STRUCT ...'
     Add the modules named STRUCT ... to the list of structures whose
     exported definitions may be accessed by the current module (using
     the `structure-ref' special form).

`accessible'
     Print the names of the modules whose contents may be accessed
     using the `structure-ref' form from the current module.

`apropos "REGEXP"'
     Print the definitions in the scope of the current module whose
     names match the regular expression REGEXP.

`bindings'
     Print all bindings in the current module.

`collect'
     Run the garbage collector.

`compile [STRUCT ...]'
     Compile any uncompiled functions in the modules named STRUCT ....
     If no named modules are given, use the current module.

`compile-proc PROCEDURE ...'
     Compile the functions called PROCEDURE ... in the current module.

`describe SYMBOL'
     Look for documentation describing the current meaning of SYMBOL,
     if any is found, print it.

`dis FORM'
     Disassemble the bytecode form or compiled function that is the
     result of evaluating FORM.

`expand FORM'
     Print FORM with any outermost macro calls recursively expanded.

`exports'
     Print the names of the variables exported from the current module.

`help'
     List all REPL commands.

`imports'
     Print the names of the modules imported by the current module.

`in STRUCT [FORM]'
     If FORM is given, temporarily switch to the module called STRUCT,
     evaluate FORM printing the result, then switch back to the
     original module.

     If FORM isn't given, simply switch the current module to be STRUCT.

`interfaces'
     Print all defined module interfaces, and their definitions.

`load STRUCT ...'
     Attempt to load the module called STRUCT.

`load-file "FILENAME" ...'
     Load the file of Lisp forms called FILENAME.

`locate SYMBOL'
     Recursively scan from the current module for the module providing
     the binding of SYMBOL.

`new STRUCT'
     Create a new module called STRUCT, and set it as the current
     module. It will import the `rep.module-system' module, but nothing
     else (i.e. no actual language).

`open STRUCT ...'
     Import the modules called STRUCT ... to the current module.  This
     is analogous to the `open' clause in the configuration form of the
     module's definition.

`profile FORM'
     Evaluate FORM, recording information about the frequency and
     duration of the calls it makes to subroutines (and the calls they
     make, and so on). This information is tabulated and printed after
     the evaluation has finished.

`quit'
     Terminate the Lisp interpreter.

`reload STRUCT ...'
     Reload the modules called STRUCT .... If modules of these names
     had previously been loaded, they will be deallocated when there
     are no remaining references to them.

     Note that importing the interface of one module into another does
     not create object references between the two modules (the
     references are purely symbolic). However, each closure (i.e.
     function) created in a module does contain a reference to the
     module it was created in.

`step FORM'
     Evaluate FORM in single-step mode (using the debugger).

`structures'
     Print the names of all currently defined modules.

`time FORM'
     Evaluate the form FORM, print the result and the time it took to
     perform the evaluation.

`unload STRUCT ...'
     Attempt to unload the modules called STRUCT .... As with
     reloading, unloading a module only removes the link between the
     module name and the module body. Only once no more references
     exist to the module body will it be freed.

`whereis SYMBOL'
     Scan all loaded modules for those that export a binding of SYMBOL,
     and print the results.

   Repl imports some modules by default. They are `rep',
`rep.io.files', `rep.io.processes', `rep.module-system', `rep.regexp',
and `rep.system'. It is so because the repl itself needs them.

   Don't confuse the interactive environment provided by `rep' command
with Sawfish's one - `sawfish-client'; it does not evaluate any, but it
merely sends expressions to the running instance of Sawfish window
manager, and prints the result.  (*note Sawfish Manual: (sawfish)Top.)


File: librep.info,  Node: The language,  Next: librep Internals,  Prev: Invocation,  Up: Top

5 The language
**************

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

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

Sockets
     `src/sockets.c'.

Dbms
     `src/repgdbm.c' and `src/repsdbm.c'.

`dynamic-wind'
     `lisp/rep/lang/interpreter.jl'.


File: librep.info,  Node: Rep's Lisp Introduction,  Next: Crash course for Elisp users,  Up: The language

5.1 Rep's Lisp Introduction
===========================

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 *Note 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


File: librep.info,  Node: Features as Lisp,  Next: nil and t,  Up: Rep's Lisp Introduction

5.1.1 Features as Lisp
----------------------

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

   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 (optionally) 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


File: librep.info,  Node: nil and t,  Next: The Lisp Reader,  Prev: Features as Lisp,  Up: Rep's Lisp Introduction

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

In librep 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 (*note
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.


File: librep.info,  Node: The Lisp Reader,  Next: Notation,  Prev: nil and t,  Up: Rep's Lisp Introduction

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

   *Note Data Types::.


File: librep.info,  Node: Notation,  Next: Descriptions,  Prev: The Lisp Reader,  Up: Rep's Lisp Introduction

5.1.4 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'.


File: librep.info,  Node: Descriptions,  Prev: Notation,  Up: Rep's Lisp Introduction

5.1.5 Descriptions
------------------

In this document the simplest type of descriptions are those defining
variables (*note 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 (*note Hooks::) are also described in this format, the only
difference is that `Variable:' is replaced by `Hook:'.

   Functions (*note Functions::) and macros (*note 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 (*note 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 (*note 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.


File: librep.info,  Node: Crash course for Elisp users,  Next: Data Types,  Prev: Rep's Lisp Introduction,  Up: The language

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

Interactive evaluation
----------------------

To evaluate Lisp expressions interactively, or to enter "REPL" - read,
eval, print loop - then call `rep' or `sawfish-client':

     $ rep # or
     $ sawfish-client

   These two look similar, but there's a striking difference. The `rep'
program starts a clean, new REPL, but in `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:

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

   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 `C-x C-e' like "Lisp interaction" mode, it works as a wrapper
to `sawfish-client', and the expression is sent to it. For more on
Sawfish, read Sawfish manual.

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 `defvar':

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

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

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

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

   Like Elisp, `defvar' does not override an existing value. (But
`define' does.) Function `defvar-setq' is `defvar' + `setq', so it
declares a global variable, and sets the value.  (It was previously
called `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 `let' in Elisp. This works too in Rep,
but ONLY with global variable. Please see the next example:

     (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)
        => outer
     ;; The let binding is newly established _inside_ of bar,
     ;; and foo doesn't see it.

     ;; Difference to defvar.
     (defvar a 'outer)
     (bar)
        => inner ;; The scope of `a' is now dynamic.

   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 *Note Fluid Variables::.

Functions
---------

You may be shocked by the following example:

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

     (define bar foo)
     (bar 'baz)
       => baz

     bar
       => <#closure foo @ my-module>

     ;; More straight example
     ((lambda (a b c)
        (list c b a))
      1 100 10000)
       => (10000 100 1)

   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 `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 `define', like the above example.  The
grammar is intuitive, where the definition looks the same as
invocation. Definitions with `define' can be nested, so you can easily
write helper functions which are only visible to the wrapping function.

   Use `#!optional' and `#!rest', instead of `&'. You can also use
named argument passing with `#!key'. See *Note Lambda Expressions::.

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

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

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

Modules
-------

See *Note 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.)

Misc
----

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

   The symbol `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.

   `#f' evaluates to `()', and `#t' to `t'. These two come from Scheme.

   Rep does not have the notion of "command", but Sawfish does.  See
*Note Commands: (sawfish)Commands.

   If you loop over list elements, then `mapc' and `mapcar' are fast,
like Emacs. But "tail-recursion" is better than a `while' loop if
byte-compiled (*note Compilation Tips::.)


File: librep.info,  Node: Data Types,  Next: Numbers,  Prev: Crash course for Elisp users,  Up: The language

5.3 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 (*note
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.

* 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


File: librep.info,  Node: Types Summary,  Next: Read Syntax,  Up: Data Types

5.3.1 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. *Note Numbers::.

"Cons cell"
     An object referring to two other Lisp objects. *Note Cons Cells::.

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

"Vector"
     A one-dimensional array of objects. *Note Vectors::.

"String"
     A vector of characters. *Note Strings::.

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

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

"Symbol"
     A symbol is a named object; they are used to provide named
     variables and functions. *Note 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. *Note
     Files::.

"Process"
     An object through which processes may be created and controlled.
     *Note Processes::.

"Stream"
     Serial data sinks and sources. These may include files, functions,
     and processes. *Note 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.


File: librep.info,  Node: Read Syntax,  Next: Printed Representation,  Prev: Types Summary,  Up: Data Types

5.3.2 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 `|#'.  *Note 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

     For full documentation, read *Note Number Read Syntax::.

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

          "This is a string"

Character
     In Librep, a character is an unsigend 8-bit integer. It read syntax
     is a question mark(`?') and the character itself. For the details,
     see *Note Characters::.

          ?a
              => 97

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
     For more, read *Note Symbol Syntax::.


File: librep.info,  Node: Printed Representation,  Next: Equality Predicates,  Prev: Read Syntax,  Up: Data Types

5.3.3 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 (*note 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 `#<...>'.


File: librep.info,  Node: Equality Predicates,  Next: Comparison Predicates,  Prev: Printed Representation,  Up: Data Types

5.3.4 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. See also the document of `='. (*note Comparison
     Predicates::.)

          (eql 3 3)
              => t

          (eql 1 2)
              => ()

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

          (eql 'x 'x)
              => t


File: librep.info,  Node: Comparison Predicates,  Next: Type Predicates,  Prev: Equality Predicates,  Up: Data Types

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


File: librep.info,  Node: Type Predicates,  Next: Garbage Collection,  Prev: Comparison Predicates,  Up: Data Types

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


File: librep.info,  Node: Garbage Collection,  Prev: Type Predicates,  Up: Data Types

5.3.7 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 *note 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 (*note Normal Hooks::) called immediately after each
     invocation of the garbage collector.


File: librep.info,  Node: Numbers,  Next: Sequences,  Prev: Data Types,  Up: The language

5.4 Numbers
===========

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

   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, *Note Types of Numbers::.

   For conversion of number from / to string, see *Note String
Functions::.

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

* 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::

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

   (1) GMP, or GNU MP is a library which supports arbitrary precision
arithmetic.


File: librep.info,  Node: Types of Numbers,  Next: Numeric Predicates,  Up: Numbers

5.4.1 Types of Numbers
----------------------

First understand that librep distinguishes `exact' and `inexact'
numbers. This is similar to Scheme. 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.

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

   Without gmp, only integer is exact. Rational numbers get approximated
with float. On 32-bit system, integer is signed 30-bit (_not_ 32 bits),
and 62-bit on 64-bit system.(2)

   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.

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

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

   (2) Internally, unsigned 64-bit integer is supported too, and used
in some cases. But this is not available to Lisp programmers.


File: librep.info,  Node: Numeric Predicates,  Next: Number Read Syntax,  Prev: Types of Numbers,  Up: Numbers

5.4.2 Numeric Predicates
------------------------

Don't use `eq' for equality test of numbers. Instead, use `eql' or
`equal'. See *Note Equality Predicates::.

   For the documentation of the functions `=', `/=', `>', `<', `>=',
`<=', `max' and `min', see *Note 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.


File: librep.info,  Node: Number Read Syntax,  Next: Arithmetic Functions,  Prev: Numeric Predicates,  Up: Numbers

5.4.3 Number Read Syntax
------------------------

The read syntax of any number is: `[PREFIX...][SGN]DATA...', where the
optional SGN is one of the characters `-' or `+', DATA is the
representation of the number, and PREFIX 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. 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 `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.


File: librep.info,  Node: Arithmetic Functions,  Next: Integer Functions,  Prev: Number Read Syntax,  Up: Numbers

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


File: librep.info,  Node: Integer Functions,  Next: Rational Functions,  Prev: Arithmetic Functions,  Up: Numbers

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


File: librep.info,  Node: Rational Functions,  Next: Real Number Functions,  Prev: Integer Functions,  Up: Numbers

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


File: librep.info,  Node: Real Number Functions,  Next: Mathematical Functions,  Prev: Rational Functions,  Up: Numbers

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

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

 -- Function: abs x
     Returns the magnitude of X.

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

   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 `inexact->exact'.

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


File: librep.info,  Node: Mathematical Functions,  Next: Bitwise Functions,  Prev: Real Number Functions,  Up: Numbers

5.4.8 Mathematical Functions
----------------------------

Functions below returns float type number.

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


File: librep.info,  Node: Bitwise Functions,  Next: Random Numbers,  Prev: Mathematical Functions,  Up: Numbers

5.4.9 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


File: librep.info,  Node: Random Numbers,  Next: Characters,  Prev: Bitwise Functions,  Up: Numbers

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


File: librep.info,  Node: Characters,  Prev: Random Numbers,  Up: Numbers

5.4.11 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 *Note Strings::.

     ?a
         => 97

     ?\n
         => 10

     ?\177
         => 127

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

     #\s
         => 115  ; = ?s
     ;; Other than above cases, the first character is read.

   Functions below makes sence for ascii characters only.

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


File: librep.info,  Node: Sequences,  Next: Symbols,  Prev: Numbers,  Up: The language

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

* 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


File: librep.info,  Node: Cons Cells,  Next: Lists,  Up: Sequences

5.5.1 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" (*note
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

   Rep also provides `cXXr', `cXXXr', and `cXXXXr', where each X is
either `a' or `d'. For example, `(cadr z)' is equal to `(car (cdr z))'.

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

 -- Function: setcar cons-cell new-car
 -- Function: setcdr cons-cell new-cdr
     Same as `rplaca' and `rplacd' respectively, but the return value
     is NEW-CAR / NEW-CDR.


File: librep.info,  Node: Lists,  Next: Vectors,  Prev: Cons Cells,  Up: Sequences

5.5.2 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 (*note 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.

* 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


File: librep.info,  Node: List Structure,  Next: Building Lists,  Up: Lists

5.5.2.1 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


File: librep.info,  Node: Building Lists,  Next: Accessing List Elements,  Prev: List Structure,  Up: Lists

5.5.2.2 Building Lists
......................

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,

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

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

     (setq x (bogus-function 'foo))
         => (nil foo)
     (setq y (bogus-function 'bar))
         => (nil bar)               ;The first result has been destroyed
     x
         => (nil bar)               ;See!

   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.

 -- Function: list #!rest elements
     This function creates a list out of its arguments, if zero
     arguments are given the empty list, `()', is returned.

          (list 1 2 3)
              => (1 2 3)

          (list (major-version-number) (minor-version-number))
              => (3 2)

          (list)
              => ()

 -- Function: list* arg1 arg2 ... argn-1 argn
     Creates a new list `(ARG1 ARG2 ... ARGN-1 .  ARGN)'.

          (list* 1 2 '(3 4))
              => (1 2 3 4)

 -- Function: make-list length #!optional initial-value
     This function creates a list LENGTH elements long. If the
     INITIAL-VALUE argument is given it defines the value of all
     elements in the list, if it is not defined they are all `()'.

          (make-list 2)
              => (() ())

          (make-list 3 t)
              => (t t t)

          (make-list 0)
              => ()

 -- Function: append #!rest lists
     This function creates a new list with the elements of each of its
     arguments (which must be lists). Unlike the function `nconc' this
     function preserves the structure of all its arguments.

          (append '(1 2 3) '(4 5))
              => (1 2 3 4 5)

          (append)
              => ()

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

          (setq foo '(1 2))
              => (1 2)
          (setq bar '(3 4))
              => (3 4)
          (setq baz (append foo bar))
              => (1 2 3 4)
          (eq (nthcdr 2 baz) bar)
              => t

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

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

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

 -- Function: remove elt list
     Return a copy of LIST, with all elements the same as ELT discarded
     (using the `equal' function to compare).

 -- Function: remq elt list
     Similar to the `remove' function, except that comparisons are made
     using `eq'.

 -- Function: reverse list
     This function returns a new list; it is made from the elements of
     the list LIST in reverse order. Note that this function does not
     alter its argument.

          (reverse '(1 2 3 4))
              => (4 3 2 1)

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

     (defun not-so-bogus-function (x)
       (list nil x))

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

     (setq x (list 1 2 3))
         => (1 2 3)
     (setq x (cons 0 x))
         => (0 1 2 3)


File: librep.info,  Node: Accessing List Elements,  Next: Modifying Lists,  Prev: Building Lists,  Up: Lists

5.5.2.3 Accessing List Elements
...............................

The most flexible method of accessing an element in a list is via a
combination of the `car' and `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 `car' and `cdr'
operations.

 -- Function: nth count list
     This function returns the element COUNT elements down the list,
     therefore to access the first element use a COUNT of zero (or even
     better the `car' function). If there are too few elements in the
     list and no element number COUNT can be found `()' is returned.

          (nth 3 '(0 1 2 3 4 5))
              => 3

          (nth 0 '(foo bar)
              => foo

 -- Function: nthcdr count list
     This function takes the cdr of the list LIST COUNT times,
     returning the last cdr taken.

          (nthcdr 3 '(0 1 2 3 4 5))
              => (3 4 5)

          (nthcdr 0 '(foo bar))
              => (foo bar)

 -- Function: last list
     This function returns the last element in the list LIST. If the
     list has zero elements `()' is returned.

          (last '(1 2 3))
              => 3

          (last '())
              => ()

 -- Function: member object list
     This function scans through the list LIST until it finds an element
     which is `equal' to OBJECT. The tail of the list (the cons cell
     whose car is the matched object) is then returned. If no elements
     match OBJECT then the empty list `()' is returned.

          (member 'c '(a b c d e))
              => (c d e)

          (member 20 '(1 2))
              => ()

 -- Function: memq object list
     This function is similar to `member' except that comparisons are
     performed by the `eq' function not `equal'.


File: librep.info,  Node: Modifying Lists,  Next: Association Lists,  Prev: Accessing List Elements,  Up: Lists

5.5.2.4 Modifying Lists
.......................

The `nthcdr' function can be used in conjunction with the `rplaca'
function to modify an arbitrary element in a list. For example,

     (rplaca (nthcdr 2 '(0 1 2 3 4 5)) 'foo)
         => foo

sets the third element of the list `(0 1 2 3 4 5)' to the symbol called
`foo'.

   There are also functions which modify the structure of a whole list.
These are called "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.

 -- Function: nconc #!rest lists
     This function is the destructive equivalent of the function
     `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 `append'
     documentation).

          (setq foo '(1 2))
              => (1 2)
          (setq bar '(3 4))
              => (3 4)
          (setq baz (nconc foo bar))
              => (1 2 3 4)
          foo
              => (1 2 3 4)                ;`foo' has been altered!
          (eq (nthcdr 2 baz) bar)
              => t

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

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

 -- Function: nreverse list
     This function rearranges the cons cells constituting the list LIST
     so that the elements are in the reverse order to what they were.

          (setq foo '(1 2 3))
              => (1 2 3)
          (nreverse foo)
              => (3 2 1)
          foo
              => (1)                      ;`foo' wasn't updated when the list
                                          ; was altered.

 -- Function: delete object list
     This function destructively removes all elements of the list LIST
     which are `equal' to OBJECT then returns the modified list.

          (delete 1 '(0 1 0 1 0))
              => (0 0 0)

     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 `delete' function. Otherwise, if the first element of
     the list has to be deleted (because it is `equal' to OBJECT) the
     value of the variable will not change.

          (setq foo '(1 2 3))
              => (1 2 3)
          (delete 1 foo)
              => (2 3)
          foo
              => (1 2 3)
          (setq foo (delete 1 foo))
              => (2 3)

 -- Function: delq object list
     This function is similar to the `delete' function, the only
     difference is that the `eq' function is used to compare OBJECT
     with each of the elements in LIST, instead of the `equal' function
     which is used by `delete'.

 -- Function: sort list #!optional predicate
     Destructively sorts (i.e. by modifying cdrs) the list of values
     LIST, to satisfy the function PREDICATE, returning the sorted
     list. If PREDICATE is undefined, the `<' function is used, sorting
     the list into ascending order.

     PREDICATE is called with two values, it should return true if the
     first is considered less than the second.

          (sort '(5 3 7 4))
              => (3 4 5 7)

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

   See also `delete-if', `delete-if-not', `filter' and so on.  (*note
Mapping Functions::).


File: librep.info,  Node: Association Lists,  Next: Infinite Lists,  Prev: Modifying Lists,  Up: Lists

5.5.2.5 Association Lists
.........................

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

     ((fred . 20)
      (bill . 30))

this alist has two keys, `fred' and `bill' which both associate to an
integer (20 and 30 respectively).

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

     ((fred 20 male)
      (bill 30 male)
      (sue  25 female))

in this alist the symbol `fred' is associated with the list `(20 male)'.

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

 -- Function: assoc key alist
     This function scans the association list ALIST for the first
     element whose car is `equal' to KEY, this element is then
     returned. If no match of KEY is found false is returned.

          (assoc 'two '((one . 1) (two . 2) (three . 3)))
              => (two . 2)

 -- Function: assq key alist
     Similar to the function `assoc' except that the function `eq' is
     used to compare elements instead of `equal'.

     It is not usually wise to use `assq' when the keys of the alist
     may not be symbols--`eq' won't think two objects are equivalent
     unless they are the _same_ object!

          (assq "foo" '(("bar" . 1) ("foo" . 2)))
              => ()
          (assoc "foo" '(("bar" . 1) ("foo" . 2)))
              => ("foo" . 2)

 -- Function: rassoc association alist
     This function searches through ALIST until it finds an element
     whose cdr is `equal' to ASSOCIATION, that element is then returned.
     false will be returned if no elements match.

          (rassoc 2 '((one . 1) (two . 2) (three . 3)))
              => (two . 2)

 -- Function: rassq association alist
     This function is equivalent to `rassoc' except that it uses `eq'
     to make comparisons.

 -- Function: assoc-regexp key-regex alist #!optional fold-case
     Same as `assoc', but it is matched with the regular expression
     KEY-REGEX.


File: librep.info,  Node: Infinite Lists,  Prev: Association Lists,  Up: Lists

5.5.2.6 Infinite Lists
......................

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.

      -----------------------------------
     |                                   |
      --> +-----+-----+   +-----+-----+  |
          |  o  |  o----> |  o  |  o-----
          +--|--+-----+   +--|--+-----+
             |               |
              --> 1           --> 2

   The diagram above represents the infinite list `(1 2 1 2 1 2 ...)'.

   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 _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 (`cons', `car', `cdr', `rplaca', `rplacd'), `nth' and
`nthcdr'.

   Also note that infinite lists can't be printed. But note the
`print-length' and `print-level' variables, see *Note Output
Functions::.


File: librep.info,  Node: Vectors,  Next: Strings,  Prev: Lists,  Up: Sequences

5.5.3 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,

     [zero one two three]

   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.

 -- Function: vectorp object
     This function returns true if its argument, OBJECT, is a vector.

 -- Function: vector #!rest elements
     This function creates a new vector containing the arguments given
     to the function.

          (vector 1 2 3)
              => [1 2 3]

          (vector)
              => []

 -- Function: make-vector size #!optional initial-value
     Returns a new vector, SIZE elements big. If INITIAL-VALUE is
     defined each element of the new vector is set to INITIAL-VALUE,
     otherwise they are all `()'.

          (make-vector 4)
              => [() () () ()]

          (make-vector 2 t)
              => [t t]


File: librep.info,  Node: Strings,  Next: Array Functions,  Prev: Vectors,  Up: Sequences

5.5.4 Strings
-------------

A string is a vector of characters (*note 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 (`^@') 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 *Note 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, `"abc"' is the read syntax of the string
`abc'.

   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 _actual_ character in the string.

   The following escape sequences are supported (all are shown without
their leading backslash `\' character).

`n'
     A newline character.

`r'
     A carriage return character.

`f'
     A form feed character.

`t'
     A TAB character.

`a'
     A `bell' character (this is Ctrl-g).

`\'
     A backslash character.

`^C'
     The `control' code of the character C. This is calculated by
     toggling the seventh bit of the _upper-case_ version of C.

     For example,

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

`012'
     The character whose ASCII value is the octal value `012'. After the
     backslash character the Lisp reader reads up to three octal digits
     and combines them into one character.

`x12'
     The character whose ASCII value is the hexadecimal value `12', i.e.
     an `x' character followed by one or two hex digits.

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

 -- Function: stringp object
     This function returns true if its argument is a string.

 -- Function: make-string length #!optional initial-character
     Creates a new string containing LENGTH characters, each character
     is initialised to INITIAL-CHARACTER (or to spaces if
     INITIAL-CHARACTER is not defined).

          (make-string 3)
              => "   "

          (make-string 2 ?$)
              => "$$"

 -- Function: concat #!rest args
     This function concatenates all of its arguments, ARGS, into a
     single string which is returned. If no arguments are given then
     the null string (`') results.

     Each of the ARGS may be a string, a character or a list or vector
     of characters. Characters are stored in strings modulo 256.

          (concat "foo" "bar")
              => "foobar"

          (concat "a" ?b)
              => "ab"

          (concat "foo" [?b ?a ?r])
              => "foobar"

          (concat)
              => ""

 -- Function: substring string start #!optional end
     This function creates a new string which is a partial copy of the
     string STRING. The first character copied is START characters from
     the beginning of the string. If the 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.

          (substring "xxyfoozwx" 3 6)
              => "foo"

          (substring "xyzfoobar" 3)
              => "foobar"

     For utf-8 encoded strings, use `utf8-substring' instead (*note
     utf-8::).

 -- Function: string= string1 string2
     This function compares the two strings STRING1 and STRING2--if
     they are made from the same characters in the same order then true
     is returned.

          (string= "one" "one")
              => t

          (string= "one" "two")
              => ()

     Note that an alternate way to compare strings (or anything!) is to
     use the `equal' function.

 -- Function: string-equal string1 string2
     Returns true if STRING1 and STRING2 are the same, ignoring
     differences in character case.

 -- Function: string< string1 string2
     This function returns true if STRING1 is `less' than `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 `<' function understands strings so
     `string<' is just a macro calling that function.

          (string< "abc" "abd")
              => t

          (string< "abc" "abb")
              => ()

 -- Function: string-lessp string1 string2
     Similar to `string<' but ignores character case in comparisons.

   See *Note String Functions:: for a few more string manipulating
functions, and *Note Regular Expressions:: for a method of pattern
matching in strings.


File: librep.info,  Node: Array Functions,  Next: Sequence Functions,  Prev: Strings,  Up: Sequences

5.5.5 Array Functions
---------------------

 -- Function: arrayp object
     This function returns true if OBJECT is an array.

 -- Function: aref array position
     Returns the element of the array (vector or string) ARRAY POSITION
     elements from the first element (i.e. the first element is
     numbered zero).  If no element exists at POSITION in ARRAY, false
     is returned.

          (aref [0 1 2 3] 2)
              => 2

          (aref "abcdef" 3)
              => 100                      ;`d'

 -- Function: aset array position value
     This function sets the element of the array ARRAY with an index of
     POSITION (counting from zero) to VALUE. An error is signalled if
     element POSITION does not exist. The result of the function is
     VALUE.

          (setq x [0 1 2 3])
              => [0 1 2 3]
          (aset x 2 'foo)
              => foo
          x
              => [0 1 foo 3]


File: librep.info,  Node: Sequence Functions,  Prev: Array Functions,  Up: Sequences

5.5.6 Sequence Functions
------------------------

 -- Function: sequencep arg
     Returns true if ARG is a sequence, i.e. a list or an array.

 -- Function: length sequence
     This function returns the length (an integer) of the sequence
     SEQUENCE.

          (length "abc")
              => 3

          (length '(1 2 3 4))
              => 4

          (length [x y])
              => 2

     For utf-8 encoded strings, use `utf8-string-length' (*note
     utf-8::).

 -- Function: copy-sequence sequence
     Returns a new copy of the sequence 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.

          (copy-sequence "xy")
              => "xy"

          (setq x '("one" "two"))
              => ("one" "two")
          (setq y (copy-sequence x))
              => ("one" "two")
          (eq x y)
              => ()
          (eq (car x) (car y))
              => t

 -- Function: elt sequence position
     This function returns the element of SEQUENCE POSITION elements
     from the beginning of the sequence.

     This function is a combination of the `nth' and `aref' functions.

          (elt [0 1 2 3] 1)
              => 1

          (elt '(foo bar) 0)
              => foo


File: librep.info,  Node: Symbols,  Next: Evaluation,  Prev: Sequences,  Up: The language

5.6 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 (*note Variables::) and functions (*note
Functions::).

 -- Function: symbolp arg
     This function returns true when its argument is a symbol.

* 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


File: librep.info,  Node: Symbol Syntax,  Next: Symbol Attributes,  Up: Symbols

5.6.1 Symbol Syntax
-------------------

The read syntax of a symbol is usually its name; however, if the name
contains any meta-characters (whitespace or any from `()[]'";|\') 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:

  1. Precede the meta-character by a backslash character (`\'), for
     example:

          xy\(z\)                 ;the symbol whose name is `xy(z)'

  2. Enclose part of the name in vertical bars (two `|' characters).
     All characters after the starting vertical line are copied as-is
     until the closing vertical line is encountered. For example:

          xy|(z)|                 ;the symbol `xy(z)'

   Here are some example read syntaxes.

     setq                    ; `setq'
     |setq|                  ; `setq'
     \s\e\t\q                ; `setq'
     1                       ; the _number_ 1
     \1                      ; the _symbol_ `1'
     |!$%zf78&|              ; `!$%zf78&'
     foo|(bar)|              ; `foo(bar)'
     foo\(bar\)              ; `foo(bar)'


File: librep.info,  Node: Symbol Attributes,  Next: Obarrays,  Prev: Symbol Syntax,  Up: Symbols

5.6.2 Symbol Attributes
-----------------------

All symbols have two basic attributes: print name and property list.
Most important is the "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.

 -- Function: symbol-name symbol
     This function returns the print name of the symbol SYMBOL.

          (symbol-name 'unwind-protect)
              => "unwind-protect"

   The symbol's "property list" (or plist) is similar to an alist
(*note Association Lists::), though stored differently, and provides a
method of storing arbitrary extra values in each symbol. *Note 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 "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 `setq' special form.  *Note
Variables::.


File: librep.info,  Node: Obarrays,  Next: Creating Symbols,  Prev: Symbol Attributes,  Up: Symbols

5.6.3 Obarrays
--------------

An "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 "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 "interning" the symbol, for more details see *Note
Interning::.

 -- Variable: obarray
     This variable contains the obarray that the `read' function uses
     when interning symbols.

 -- Function: make-obarray size
     This function creates a new obarray with SIZE hash buckets (this
     should probably be a prime number for the fewest hash collisions).

     This is the only way of creating an obarray. `make-vector' is _not
     suitable_.

 -- Function: find-symbol symbol-name #!optional obarray
     This function scans the specified obarray (OBARRAY or the value of
     the variable `obarray' if OBARRAY is undefined) for a symbol whose
     name is the string SYMBOL-NAME. The value returned is the symbol
     if it can be found or false otherwise.

          (find-symbol "setq")
              => setq

 -- Function: apropos regexp #!optional predicate obarray
     Returns a list of symbols from the obarray OBARRAY (or the
     default) whose print name matches the regular expression REGEXP
     (*note Regular Expressions::). If PREDICATE is true, each symbol
     which matches REGEXP is applied to the function PREDICATE, if the
     value is true it is considered a match.

     The PREDICATE argument is useful for restricting matches to a
     certain type of symbol, for example only commands.

          (apropos "^yank" 'commandp)
              => (yank-rectangle yank yank-to-mouse)


File: librep.info,  Node: Creating Symbols,  Next: Interning,  Prev: Obarrays,  Up: Symbols

5.6.4 Creating Symbols
----------------------

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

 -- Function: make-symbol print-name
     This function creates and returns a new, uninterned, symbol whose
     print name is the string PRINT-NAME. Its value cell is void
     (undefined) and it will have an empty property list.

     If you're unsure, use `intern' instead. (*note Interning::.)

          (make-symbol "foo")
              => foo

          (eq 'foo (make-symbol "foo"))
              => ()

          (eq 'foo (intern "foo"))
              => t

 -- Function: gensym
     This function returns a new, uninterned, symbol that has a unique
     print name.

          (gensym)
              => G0001

          (gensym)
              => G0002


File: librep.info,  Node: Interning,  Next: Property Lists,  Prev: Creating Symbols,  Up: Symbols

5.6.5 Interning
---------------

"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 `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 `obarray' is
altered).

     (eq 'some-symbol 'some-symbol)
         => t

 -- Function: intern symbol-name #!optional obarray
     This function uses `find-symbol' to search the OBARRAY (or the
     standard obarray) for a symbol called 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.

          (intern "setq")
              => setq

          (intern "my-symbol" my-obarray)
              => my-symbol

 -- Function: intern-symbol symbol #!optional obarray
     Interns the symbol SYMBOL into the obarray OBARRAY (or the
     standard one) then returns the symbol. If SYMBOL is currently
     interned in an obarray an error is signalled.

          (intern-symbol (make-symbol "foo"))
              => foo

          (intern-symbol 'foo)
              error--> Error: Symbol is already interned, foo

 -- Function: unintern symbol #!optional obarray
     This function removes the symbol SYMBOL from the obarray OBARRAY
     then returns the symbol.

     Beware! this function should be used with _extreme_ caution--once
     you unintern a symbol there may be no way to recover it.

          (unintern 'setq)                ;This is extremely stupid
              => setq


File: librep.info,  Node: Property Lists,  Next: Keyword Symbols,  Prev: Interning,  Up: Symbols

5.6.6 Property Lists
--------------------

Each symbol has a property list (or "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
(*note Association Lists::) but there are two main differences:

  1. 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,

          ((one . 1) (two . 2) (three . 3))

     a property list would be,

          (one 1 two 2 three 3)

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

 -- Function: get symbol property
     This function searches the property list of the symbol SYMBOL for
     a property `equal' to PROPERTY. If such a property is found it is
     returned, otherwise false is returned.

          (get 'if 'lisp-indent)
              => 2

          (get 'set 'lisp-indent)
              => ()

 -- Function: put symbol property new-value
     `put' sets the value of the property PROPERTY to NEW-VALUE in the
     property list of the symbol SYMBOL. If there is an existing value
     for this property (using `equal' to compare keys) it is
     overwritten. The value returned is NEW-VALUE.

          (put 'foo 'prop 200)
              => 200

 -- Function: symbol-plist symbol
     Returns the property list of the symbol SYMBOL.

          (symbol-plist 'if)
              => (lisp-indent 2)

 -- Function: setplist symbol plist
     This function sets the property list of the symbol SYMBOL to PLIST.

          (setplist 'foo '(zombie yes))
              => (zombie yes)


File: librep.info,  Node: Keyword Symbols,  Prev: Property Lists,  Up: Symbols

5.6.7 Keyword Symbols
---------------------

Keywords are a special class of symbols. They evaluate to themselves,
and have the read syntax `#:SYMBOL', where SYMBOL is anything
satisfying the usual symbol syntax. These objects are normally used to
mark keyword parameters in function applications (*note Lambda
Expressions::).

 -- Function: make-keyword symbol
     Return the keyword symbol that could be used to mark an argument
     value for the keyword parameter SYMBOL.

          (make-keyword 'x)
              => #:x

 -- Function: keywordp arg
     Returns true if ARG is a keyword symbol.


File: librep.info,  Node: Evaluation,  Next: Variables,  Prev: Symbols,  Up: The language

5.7 Evaluation
==============

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 "Lisp
evaluator" and each expression to be evaluated is called a "form".  The
evaluator (the function `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 "self-evaluating form").

 -- Function: eval form #!optional structure
     This function computes and returns the value of FORM within the
     current module and dynamic environment, and a null lexical
     environment.

     If the optional argument STRUCTURE is non-nil, then FORM is
     evaluated in that structure.

   However, `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.

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

* 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


File: librep.info,  Node: Symbol Forms,  Next: List Forms,  Up: Evaluation

5.7.1 Symbol Forms
------------------

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,

     rep-version
         => "1.0"

this extract from a Lisp session shows the read syntax of a form to get
the value of the variable `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). *Note Variables::.

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


File: librep.info,  Node: List Forms,  Next: Self-Evaluating Forms,  Prev: Symbol Forms,  Up: Evaluation

5.7.2 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


File: librep.info,  Node: Function Call Forms,  Next: Macro Call Forms,  Up: List Forms

5.7.2.1 Function Call Forms
...........................

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 `(/ 100 (1+ 4))'. This is a function
call to the function stored in the variable `/'. First the `/' form is
evaluated, it is a variable containing a data value representing the
primitive subroutine for integer division. Then the `100' form is
evaluated: it is a number, so self-evaluates to the value `100'. Next
the form `(1+ 4)' is evaluated. This is also a function call and
computes to a value of `5' which becomes the second argument to the `/'
function. Now the `/' function is applied to its evaluated arguments of
`100' and `5', and returns the value `20'. This then becomes the value
of the form `(/ 100 (1+ 4))'.

     (/ 100 (1+ 4))
     == (/ 100 5)
     => 20

   Or another example,

     (+ (- 10 (1- 7)) (* (1+ 2) 4)
     == (+ (- 10 6) (* (1+ 2) 4)
     == (+ 4 (* (1+ 2) 4)
     == (+ 4 (* 3 4))
     == (+ 4 12)
     => 16

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

   A "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,
`unwind-protect', `condition-case', `catch', etc...)  are currently
active in the containing function.

   Consider, for example, the following function:

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

the call to `print-list' occurs in the "tail-position" of the function.
This means that the call may be made after removing the previous call
to `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 ]


File: librep.info,  Node: Macro Call Forms,  Next: Special Forms,  Prev: Function Call Forms,  Up: List Forms

5.7.2.2 Macro Call Forms
........................

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 *Note Macros::.


File: librep.info,  Node: Special Forms,  Next: Autoload Forms,  Prev: Macro Call Forms,  Up: List Forms

5.7.2.3 Special Forms
.....................

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 _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: `cond', `defvar',
`progn', `quote', `setq'.

 -- Function: special-form-p arg
     Returns true if ARG is a special form.

          (special-form-p quote)
              => t


File: librep.info,  Node: Autoload Forms,  Prev: Special Forms,  Up: List Forms

5.7.2.4 Autoload Forms
......................

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 *Note Autoloading::.


File: librep.info,  Node: Self-Evaluating Forms,  Next: Quoting,  Prev: List Forms,  Up: Evaluation

5.7.3 Self-Evaluating Forms
---------------------------

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

     "foo"
         => "foo"


File: librep.info,  Node: Quoting,  Prev: Self-Evaluating Forms,  Up: Evaluation

5.7.4 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 "quoting". The special
form `quote' simply returns its argument without evaluating it.  For
example,

     (quote my-symbol)
         => my-symbol

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

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

     'my-symbol
         => my-symbol

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

 -- Special Form: quote form
     This special form returns its single argument without evaluating
     it. This is used to "quote" constant objects to prevent them from
     being evaluated.

   For another form of quoting, see *Note Backquoting::.


File: librep.info,  Node: Variables,  Next: Functions,  Prev: Evaluation,  Up: The language

5.8 Variables
=============

In Lisp, symbols are used to represent variables. Each symbol contains
a "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 `symbol-value' function can be used to
evaluate variables whose names not known statically.

 -- Function: symbol-value variable
     This function returns the value of the symbol VARIABLE in the
     current environment.

* 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


File: librep.info,  Node: Local Variables,  Next: Setting Variables,  Up: Variables

5.8.1 Local Variables
---------------------

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

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

   One way of visualising variable binding is to think of each variable
as a stack. When the variable is bound to, a new value is pushed onto
the stack, when it is unbound the top of the stack is popped. Similarly
when the stack is empty the value of the variable is void (*note Void
Variables::). Assigning a value to the variable (*note 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 *Note Fluid Variables::.

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

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

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

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

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

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

          (bar)
             => outer
          ;; The let binding is newly established inside of bar,
          ;; and foo doesn't see it.

          ;; Difference to defvar.
          (defvar a 'outer)
          (bar)
             => inner ;; The scope of a is now dynamic.

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

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

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

     The second form, `(let function bindings body...)', can be used to
     make a loop. (*note Looping Structures::)

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

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

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

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

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

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

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

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


File: librep.info,  Node: Setting Variables,  Next: Scope and Extent,  Prev: Local Variables,  Up: Variables

5.8.2 Setting Variables
-----------------------

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

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

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

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

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

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

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

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

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


File: librep.info,  Node: Scope and Extent,  Next: Void Variables,  Prev: Setting Variables,  Up: Variables

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

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

   Consider the following example:

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

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

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

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

     (defvar *foo-var* nil)

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

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

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

 -- Function: special-variable-p symbol
     Returns t if SYMBOL is a special variable (dynamically scoped).


File: librep.info,  Node: Void Variables,  Next: Defining Variables,  Prev: Scope and Extent,  Up: Variables

5.8.4 Void Variables
--------------------

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

 -- Function: boundp symbol
     Returns true if SYMBOL is bound to a variable.

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

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


File: librep.info,  Node: Defining Variables,  Next: Fluid Variables,  Prev: Void Variables,  Up: Variables

5.8.5 Defining Variables
------------------------

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

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

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

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

     If the DOC-STRING argument is defined it is a string documenting
     VARIABLE (*note Docstrings::).

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

     Don't use `defvar' if `define' suffices. For the reason, see *Note
     Modules and Special Variables::.

 -- Macro: defvar-setq var #!optional value doc
     It's `defvar' + `setq', so defines VAR as a special variable, and
     sets the value to VALUE.

 -- Macro: define-special-variable var #!optional value doc
     Same as `defvar-setq' above. A very confusing name, so it's
     deprecated now.

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

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

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


File: librep.info,  Node: Fluid Variables,  Prev: Defining Variables,  Up: Variables

5.8.6 Fluid Variables
---------------------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     (bar)
        => outer
     ;; The let binding is newly established inside of bar,
     ;; and foo doesn't see it.


File: librep.info,  Node: Functions,  Next: Macros,  Prev: Variables,  Up: The language

5.9 Functions
=============

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

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

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

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

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

          (functionp set)
              => t

          (functionp setq)
              => ()

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

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

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

* 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


File: librep.info,  Node: Lambda Expressions,  Next: Closures,  Up: Functions

5.9.1 Lambda Expressions
------------------------

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

   The general format of a lambda expression is:

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

Where LAMBDA-LIST is a list defining the formal parameters of the
function, DOC is an optional documentation string (*note Docstrings::),
and BODY-FORMS is the sequence of forms making up the function body,
evaluated using an implicit `progn'.

   INTERACTIVE-DECLARATION is an obsolete feature, only required by
interactive commands(1).

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

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

this evaluates to an anonymous function with two parameters, `x' and
`y', which when called evaluates to their sum. More on evaluation is
described in the next section, *Note Closures::.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

          (lambda (x . y) ...)

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

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

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

   (1) Only used when Librep is embedded within another application.

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


File: librep.info,  Node: Closures,  Next: Defining Named Functions,  Prev: Lambda Expressions,  Up: Functions

5.9.2 Closures
--------------

A lambda expression itself is _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:

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

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

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

   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 `define' in a closure which is not top-level
creates a binding in the closure's module, NOT inside of the closure.

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

     (count-0)
         => 1
     (count-0)
         => 1
     ;; Each time `define' resets the value to 0.

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

     (count)
         => 1
     (count)
         => 2 ;; Ok, but
     val
         => 2 ;; Not invisible.

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

 -- Function: closure-name fun
     Returns the name of closure FUN, a string. Or if it's unnamed,
     `nil'.

 -- Function: closure-structure fun
     Returns the structure FUN belongs to.

 -- Function: set-closure-structure closure structure
     Sets the structure CLOSURE belongs to to STRUCTURE.

   It is often useful to pass a function _definition_ to other
functions, instead of function's name, especially for example to `mapc'
or `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 LIST which are
even and greater than 20.

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

   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 (*note Backquoting::). In these cases
the `make-closure' function may be used to create a function object
from a lambda expression.

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

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

 -- Function: set-closure-function closure function
     Sets the function value of CLOSURE to `function'.

     (define (foo) 'foo-sym)
     (define (bar) 'bar-sym)
     (set-closure-function foo (closure-function bar))
     (foo)
         => foo-sym


File: librep.info,  Node: Defining Named Functions,  Next: Predicate Functions,  Prev: Closures,  Up: Functions

5.9.3 Defining Named Functions
------------------------------

Functions can be defined by the `defun' special form. However `define'
is the more preferred way. (*note Definitions::.)

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

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

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

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


File: librep.info,  Node: Predicate Functions,  Next: Local Functions,  Prev: Defining Named Functions,  Up: Functions

5.9.4 Predicate Functions
-------------------------

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

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

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


File: librep.info,  Node: Local Functions,  Next: Calling Functions,  Prev: Predicate Functions,  Up: Functions

5.9.5 Local Functions
---------------------

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

   For example,

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


File: librep.info,  Node: Calling Functions,  Next: Mapping Functions,  Prev: Local Functions,  Up: Functions

5.9.6 Calling Functions
-----------------------

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

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

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

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

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


File: librep.info,  Node: Mapping Functions,  Prev: Calling Functions,  Up: Functions

5.9.7 Mapping Functions
-----------------------

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

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

     The FUNCTION must accept a single argument value.

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

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

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

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

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

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

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

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

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

 -- Function: remove-if pred list
 -- Function: remove-if-not pred list
     Same as `delete-if' / `delete-if-not' respectively, but returns a
     new copy, instead of destructively. Defined in `rep.data'.

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

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

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


File: librep.info,  Node: Macros,  Next: Definitions,  Prev: Functions,  Up: The language

5.10 Macros
===========

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

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

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

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

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

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


File: librep.info,  Node: Defining Macros,  Next: Backquoting,  Up: Macros

5.10.1 Defining Macros
----------------------

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

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

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

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

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

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

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


File: librep.info,  Node: Backquoting,  Next: Macro Expansion,  Prev: Defining Macros,  Up: Macros

5.10.2 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 (*note Quoting::), here another form of quoting is
described, where only some of the quoted object is actually constant.
This is known as "backquoting", since it is introduced by the backquote
character ``', a shortcut for the `backquote' macro.

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

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

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

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

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

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

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


File: librep.info,  Node: Macro Expansion,  Next: Compiling Macros,  Prev: Backquoting,  Up: Macros

5.10.3 Macro Expansion
----------------------

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

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

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

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

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

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

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

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

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


File: librep.info,  Node: Compiling Macros,  Prev: Macro Expansion,  Up: Macros

5.10.4 Compiling Macros
-----------------------

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

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

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

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

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

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


File: librep.info,  Node: Definitions,  Next: Modules,  Prev: Macros,  Up: The language

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

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

   The `define' originates in Scheme.

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

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

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

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

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

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

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

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

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

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

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

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

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


File: librep.info,  Node: Modules,  Next: Control Structures,  Prev: Definitions,  Up: The language

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

   Some functions are not yet covered. For them, obtain the source, and
read `src/structures.c'.


File: librep.info,  Node: Informal Module Introduction,  Next: Introduction on Modules,  Up: Modules

5.12.1 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 `require':
     (require 'rep.util.time) ;; Module name is a symbol

   Looks like Elips, but forget it; Elisp doesn't have the module
system.  There's no `provide' in modules.

   In fact, two things are done by `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 `user' module. Also the module which the REPL
of `sawfish-client' and Sawfish's `~/.sawfish/rc' dwell is called
`user'.

   When you want to use, say `rep.util.time' from another module, then
you have to call `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
`require' any. (In fact, `rep' module is necessary, but you can forget
it now.)

   If you look at `/usr/share/rep/x.y.z/lisp/rep/util/time.jl', then it
exports for example `seconds->time'. Now you can call it.

     (seconds->time (* 3600 72))
       => (3 . 0) ;; Cons of days and the rest in seconds.

   The 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 `open'
clause, you declare which modules you import to that module. `require'
is a usual function, but `open' is only used in the definition of a
module. `time' module opens only one module, `rep'.

   In a module definition, first comes `define-structure' ("structure"
is a synonym for "module"), then `export', and `open'. After them come
usual expressions, and they're evaluated in that module. You can put
there anything, not limited to `define's.

Module name and file name
.........................

How does a module name corresponds to a file name? When loading,
modules are searched from `load-path'. If you're using Sawfish in a
Unix, its first element is `~/.sawfish/lisp', the second
`/usr/share/sawfish/<version>/lisp', and so on.

   Now assume `load-path' is `(a b)'. When you require the module
`foo.bar', then `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, `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.


File: librep.info,  Node: Introduction on Modules,  Next: Simple Module Definition,  Prev: Informal Module Introduction,  Up: Modules

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


File: librep.info,  Node: Simple Module Definition,  Next: Module and File,  Prev: Introduction on Modules,  Up: Modules

5.12.3 Simple Module Definition
-------------------------------

In its simplest form, a module definition looks like this:

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

   This module has the name `simple.test'.  Then it "exports" two
bindings, `foo' and `bar', functions in this case. It also declare to
use modules `rep' and `rep.structures'. The entire order is fixed;
first `export', then `open', and the rest.

   Always make it rule to open `rep' structure. It's because Librep
used to offer alternative Lisps, for example Scheme mimicry by
importing `scheme' structure, instead of `rep' module.

   Then comes the body. They're evaluated when `define-structure' is
evaluated, _inside_ of this module. It defines three functions, and it
emits a message to stderr. The third function `baz' is not exported, so
it can't be seen outside of this module.

   The function `current-structure' is defined in `rep.structures', and
it can be used in this module because `rep.structures' was opened.


File: librep.info,  Node: Module and File,  Next: Using Other Modules,  Prev: Simple Module Definition,  Up: Modules

5.12.4 Module and File
----------------------

A module can be defined anywhere, in any lisp expression, but usually
it only makes sense if the module `foo.bar.baz' is defined in a file
like `<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 `load-path'.
Files can be byte-compiled, and usually they have a suffix `.jlc',
instead of `.jl' for plain Lisp source.

   The variable `load-path' and suffixes are fully described in *Note
Load Function::.


File: librep.info,  Node: Using Other Modules,  Next: Modules and Special Variables,  Prev: Module and File,  Up: Modules

5.12.5 Using Other Modules
--------------------------

We've already seen one way to use other module in the previous
subsection. It was `open'.

   There're three aspects in module access:
   * Loading of a module to Rep,

   * How are that module's bindings are referred to from the current
     module,

   * And doing these things on the fly, as usual lisp expressions, not
     only in module definitions.

   We'll see these three in turn.

   Function `load' loads any file, not only module definitions, and
evaluate each form in it, but `load' does NOT import bindings. For the
full doc, see *Note Load Function::.

   We've seen `open' clause. If specified modules are not yet loaded
into Rep, then they're loaded. It also imports exported bindings.

   The alternative, `access' is available, too. With `access', exported
bindings can be referred to by specifying the module it belongs to:

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

   One of `open' or `access' clauses can only be used at the module
definition, but there're equivalent lisp functions.  `require' and
`open-structures' correspond to `open', and `access-structures' to
`access':

 -- Function: require module
 -- Function: open-structures list
 -- Function: access-structures list
     Example:
          (require 'foo.bar)
          (open-structures '(foo.bar baz))
          (access-structures '(foo.bar baz))

     All loads modules to Rep if not yet, and import the bindings of
     specified modules, in the same way as `open' or `access'.  The
     latter two are defined in `rep.structures'.

     If the load fails, an error is signaled.


File: librep.info,  Node: Modules and Special Variables,  Next: Module Functions,  Prev: Using Other Modules,  Up: Modules

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

As described earlier, `defvar' creates dynamically scoped variables, or
special variables. (*note 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.  *Note Fluid Variables::.


File: librep.info,  Node: Module Functions,  Next: Implicit Exports,  Prev: Modules and Special Variables,  Up: Modules

5.12.7 Module Functions
-----------------------

In this section basic module functions are explained. All are defined
in `rep.structures'. Functions related to contruction of modules are
described in following sections.

 -- Function: structurep str
     Returns `t' if STR is a Lisp structure object.

 -- Function: current-structure
     Returns the current structure.

   Evaluation of a lisp expression can be done in any module you
specify, not only in the current module, with the function `eval'.
(*note Evaluation::.)

   Structure's name is a symbol.

 -- Function: structure-name str
     Returns the name of a structure `str'.

 -- Function: get-structure name
     Returns the structure called NAME, or `nil' if no such structure
     exists.

 -- Function: intern-structure name
     Returns the structure called NAME, or if one doesn't exist,
     attempts to load it.

     This is a kind of mixture of `require' and `load'; the grammar is
     that of `require', but it doesn't import any.

   These functions are related to opening other modules.

 -- Function: structure-imports str
 -- Function: structure-accessible str
     Returns the list of modules `str' has opened or accesses.

   There's a function for bindings.

 -- Function: structure-exports-p str sym
     Returns non-nil if the structure STRUCTURE exports a binding of
     the symbol SYM. More specifically, it returns the symbol `local'
     if STRUCTURE defines it, and returns the symbol `external' if it
     exports but does not define it.

   Functions `open-structures' and `access-structures' are explained in
*Note Using Other Modules::.


File: librep.info,  Node: Implicit Exports,  Next: Module Definition,  Prev: Module Functions,  Up: Modules

5.12.8 Implicit Exports
-----------------------

If you inspect the Librep source, you may find for example, the
function `caar' is defined in `rep.data' module, but you can call it
without importing.

   It's because `rep' module exports some functions on behalf of their
modules. To name all, they are: `rep.data', `rep.io.streams',
`rep.lang.debug', `rep.lang.interpreter', `rep.lang.math',
`rep.lang.symbols', `rep.module-system', and `rep.vm.interpreter'.

   The interactive environment pulls in a bit more. (*Note Interactive
environment::.)


File: librep.info,  Node: Module Definition,  Next: Module Interfaces,  Prev: Implicit Exports,  Up: Modules

5.12.9 Module Definition
------------------------

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 `open' or `access' clause.

 -- Macro: define-structure name interface config body...
 -- Macro: structure interface config body...
     These special forms each create a new module with interface
     INTERFACE and configuration CONFIG. The full syntax of an
     interface is described in the next section. `structure' defines an
     anonymous structure.

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

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

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

     Each NAME specifies the name of a module.

   Always make it rule to open `rep' structure. It's because Librep
used to offer Scheme mimicry by importing `scheme' structure.

   As described in the section `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 `test'
that exports two functions `foo' and `bar'.

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

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

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

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

     Here is a trivial example:

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

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


File: librep.info,  Node: Module Interfaces,  Next: Obsolete Aspects of Modules,  Prev: Module Definition,  Up: Modules

5.12.10 Module 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:

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

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

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

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

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

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

 -- Function: structure-interface str
     returns the interface of structure object STR.

 -- Function: set-interface str int
     Set the interface of structure object STR to INT.


File: librep.info,  Node: Obsolete Aspects of Modules,  Prev: Module Interfaces,  Up: Modules

5.12.11 Obsolete Aspects of Modules
-----------------------------------

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
`feature's. Function `require' imports a module only when its feature
is absent.

 -- Variable: features
     A list of the features, i.e. module names marked as imported into
     the current module. Each is a symbol.

 -- Function: featurep feature
     Returns true if the feature FEATURE has been loaded into the
     current module.

 -- Function: provide feature
     Don't use this function unless you're sure. Usually you don't need
     it.

     This function adds 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.


File: librep.info,  Node: Control Structures,  Next: Threads,  Prev: Modules,  Up: The language

5.13 Control Structures
=======================

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

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

* 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


File: librep.info,  Node: Sequencing Structures,  Next: Conditional Structures,  Up: Control Structures

5.13.1 Sequencing Structures
----------------------------

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 `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
"implicit progn", this means that internally they call `progn' with a
list of forms.

   `progn' in Lisp is nearly analogous to a `begin...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 `if' structure).

 -- Special Form: progn forms...
     All of the FORMS are evaluated sequentially (from left-to-right),
     the result of the last evaluated FORM is the return value of the
     special form. If no arguments are given to `progn' it returns
     false.

          (progn 'one (+ 1 1) "three")
              => "three"

          (progn)
              => ()

 -- Macro: prog1 first forms...
     This special form evaluates its FIRST form then performs an
     implicit progn on the rest of its arguments. The result of this
     structure is the computed value of the FIRST form.

          (prog1 'one (+ 1 1) "three")
              => one

 -- Macro: prog2 first second forms...
     This is similar to `prog1' except that the evaluation of its
     SECOND form is returned.

     The FIRST form is evaluated, then its SECOND, then it performs an
     implicit progn on the remaining arguments.

          (prog2 'one (+ 1 1) "three")
              => 2


File: librep.info,  Node: Conditional Structures,  Next: Looping Structures,  Prev: Sequencing Structures,  Up: Control Structures

5.13.2 Conditional Structures
-----------------------------

Lisp provides a number of conditional constructs, the most complex of
which (`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.

 -- Macro: if condition true-form else-forms...
     The `if' form is the nearest thing in Lisp to the "if-then-else"
     construct found in most programming languages.

     First the CONDITION form is evaluated, if it returns true the
     TRUE-FORM is evaluated and its result returned. Otherwise the
     result of an implicit progn on the ELSE-FORMS is returned. If
     there are no ELSE-FORMS false is returned.

     Note that one of the TRUE-FORM or the ELSE-FORMS is completely
     ignored--it is not evaluated.

          (if (special-form-p if)
              "`if' is a special form"
            "`if' is not a special form")
              => "`if' is not a special form"

 -- Macro: when condition true-forms...
     CONDITION is evaluated, if it is true the result of an implicit
     progn on the TRUE-FORMS is returned, otherwise false is returned.

          (when t
            (message "Pointless")
            'foo)
              => foo

 -- Macro: unless condition else-forms...
     This special form evaluates CONDITION, if its computed value is
     true, `()' is returned. Otherwise the ELSE-FORMS are evaluated
     sequentially, the value of the last is returned.

 -- Special Form: cond clause...
     The `cond' special form is used to choose between an arbitrary
     number of conditions. Each CLAUSE is a list; the car of which is a
     CONDITION, the cdr is a list of forms to evaluate (in an implicit
     `progn') if the CONDITION evaluates to true.  This means that each
     CLAUSE looks something like:

          (CONDITION BODY-FORMS...)

     and a whole `cond' form looks like:

          (cond
           (CONDITION-1 BODY-FORMS-1...)
           (CONDITION-2 BODY-FORMS-2...)
           ...)

     The CONDITION in each CLAUSE is evaluated in sequence
     (CONDITION-1, then CONDITION-2, ...), the first one which
     evaluates to a true value has an implicit `progn' performed on its
     BODY-FORMS. The value of this `progn' is also the value of the
     `cond' statement.

     If the true CONDITION has no BODY-FORMS the value returned is the
     value of the CONDITION. If none of the clauses has a true
     CONDITION the value of the `cond' statement is false.

     Often you want a "default" clause which has its BODY-FORMS
     evaluated when none of the other clauses are true. The way to do
     this is to add a clause with a CONDITION of `t' and BODY-FORMS of
     whatever you want the default action to be.

          (cond
           ((stringp buffer-list))        ;Clause with no BODY-FORMS
           ((consp buffer-list)
            (setq x buffer-list)          ;Two BODY-FORMS
            t)
           (t                             ;Default clause
            (error "`buffer-list' is corrupted!")))
              => t

 -- Macro: case key clauses...
     This special form is similar to `cond', but switches on the result
     of evaluating a single form KEY, checking for equality with a
     number of other values, defined by the CLAUSES. If any of these
     other values is the same as the result of evaluating KEY, then a
     sequence of forms associated with the value is evaluated.

     Each element of the CLAUSES list has the format:

          ((VALUE-1 VALUE-2 ... VALUE-N) FORMS...)

     Each of the values in the car of the clause is tested for equality
     with KEY, using the `eql' function. If any test positively, then
     the associated 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 `t'. If such a clause is
     encountered, and no other clauses have matched the value of KEY,
     then this clause is assumed to match by default.

     If any of the values in the CLAUSES appear multiply, then the
     behaviour of the construct is undefined.

     Here is an example use of `case':

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

   There are also a number of special forms which combine conditions
together by the normal logical rules.

 -- Macro: or forms...
     The first of the FORMS is evaluated, if it is true its value is
     the value of the `or' form and no more of `forms' are evaluated.
     Otherwise this step is repeated for the next member of FORMS.

     If all of the FORMS have been evaluated and none have a true value
     the `or' form evaluates to false.

          (or nil 1 nil (beep))           ;`(beep)' won't be evaluated
              => 1

 -- Macro: and forms...
     The first of the FORMS is evaluated. If it is false no more of the
     FORMS are evaluated and false is the value of the `and' statement.
     Otherwise the next member of FORMS is evaluated and its value
     tested. If none of the FORMS are false the computed value of the
     last member of FORMS is returned from the `and' form.

          (and 1 2 nil (beep))            ;`(beep)' won't be evaluated
              => ()

          (and 1 2 3)                     ;All forms are evaluated
              => 3

 -- Function: not object
     This function inverts the truth value of its argument. If OBJECT
     is true, false is returned, otherwise true is returned.

          (not nil)
              => t

          (not t)
              => ()

          (not (not 42))
              => t


File: librep.info,  Node: Looping Structures,  Next: Non-Local Exits,  Prev: Conditional Structures,  Up: Control Structures

5.13.3 Looping Structures
-------------------------

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 `while' statement:

     (while CONDITION BODY...)
     ==
     (letrec ((loop (lambda ()
                      (when CONDITION
                        BODY
                        (loop)))))
       (loop))

Each successive iteration of the loop is simply another call to the
function. Also note that the recursive call to the `(loop)' function
occurs in the tail-position of the function. When combined with the
system's ability to eliminate tail-calls (*note 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.

 -- Macro: do vars (test expr...) body...
     `do' is an iteration construct; VARS specifies a set of variable
     bindings to be created, how they are initialized and how they are
     updated on each iteration. TEST specifies the termination
     condition of the loop, any EXPR... forms are evaluated immediately
     prior to exiting the `do' construct. The BODY...  forms specify
     the side effecting body of the loop.

     VARS is a list of variable clauses, each of which has the
     structure `(VARIABLE INIT STEP)' where VARIABLE is the name of a
     variable, INIT defines the initial value of its binding, and STEP
     defines how the next value of the binding is computed. An
     alternative form is `(VARIABLE INIT)', in this case the value of
     the binding does not change across loop iterations.

     Each iteration begins by evaluating TEST, if the result is false,
     then the BODY... expressions are evaluated, and the variables
     bound to new locations initialized to the results of evaluating
     the associated STEP forms.

     If the result of evaluating TEST is true then the EXPR... forms
     are evaluated, and the `do' construct returns the value of the
     last EXPR form evaluated.

          (do ((vec (make-vector 5))
               (i 0 (1+ i)))
              ((= i 5) vec)
            (aset vec i i))

              => [0 1 2 3 4]

   The "named-let" variant of the `let' form also provides a convenient
looping construct.

 -- Macro: let function bindings body...
     This is the same as the `(let BINDINGS BODY...)' form described in
     *Note Local Variables::, but within the BODY... forms, the symbol
     FUCTION is bound to a function whose parameters are the bound
     variables defined by BINDINGS and whose body is the sequence of
     forms BODY...

     This means that the body of the `let' may be repeated by invoking
     the function VARIABLE with suitable parameters.

          (let loop ((rest '(1 2 3))
                     (total 0))
            (if (null rest)
                total
              (loop (cdr rest) (+ total (car rest)))))

              => 6

   Finally, the imperative `while' form shown at the start of the
section is also provided:

 -- Macro: while condition body...
     The CONDITION form is evaluated. If it is true an implicit progn
     is performed on the BODY forms and the whole procedure is repeated.

     This continues until the CONDITION form evaluates to false.  The
     value of every `while' structure that terminates is false.


File: librep.info,  Node: Non-Local Exits,  Next: Continuations,  Prev: Looping Structures,  Up: Control Structures

5.13.4 Non-Local Exits
----------------------

A "non-local exit" is a transfer of control from the current point of
evaluation to a different point (somewhat similar to the much-maligned
`goto' statement in imperative languages).

   Non-local exits can either be used explicitly (`catch' and `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


File: librep.info,  Node: Catch and Throw,  Next: Function Exits,  Up: Non-Local Exits

5.13.4.1 Catch and Throw
........................

The `catch' and `throw' structures are used to perform explicit
transfers of control. First a `catch' form is used to setup a "tag";
this acts like a label for a `goto' statement.  To transfer control a
`throw' form is then used to transfer to the named tag. The tag is
destroyed and the `catch' form exits with the value provided by the
`throw'.

   In a program this looks like,

     (catch 'TAG
       ;; Forms which may `throw' back to TAG
       ...
       (throw 'TAG VALUE)
       ;; Control has now passed to the `catch',
       ;; no more forms in this progn will be evaluated.
       ...)
         => VALUE

where TAG is the tag to be used (this is normally a symbol) and VALUE
is the result of the `catch' form.

   When a throw actually happens all catches in scope are searched for
one with a tag which is `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...) and all Lisp constructs between the current point of control
and the catch are immediately exited.

   For example,

     (let
         ((test 'outer))
       (cons (catch 'foo
               (let
                   ((test 'inner))
                 (throw 'foo test)
                 (setq test 'unreachable)))  ;Never reached
             test))
         => (inner . outer)

when the throw executes the second binding of `test' is unwound and the
first binding comes back into effect. For more details on variable
binding see *Note Local Variables::.

   Note that catch tags are _dynamically_ scoped, the thrower does not
have to be within the same lexical scope (this means that you can
`throw' through functions).

 -- Macro: catch tag body-forms...
     This special form defines a catch tag which will be accessible
     while the BODY-FORMS are evaluated.

     TAG is evaluated and recorded as the tag for this catch. Next the
     BODY-FORMS are evaluated as an implicit `progn'. The value of the
     `catch' form is either the value of the `progn', or, if a `throw'
     happened, the value specified in the THROW form.

     Before exiting, the tag installed by this form is removed.

 -- Function: throw tag #!optional catch-value
     This function transfers the point of control to the catch form
     with a tag which is `eq' to TAG. The value returned by this catch
     form is either CATCH-VALUE or false if CATCH-VALUE is undefined.

     If there is no catch with a tag of TAG an error is signalled and
     the interpreter returns to the top-level of evaluation.

   There are a number of pre-defined throw tags:

`quit'
     Terminate the Librep interpreter, returning the value of the throw
     (if a number).

`exit'
     Exit the innermost event loop, unless currently in the outermost
     event loop, when control just passes back to the event loop.

`user-interrupt'
     As if a `SIGINT' or `C-c' signal has been received. Control passes
     back to the top-level event loop.

`term-interrupt'
     Triggered when a `SIGTERM' or `SIGHUP' signal is received.  Tries
     to clean up any existing state, then terminates the interpreter.

   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.


File: librep.info,  Node: Function Exits,  Next: Cleanup Forms,  Prev: Catch and Throw,  Up: Non-Local Exits

5.13.4.2 Function Exits
.......................

Librep has no explicit `return' statement, as found in most other
languages. Where a value has to returned from a function before the
function would normally exit, a `catch'/`throw' pair may be used.

   For example:

     (defun foo (x y)
       (catch 'return
          (when (= x 2)
            (throw 'return nil))
          ...


File: librep.info,  Node: Cleanup Forms,  Next: Errors,  Prev: Function Exits,  Up: Non-Local Exits

5.13.4.3 Cleanup Forms
......................

It is sometimes necessary ensure that a certain form is _always_
evaluated, even when a non-local exit would normally bypass that form.
The `unwind-protect' special form is used in this case.

 -- Macro: unwind-protect body-form cleanup-forms...
     The BODY-FORM is evaluated, if it exits normally the CLEANUP-FORMS
     are evaluated sequentially then the value which the BODY-FORM
     returned becomes the value of the `unwind-protect' form. If the
     BODY-FORM exits abnormally though (i.e. a non-local exit happened)
     the CLEANUP-FORMS are evaluated anyway and the non-local exit
     continues.

   One use of this is to ensure that an opened file is always closed,
for example,

     (catch 'foo
       (unwind-protect
           (let
               ((temporary-file (open-file (make-temp-name) 'write)))
             ;; Use `temporary-file'
             (write temporary-file "A test\n")
             ;; Now force a non-local exit
             (throw 'foo))
         ;; This is the CLEANUP-FORM it will _always_
         ;; be evaluated, despite the `throw'.
         (close temporary-file)))
         => ()


File: librep.info,  Node: Errors,  Prev: Cleanup Forms,  Up: Non-Local Exits

5.13.4.4 Errors
...............

Errors are a type of non-local exit; when a form can not be evaluated
for some reason an error is normally "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.

 -- Function: signal error-symbol data
     Signals that an error has happened. ERROR-SYMBOL is a symbol
     classifying the type of error, it should have a property
     `error-message' (a string) which is the error message to be
     printed.

     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.

          (signal 'void-value '(some-symbol))
              error--> Value as variable is void: some-symbol

 -- Function: error template #!rest values
     Same as `(signal 'error STRING)', where STRING is a string
     formatted by TEMPLATE and VALUES. (*note Formatted Output::)

 -- Variable: 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 `t', then the debugger starts if the control is not inside
     of any `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 `always', then the debugger is entered always,
     i.e. even if it is inside of a `condition-case'. If it's a list of
     errer-symbols, for example `(void-value bad-arg)', then only when
     the error matches one of them, the debugger is called even inside
     of a `condition-case'.

          (setq backtrace-on-error t) ;; Ordinary usage.
          (setq backtrace-on-error '(void-value bad-arg)) ;; Catch them only

 -- Variable: backtrace-on-error
     Similar to `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.

   When you expect an error to occur and need to be able to regain
control afterwards the `condition-case' special form may be used.

 -- Macro: condition-case symbol body-form error-handlers...
     `condition-case' evaluates the BODY-FORM with the ERROR-HANDLERS
     in place. If an error occurs and one of the handles matches the
     error, then it is evaluated with the value of SYMBOL set to the
     error information.

     Each of the 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 `progn' if the
     handler is invoked.

     While the forms of the error handler are being evaluated the
     variable SYMBOL is bound to the value `(ERROR-SYMBOL .  DATA)'
     (these were the arguments to the `signal' form which caused the
     error). If SYMBOL is the symbol `nil' (or the empty list `()'),
     then the error information is not available to the handler.

     The special value, the symbol `error', in the car of one of the
     ERROR-HANDLERS will catch _all_ types of errors.

          (condition-case data
              (signal 'file-error '("File not found" "/tmp/foo"))
            (file-error
             data)
            (error
             (setq x z)))         ;Default handler
              => (file-error "File not found" "/tmp/foo")


File: librep.info,  Node: Continuations,  Prev: Non-Local Exits,  Up: Control Structures

5.14 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
"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
`call-with-current-continuation' function (often shortened to
`call/cc') that is standard in Scheme.

 -- Function: call/cc function
     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 FUNCTION exits).

     The continuation object passed to FUNCTION is itself a function
     accepting a single argument, when called it transfers control to
     the continuation of FUNCTION, as if FUNCTION had returned the
     argument applied to the continuation object.

 -- Function: call-with-current-continuation function
     This is an alias for `call/cc'.

   In its simplest form, `call/cc' can mimic the `catch' and `throw'
procedures (*note Catch and Throw::), for example:

     (defun foo (bar)
       (call/cc (lambda (esc)
                  (when (null bar)
                    ;; throws out of the call/cc
                    (esc nil))
                  ;; do something with bar
                  ...

this is roughly equivalent to:

     (defun foo (bar)
       (catch 'tag
         (when (null bar)
           (throw 'tag nil))
         ;; do something with bar
         ...

   This is only half the story--the most powerful feature of `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:

     (prog1 (call/cc (lambda (esc)
                       (setq cont esc)))
       (message "foo!"))
         -| foo!
         => #<closure>

     cont
         => #<closure>

     (cont 10)
         -| foo!
         => 10

The continuation of the `prog1' form is saved into the variable `cont'.
When subsequently called with a single argument, it has exactly the
same effect as the first time that the second form in the `prog1'
construct was evaluated.

5.14.1 Implementation Notes
---------------------------

`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 `unwind-protect',
`condition-case' or `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 (*note Threads::).


File: librep.info,  Node: Threads,  Next: Loading,  Prev: Control Structures,  Up: The language

5.15 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 `rep.threads' module.

* Menu:

* Thread Contexts::
* Creating Threads::
* Deleting Threads::
* Manipulating Threads::
* Mutexes::
* Thread Implementation Notes::


File: librep.info,  Node: Thread Contexts,  Next: Creating Threads,  Up: Threads

5.15.1 Thread Contexts
----------------------

Every thread created by Rep is a member of a "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.

 -- Function: call-with-dynamic-root thunk
     Call the function of zero-parameters THUNK in a new thread
     context. The new context will contain a single thread, that
     executing THUNK.

     The call to `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.


File: librep.info,  Node: Creating Threads,  Next: Deleting Threads,  Prev: Thread Contexts,  Up: Threads

5.15.2 Creating Threads
-----------------------

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

 -- Function: threadp arg
     Return true if lisp object ARG represents a thread of execution in
     the lisp environment.

 -- Function: make-thread thunk #!optional name
     Create and return a new thread of execution; it will initially
     invoke the zero-parameter function THUNK. If the call to THUNK
     returns the thread is automatically deleted.

     If NAME is defined, it is a string naming the current thread.

 -- Function: make-suspended-thread #!optional name
     Similar to `make-thread', except that the newly created thread
     will be immediately suspended from running.

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

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


File: librep.info,  Node: Deleting Threads,  Next: Manipulating Threads,  Prev: Creating Threads,  Up: Threads

5.15.3 Deleting Threads
-----------------------

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 `call-with-dynamic-root' function may be deleted by
exiting from the function called in the new context.

 -- Function: thread-delete #!optional thread
     Mark 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.

 -- Function: thread-deleted-p thread
     Returns true if THREAD has been deleted.


File: librep.info,  Node: Manipulating Threads,  Next: Mutexes,  Prev: Deleting Threads,  Up: Threads

5.15.4 Manipulating Threads
---------------------------

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

 -- Function: thread-suspend #!optional thread milliseconds
     Mark THREAD (or the current thread) as being suspended. It will
     not be selected until either it has had this status removed, or
     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.

 -- Function: thread-join thread #!optional timeout default-value
     Suspends the current thread until either THREAD has exited, or
     TIMEOUT milliseconds have passed.

     If THREAD exits normally, then the value of the last form it
     evaluated is returned; otherwise DEFAULT-VALUE is returned.

     It is an error to call `thread-join' on a THREAD that is not a
     member of the current dynamic root.

 -- Function: thread-wake thread
     Remove the suspended state from thread THREAD. It will then be
     scheduled for execution sometime subsequently, if its dynamic root
     is active.

 -- Function: thread-suspended-p thread
     Returns true if THREAD is currently suspended.

   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.

 -- Function: thread-forbid
     Increment the forbid count.

 -- Function: thread-permit
     Decrement the forbid count.

 -- Macro: without-interrupts #!rest forms
     Evaluate the list of forms FORMS with thread preemption
     temporarily disabled.


File: librep.info,  Node: Mutexes,  Next: Thread Implementation Notes,  Prev: Manipulating Threads,  Up: Threads

5.15.5 Mutual Exclusion Devices
-------------------------------

"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 `rep.threads.mutex' module (*note
Modules::).

 -- Function: make-mutex
     Create and return a mutex object. No thread will own the new mutex.

 -- Function: mutexp arg
     Return true if ARG is a mutex object.

 -- Function: obtain-mutex mutex
     Obtain the mutex MUTEX for the current thread. Will suspend the
     current thread until the mutex is exclusively available.

 -- Function: maybe-obtain-mutex mutex
     Attempt to obtain mutex MUTEX for the current thread without
     blocking. Returns true if able to obtain the mutex, false
     otherwise.

 -- Function: release-mutex mutex
     Release the mutex object MUTEX (which must have previously been
     obtained by the current thread). Returns true if the mutex has no
     new owner.


File: librep.info,  Node: Thread Implementation Notes,  Prev: Mutexes,  Up: Threads

5.15.6 Thread Implementation Notes
----------------------------------

The threads used by Librep are _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:

   * blocking I/O blocks _all_ threads, not just the thread doing the
     I/O,

   * only a single processor is used, thereby avoiding any true
     parallelism on multi-processor systems.

The main advantage is the ease of implementation, especially when
retrofitting threads into the previously single-threaded interpreter.


File: librep.info,  Node: Loading,  Next: Compiled Lisp,  Prev: Threads,  Up: The language

5.16 Loading
============

In Lisp, programs (also called "modules", or "libraries") are stored in
files. Each file is a sequence of Lisp forms (known as "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 "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


File: librep.info,  Node: Load Function,  Next: Autoloading,  Up: Loading

5.16.1 Load Function
--------------------

 -- Function: load program #!optional no-error no-path no-suffix
     This function loads the file containing the program called PROGRAM.
     First the file is located, then evaluated, i.e., each top-level
     form is read and evaluated in order.

     If PROGRAM is not an absolute path, each directory named by the
     variable `load-path' is searched until the file containing PROGRAM
     is found. In each directory two different file names are tried,

       1. PROGRAM with `.jlc' appended to it. Files with a `.jlc'
          suffix are usually compiled Lisp files. *Note Compiled Lisp::.

          If it is older than a `.jl' version of the same file (i.e. the
          source code is newer than the compiled version), a warning is
          displayed and the `.jl' version is used instead.

       2. PROGRAM with `.jl' appended, most uncompiled Lisp programs are
          stored in files with names like this.

     Notice that the file PROGRAM with no modifications is _not_
     loaded. If you want it, set NO-SUFFIX to non-nil.

     Filename can have a leading tilde in Unix, and tar archive is also
     readable directly. See *Note File Handlers::.

     If none of these gives a result the next directory is searched in
     the same way. When all directories in `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,

    NO-ERROR
          When this argument is true no error is signalled if the file
          can not be located. Instead the function returns false.

    NO-PATH
          The variable `load-path' is not used, PROGRAM must point to
          the file from the current working directory.

    NO-SUFFIX
          When true no `.jlc' or `.jl' suffixes are applied to the
          PROGRAM argument when locating the file.

     If no Lisp file can be found matching PROGRAM, then each directory
     in the variable `dl-load-path' is searched for a `libtool' shared
     library called `PROGRAM.la'.

 -- Variable: load-filename
     Whilst loading a Lisp library, this variable is bound to the name
     of the file being loaded.

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

          load-path
              => ("/usr/local/lib/rep/1.0/lisp/"
                  "/usr/local/lib/rep/site-lisp/" "")

     The element `""' refers to the current directory, note that
     directory names should have an ending `/' (or whatever) so that
     when concatenated with the name of the file they make a meaningful
     filename.

 -- Variable: dl-load-path
     A list of strings defining all directories to search for shared
     libraries.

 -- Variable: lisp-lib-directory
     The name of the directory in which the standard Lisp files are
     stored.

          lisp-lib-dir
              => "/usr/local/lib/rep/1.0/lisp/"

 -- Variable: after-load-alist
     An association list of elements of the format `(FILE FORMS ...)'.
     When the library FILE is loaded, all FORMS are executed. However,
     note that FILE must _exactly_ match the PROGRAM argument to the
     `load' function.

 -- Function: eval-after-load library form
     Arrange for FORM to be evaluated immediately after the Lisp
     library of LIBRARY has been read by the `load' function.  Note
     that LIBRARY must exactly match the PROGRAM argument to `load'.


File: librep.info,  Node: Autoloading,  Prev: Load Function,  Up: Loading

5.16.2 Autoloading
------------------

Obviously, not all features of the Librep environment are always used.
"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 "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 `autoload' function.

 -- Function: autoload symbol file #!optional is-command
     Installs an autoload form into the symbol SYMBOL. It marks that
     when SYMBOL is called as a function the lisp library FILE should
     be loaded to provided the actual definition of SYMBOL.

   "Magic cookie" `;;;###autoload' comment in the source is
meaningless. It was supported by Obsolete "Jade" editor only.


File: librep.info,  Node: Compiled Lisp,  Next: Docstrings,  Prev: Loading,  Up: The language

5.17 Compiled Lisp
==================

Librep contains a Lisp compiler as well as an interpreter; this takes a
Lisp form or program and compiles it into a "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:

     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

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


File: librep.info,  Node: Compilation Functions,  Next: Compiler Declarations,  Up: Compiled Lisp

5.17.1 Compilation Functions
----------------------------

These functions are defined in `rep.vm.compiler'.

 -- Function: compile-form form
     This function compiles the Lisp form FORM into a byte-code form
     which is returned.

          (compile-form '(setq foo bar))
              => (run-byte-code "\030F!v" [bar foo] 2)

 -- Command: compile-function function
     This function replaces the uncompiled body of the function FUNCTION
     (a symbol) with a compiled version, then returns FUNCTION.

 -- Command: compile-file file-name
     This function compiles the file called FILE-NAME into a file of
     compiled Lisp forms whose name is FILE-NAME with `c' appended to
     it (i.e. if FILE-NAME is `foo.jl' it will be compiled to
     `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
     FILE-NAME.

 -- Command: compile-directory directory #!optional force exclude
     Compiles all the Lisp files in the directory called DIRECTORY which
     either haven't been compiled or whose compiled version is older
     than the source file (Lisp files are those ending in `.jl').

     If the optional argument FORCE is true _all_ Lisp files will be
     recompiled whatever the status of their compiled version.

     The EXCLUDE argument may be a list of filenames, these files will
     _not_ be compiled.

     When this function is called interactively it prompts for the
     directory.

 -- Command: compile-module module-name
     Compiles all uncompiled function definitions in the module named
     MODULE-NAME (a symbol).

     When called interactively the module name will be prompted for.

 -- Function: run-byte-code byte-codes constants stack
     Interprets the string of byte instructions BYTE-CODES with the
     vector of constants CONSTANTS.

     This function should _never_ be called by hand. The compiler will
     produce calls to this function when it compiles a form or a
     function.

   There is a second form that byte-code objects can take: a vector
whose read syntax includes a preceding `#' character is a "byte-code
subr". These objects represent compiled Lisp functions and macros.

 -- Function: bytecodep arg
     Returns true if ARG is a byte-code subroutine.


File: librep.info,  Node: Compiler Declarations,  Next: Compilation Tips,  Prev: Compilation Functions,  Up: Compiled Lisp

5.17.2 Compiler Declarations
----------------------------

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.

 -- Macro: declare clause...
     Offer the information contained in the CLAUSE... forms to the
     compiler, which it may or may not use when compiling the program.

     Each 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:

    `(bound VARIABLES...)'
          This declaration tells the compiler that all symbols VARIABLES
          have lexical bindings for the extent of the current lexical
          scope. This is often useful to prevent spurious compiler
          warnings.

    `(special VARIABLES...)'
          This tells the compiler that all symbols 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.)

    `(unused VARIABLES...)'
          Directs the compiler not to warn about bindings for
          VARIABLES... being unreferenced.

    `(inline NAMES...)'
          Tells the compiler that it should consider inlining calls to
          the functions called NAMES.... Inlining will only occur if
          these functions are declared in the same module as, and
          after, the declaration itself.

    `(in-module 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 MODULE-NAME
          (a symbol).

    `(language 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 `rep', then the Rep language
          dialect is compiled for).

    `(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 `call/cc' causes a function call to
          return more than once (*note 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:

             * the binding is not accessed from any inner closures, and,

             * the binding is never modified after being initialized
               (actually, the binding may be modified between being
               intialized and the next function call)

          this declaration is often useful where `call/cc' isn't used,
          and there is a lot of side effecting of local variables.

     Declaration forms always evaluate to false.

   A second type of declaration is the `eval-when-compile' form, it
allows Lisp forms to be evaluated only at compile-time.

 -- Macro: eval-when-compile form
     This form tells the system that FORM should only be evaluated when
     the containing code is being compiled.

     The compiler knows to recognize FORMs of the pattern
     `(eval-when-compile (require 'FEATURE))' as marking that FEATURE
     should be imported at compile-time. Any other FORMs are simply
     evaluated in an unspecified environment.

     When interpreted, `eval-when-compile' forms alway evaluate to
     false, when compiled they evaluate to the result of evaluating the
     FORM at compile-time.


File: librep.info,  Node: Compilation Tips,  Next: Disassembly,  Prev: Compiler Declarations,  Up: Compiled Lisp

5.17.3 Compilation Tips
-----------------------

Here are some tips for making compiled code run fast(er):

   * Instead of using `while' loops to traverse lists, use `mapc' or
     tail recursion.

     For example you might code a function to scan a list using
     iteration through a `while' loop:

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

     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:

          (defun scan-list (lst elt)
            (if (equal (car lst) elt)
                elt
              (scan-list (cdr lst) elt)))

     An alternative idiom is to map an anonymous function over the list
     using the `mapc' function:

          (defun scan-list (lst elt)
            (catch 'return
              (mapc (lambda (x)
                      (when (equal x elt)
                        (throw 'return elt)))
                    lst)
              nil))

     In fact, the compiler knows that calls to `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.

   * In some cases the functions `member', `memq', `assoc', etc... 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 `scan-list' example can again be rewritten, this time
     as:

          (defun scan-list (lst elt)
            (car (member elt lst)))

   * All conditional structures are equivalent when compiled (they are
     all translated to `cond' statements), so use whichever is the
     easiest to understand.

   * 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

          (logor (lsh 1 6) x)
              ==> (logor 32 x)

   * Careful use of named constants (*note 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 _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 `eq' whereas two references to the same
     variable are always `eq').

   * 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:

     `cons', `car', `cdr', `rplaca', `rplacd', `nth', `nthcdr', `aset',
     `aref', `length', `eval', `+', `*', `/', `%', `mod', `lognot',
     `not', `logior', `logand', `logxor', `equal', `eq', `=', `/=',
     `>', `<', `>=', `<=', `1+', `1-', `-', `set', `lsh', `zerop',
     `null', `atom', `consp', `listp', `numberp', `stringp', `vectorp',
     `throw', `boundp', `symbolp', `get', `put', `signal', `return',
     `reverse', `nreverse', `assoc', `assq', `rassoc', `rassq', `last',
     `mapcar', `mapc', `member', `memq', `delete', `delq', `delete-if',
     `delete-if-not', `copy-sequence', `sequencep', `functionp',
     `special-form-p', `subrp', `eql', `max', `min', `filter',
     `macrop', `bytecodep', `bind-object'.

   * 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:

        * Function and macro definitions have their body forms compiled
          into a single byte-code form. The doc-string and interactive
          declaration are not compiled.

        * If the form is a list form (*note List Forms::) and the
          symbol which is the car of the list is one of:

          `if', `cond', `when', `unless', `let', `let*', `catch',
          `unwind-protect', `error-protect', `with-buffer',
          `with-window', `progn', `prog1', `prog2', `while', `and',
          `or', `case'.

          then the form is compiled. Otherwise it is just written to
          the output file in its uncompiled state.

     If your program contains a lot of top-level forms which you know
     will not be compiled automatically, consider putting them in a
     `progn' block to make the compiler coalesce them into one
     byte-code form.


File: librep.info,  Node: Disassembly,  Prev: Compilation Tips,  Up: Compiled Lisp

5.17.4 Disassembly
------------------

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!

 -- Command: disassemble function #!optional stream
     This function disassembles the compile Lisp function FUNCTION. It
     writes a listing to the output stream STREAM (normally the value
     of the `standard-output' variable).

     When called interactively it will prompt for a function to
     disassemble.  Defined in `rep.vm.disassembler'.

   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 `fib' function given at the
start of this section:

     (define (fib n)
       (if (<= n 2)
           1
         (+ (fib (- n 1))
            (fib (- n 2)))))

After compilation and disassembly, the following is produced (but
without the annotations):

     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


File: librep.info,  Node: Docstrings,  Next: Datums,  Prev: Compiled Lisp,  Up: The language

5.18 Documentation Strings
==========================

The "docstring", or documentation string, of a variable or function
gives the description on it, given at its definition.

 -- Function: documentation symbol structure value
     Returns the documentation-string for SYMBOL. It should be the name
     of a special variable, function, macro, or a special form.  If
     it's not a variable, then VALUE should be the function itself,
     like a closure.

     Returns nil when not found. This function is defined in
     `rep.lang.doc' module.

     STRUCTURE can be nil. It was required in the old syntax.

   Docstring is stored in a very complicated way. Those from installed
files are stored in `DOC' file. Others use the plist for the name. If
it's a special variable, then docstring is in `documentation' property,
and a closure and a macro, in `documentation#MODULE'.


File: librep.info,  Node: Datums,  Next: Queues,  Prev: Docstrings,  Up: The language

5.19 Datums
===========

"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 `rep.data.datums'.

 -- Function: make-datum value key
     Create and return a new datum object. It has the value VALUE
     associated with it, and has type KEY.

 -- Function: datum-ref arg key
     If ARG has type KEY, then return the value associated with it.
     Otherwise, an error is signalled.

 -- Function: datum-set arg key value
     If ARG has type KEY, then set the value associated with it to be
     VALUE. Otherwise, an error is signalled.

 -- Function: has-type-p arg key
     Return true if ARG has type KEY.

 -- Function: define-datum-printer key printer
     Associate the function PRINTER with all datum objects of type KEY.
     When any such object is printed, PRINTER is applied to two
     arguments, the datum and the stream to which it should be printed
     (*note Output Streams::).


File: librep.info,  Node: Queues,  Next: Records,  Prev: Datums,  Up: The language

5.20 Queues
===========

A "queue" is an ordered set of objects, such that objects enter at one
end of the queue (the "tail"), and leave from the other end of the
queue (the "head"). The acts of entering and leaving a queue are often
called "enqueing" and "dequeueing".

   Librep provides a straightforward queue implementation, implemented
by the `rep.data.queues' module (*note Modules::).

 -- Function: make-queue
     Create and return a new queue object. The queue will initially be
     empty.

 -- Function: enqueue q arg
     Add the object ARG to the tail of the queue Q.

 -- Function: dequeue q
     Remove the object at the head of the queue Q, and return it. If Q
     is empty, an error is signalled.

 -- Function: queue-empty-p q
     Return true if the queue Q is not empty.

 -- Function: queuep arg
     Return true if the object ARG is a queue.

 -- Function: queue->list q
     Return a list of objects representing the contents of the queue Q,
     with objects ordered from head to tail. Modifying the list
     structure causes undefined effects to the queue itself.

 -- Function: queue-length q
     Return the number of objects stored in the queue Q.

 -- Function: delete-from-queue q arg
     Removes any occurrences of the object ARG from the queue Q.


File: librep.info,  Node: Records,  Next: Hash Tables,  Prev: Queues,  Up: The language

5.21 Records
============

The "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
`rep.data.records' module (*note Modules::).

   Record types are defined using the `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.

 -- Macro: define-record-type type (constructor fields...) [predicate]
          (field accessor [modifier])...
     This macro creates a new record type storing an opaque object
     identifying the type in the variable named TYPE.

     It then defines a function CONSTRUCTOR with parameter list as
     specified by the FIELDS..., and a predicate function called
     PREDICATE if PREDICATE is given.

     The fields of the record are defined by the sequence of `(FIELD
     ACCESSOR [MODIFIER])' forms, each form describes a single field
     (named FIELD, which may match one of the constructor arguments).

     The function ACCESSOR of each field will be defined that when
     applied to an argument of the record type, returns the value
     stored in the associated FIELD. If the 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 FIELDS... may include all the standard lambda-list
     features (*note Lambda Expressions::), including keyword
     parameters and default values.

   Here is an example record definition:

     (define-record-type :pare
       (kons x y)          ; constructor
       pare?               ; predicate
       (x kar set-kar!)    ; field `x', its accessor and modifier
       (y kdr))            ; field `y' is read-only.

the variable `:pare' is bound to the record type. Following this
definition, the record type could be used as follows:

     (define my-kons (kons 1 2))

     (pare? my-kons)
         => t

     (kar my-kons)
         => 1

     (set-kar! my-kons 42)

     (kar my-kons)
         => 42

   Printed representation of record objects is the name of their type in
angle brackets, e.g. for the above `pare' type, each object prints as
the string `#<:pare>'. This may be redefined using the
`define-record-discloser' function.

 -- Function: define-record-discloser type discloser
     Associate the function DISCLOSER with the record type TYPE.  When
     any record of this type is printed, DISCLOSER is applied to the
     object, it should return the value that will actually be printed.

   For the above example, the following could be used:

     (define-record-discloser :pare (lambda (x) `(pare ,(kar x) ,(kdr x))))

     (kons 'a 'b)
         => (pare a b)

   Constructors for records with large numbers of fields often benefit
from using keyword parameters. For example the `kons' record above
could be defined as follows (though this would make more sense if it
had more than two fields):

     (define-record-type :pare
       (kons #!key (kar 1) (kdr 2))
       pare?
       (kar kar set-kar!)
       (kdr kdr set-kdr!))

     (kons #:kar 42) => (pare 42 2)
     (kons #:kdr 42) => (pare 1 42)


File: librep.info,  Node: Hash Tables,  Next: Guardians,  Prev: Records,  Up: The language

5.22 Hash Tables
================

The `rep.data.tables' module provides a flexible hash table
implementation (*note Modules::). Each hash table is represented by a
lisp object satisfying the `tablep' predicate:

 -- Function: tablep arg
     Return true if ARG is a hash table.

   Hash tables may be created by using the `make-table' and
`make-weak-table' functions:

 -- Function: make-table hash-fun compare-fun
     Create and return a new hash table. When storing and referencing
     keys it will use the function HASH-FUN to map keys to hash codes
     (positive fixnums), and the predicate function COMPARE-FUN to
     compare two keys (should return true if the keys are considered
     equal).

 -- Function: make-weak-table hash-fun compare-fun
     Similar to `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 `make-table' function, the fact
     that the key is stored in the table is not considered good enough
     to prevent it being garbage collected.

 -- Function: table-ref table key
     Return the value stored in hash table TABLE indexed by object KEY.
     Returns false if no such value exists.

 -- Function: table-bound-p table key
     Returns true if the hash table TABLE contains a value associated
     with KEY.

 -- Function: table-set table key value
     Associate the value VALUE with KEY in hash table TABLE. Returns
     `value'.

 -- Function: table-unset table key
     Remove any value stored in TABLE associated with KEY.

 -- Function: table-walk function table
     Call function FUNCTION for every key-value pair stored in hash
     table TABLE. For each pair, the function is called with arguments
     `(KEY VALUE)'.

 -- Function: table-size table
     Returns the number of items currently stored in TABLE.

   Several hash functions are also provided:

 -- Function: string-hash string
     Return an integer representing the string STRING.

 -- Function: symbol-hash symbol
     Call `(string-hash (symbol-name SYMBOL))'.

 -- Function: eq-hash arg
     Return a hash value representing object ARG. The hash is generated
     from the _address_ of the object.

 -- Function: equal-hash arg
     Return a hash value representing object ARG. The hash is generated
     from the _contents_ of the object.


File: librep.info,  Node: Guardians,  Next: Streams,  Prev: Hash Tables,  Up: The language

5.23 Guardians
==============

A "guardian" is a lisp object used to control when other data objects
are recycled by the garbage collector (*note Garbage Collection::).(1)
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.

 -- Function: 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:

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

        * If none of the associated objects have been proved to be
          inaccessible, then return the value false.

   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:

     ;; create a new guardian object
     (setq G (make-guardian))

     ;; create a lisp object
     (setq x (cons 'a 'b))
        => (a . b)

     ;; protect the object using the guardian
     (G x)

     ;; remove the sole reference to the object
     (setq x nil)
        => ()

     ;; 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)
        => (a . b)

     ;; no more inaccessible values available
     (G)
        => ()

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

   (1) Guardians were first described in a paper by R.  Kent Dybvig,
Carl Bruggeman, and David Eby: `"Guardians in a Generation-Based
Garbage Collector", ACM SIGPLAN Conference on Programming Language
Design and Implementation, June 1993.'


File: librep.info,  Node: Streams,  Next: Hooks,  Prev: Guardians,  Up: The language

5.24 Streams
============

A "stream" is a Lisp object which is either a data sink (an "output
stream") or a data source (an "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 `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 `read' function does not need to differentiate.

 -- Function: streamp arg
     Return true if ARG is a stream.

 -- Function: input-stream-p arg
     Return true if ARG is an input stream.

 -- Function: output-stream-p arg
     Return true if ARG is an output stream.

* 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


File: librep.info,  Node: Input Streams,  Next: Output Streams,  Up: Streams

5.24.1 Input Streams
--------------------

These are the possible types of input stream, for the functions which
use them see *Note Input Functions::.

`FILE'
     Characters are read from the file object FILE, for the functions
     which manipulate file objects see *Note Files::.

`FUNCTION'
     Each time an input character is required the FUNCTION is called
     with no arguments. It should return the character read (an
     integer) or false if for some reason no character is available.

     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,

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

`nil'
     Read from the stream stored in the variable `standard-input'.

   It is also possible to use a string as an input stream. The string to
be read from must be applied to the `make-string-input-stream' function
and the result from this function used as the input stream.

 -- Function: make-string-input-stream string #!optional start
     Returns an input stream which will supply the characters of the
     string STRING in order starting with the character at position
     START (or from position zero if this argument is undefined).

          (read (make-string-input-stream "(1 . 2)"))
              => (1 . 2)

 -- Variable: standard-input
     The input stream which is used when no other is specified or is
     false.

   Applications that embed Librep, or dynamically loaded extensions,
may provide further input stream types.


File: librep.info,  Node: Output Streams,  Next: Input Functions,  Prev: Input Streams,  Up: Streams

5.24.2 Output Streams
---------------------

These are the different types of output stream, for the functions which
use them see *Note Output Functions::.

`FILE'
     Writes to the file object FILE. *Note Files::.

`FUNCTION'
     The function 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.

`PROCESS'
     Writes to the standard input of the process object PROCESS. If
     PROCESS isn't running an error is signalled. *Note Processes::.

`t'
     Appends the character(s) to the end of the status line message.

`()'
     Write to the stream stored in the variable `standard-output'.

   It is also possible to store the characters sent to an output stream
in a string.

 -- Function: make-string-output-stream
     Returns an output stream. It accumulates the text sent to it for
     the benefit of the `get-output-stream-string' function.

 -- Function: get-output-stream-string string-output-stream
     Returns a string consisting of the text sent to the
     STRING-OUTPUT-STREAM since the last call to
     GET-OUTPUT-STREAM-STRING (or since this stream was created by
     `make-string-output-stream').

          (setq stream (make-string-output-stream))
              => ("" . 0)
          (prin1 keymap-path stream)
              => ("(lisp-mode-keymap global-keymap)" . 64)
          (get-output-stream-string stream)
              => "(lisp-mode-keymap global-keymap)"

 -- Variable: standard-output
     This variable contains the output stream which is used when no
     other is specified (or when the given output stream is false).

 -- Variable: standard-error
     This variable contains the output stream which is used when an
     error message is being reported.

   Applications that embed Librep, or dynamically loaded extensions,
may provide further output stream types.


File: librep.info,  Node: Input Functions,  Next: Output Functions,  Prev: Output Streams,  Up: Streams

5.24.3 Input Functions
----------------------

 -- Function: read-char stream
     Read and return the next character from the input stream STREAM. If
     the end of the stream is reached false is returned.

 -- Function: peek-char stream
     returns the next character from the input-stream STREAM, _without_
     removing that character from the head of the stream. if no more
     characters are available returns nil.

 -- Function: read-chars stream count
     read upto COUNT characters from the input stream STREAM, returning
     a string containing the characters. If EOF is read before reading
     COUNT characters, the returned string will contain the characters
     read up to that point. If no characters are read, `nil' will be
     returned.

 -- Function: read-line stream
     This function reads one line of text from the input stream 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.

 -- Function: read stream
     This function is the function which encapsulates the Lisp reader
     (*note The Lisp Reader::). It reads as many characters from the
     input stream STREAM as required to form the read syntax of a single
     Lisp object (*note Read Syntax::), this object is then returned.

 -- Function: read-from-string string #!optional start
     Reads one Lisp object from the string STRING, the first character
     is read from position START (or position zero).

          (read-from-string STRING START)
          ==
          (read (make-string-input-stream STRING START))


File: librep.info,  Node: Output Functions,  Next: Formatted Output,  Prev: Input Functions,  Up: Streams

5.24.4 Output Functions
-----------------------

 -- Function: write stream data #!optional length
     Writes the specified character(s) to the output stream STREAM.
     DATA is either the character or the string to be written. If DATA
     is a string the optional argument LENGTH may specify how many
     characters are to be written. The value returned is the number of
     characters successfully written.

          (write standard-output "Testing 1.. 2.. 3..")
              -| Testing 1.. 2.. 3..
              => 19

 -- Function: copy-stream input-stream output-stream
     This function copies all characters which may be read from
     INPUT-STREAM to 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!

 -- Function: print object #!optional stream
     Outputs a newline character to the output stream STREAM, then
     writes a textual representation of OBJECT to the stream.

     If possible, this representation will be the read syntax of OBJECT.

     OBJECT is returned.

          (print '(1 2 3))
              -|
              -| (1 2 3)
              => (1 2 3)

 -- Function: prin1 object #!optional stream
     Similar to `print' but no initial newline is output.

          (prin1 '(1 2 3))
              -| (1 2 3)
              => (1 2 3)

          (prin1 '|(xy((z]|)              ;A strange symbol
              -| \(xy\(\(z\]
              => \(xy\(\(z\]

 -- Function: prin1-to-string object
     Returns a string containing the characters that `prin1' would
     output when it prints OBJECT.

          (prin1-to-string '(1 2 3))
              => "(1 2 3)"

 -- Function: princ object #!optional stream
     Prints a textual representation of OBJECT to the output stream
     STREAM. No steps are taken to create output that `read' can parse;
     in particular, no double-quote characters surround strings.

          (princ "foo")
              -| foo
              => "foo"

          (princ '|(xy((z]|)
              -| (xy((z]
              => \(xy\(\(z\]

   Several variables may be used to control how objects are printed.

 -- Variable: print-escape
     This defines which control characters `print' and `prin1' will
     escape (using backslashes). Possible values are:

    `()'
          Only escape double-quote and backslash characters.

    `newlines'
          Only escape double-quote, backslash, newline, `TAB', and
          formfeed characters.

    `t'
          Escape double-quote, backslash, and all control characters
          (anything with a numeric value less than 32, or greater than
          126).

 -- Variable: print-length
     This variable, if true, limits the number of elements printed from
     lists.

 -- Variable: print-level
     This variable, if true, limits the recursion depth when printing
     lists.


File: librep.info,  Node: Formatted Output,  Prev: Output Functions,  Up: Streams

5.24.5 Formatted Output
-----------------------

 -- Function: format stream template #!rest values
     Writes to a stream, STREAM, a string constructed from the format
     string, TEMPLATE, and list of arguments VALUES.

     If STREAM is false the resulting string will be returned, not
     written to a stream.

     TEMPLATE is a template for the output string, any `%' characters
     introduce a substitution, using the next unused argument.  The
     substitutions have the following syntax,

          %[INDEX$][FLAGS][FIELD-WIDTH]CONVERSION

     INDEX is an optional decimal number specifying exactly which of
     the 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.

     FIELD-WIDTH is a positive decimal integer, defining the size in
     characters of the substitution output.

     CONVERSION is a character defining how to convert the
     corresponding argument value to text. The default options are:

    `s'
          Write the printed representation of the value without quoting
          (as if from the `princ' function).

    `S'
          Write the printed representation _with_ quoting enabled (like
          the `prin1' function).

    `d'
          Output the value as a decimal number.

    `o'
          Write the value in octal.

    `x'
    `X'
          In hexadecimal.

    `c'
          Write the character specified by the value.

    `%'
          Print a literal percent character. None of the VALUES are
          used.

     FLAGS is a sequence of zero or more of the following characters,

    `_'
          Left justify the substitution within the field.

    `^'
          Truncate the substitution at the size of the field.

    `0'
          Pad the field with zeros instead of spaces.

    `+'
          For `d', `x', and `o' conversions, output a leading plus sign
          if the argument is positive.

    ` ' (a space)
          For `d', `x', and `o' conversions, if the result doesn't
          start with a plus or minus sign, output a leading space.

     The list of CONVERSIONS can be extended through the
     `format-hooks-alist' variable; the strings created by these extra
     conversions are formatted as if by the `s' conversion.

     Note that the FIELD-WIDTH and all flags currently have no effect
     on the `S' conversion, (or the `s' conversion when the argument
     isn't a string).

     If STREAM isn't false (in which case the created string is
     returned) the value of STREAM is returned.

          (format nil "foo %S bar 0x%x" '(x . y) 255)
              => "foo (x . y) bar 0xff"

          (format standard-output "The %2$s is %1$s!" "purple" "dog")
              -| The dog is purple!
              => #<buffer *jade*>

 -- Variable: format-hooks-alist
     This variable is an association-list, each element being `(CHAR .
     FUNCTION)', defining extra conversions for the `format' function.

     If a conversion `%X' is given, and the alist contains an element
     whose car is the character X, the the associated function is
     called with one value, the next argument to be formatted. It should
     return the string to be inserted.


File: librep.info,  Node: Hooks,  Next: Files,  Prev: Streams,  Up: The language

5.25 Hooks
==========

A "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 `format-hooks-alist' variable (*note 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.


File: librep.info,  Node: Functions As Hooks,  Next: Normal Hooks,  Up: Hooks

5.25.1 Functions As Hooks
-------------------------

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 `-function'.

   An alternative scheme is to use a variable to store the hook, its
value should be the function to call.


File: librep.info,  Node: Normal Hooks,  Prev: Functions As Hooks,  Up: Hooks

5.25.2 Normal Hooks
-------------------

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 `-hook'.

   These functions are exported by the `rep.system' module.

 -- Function: add-hook hook function #!optional at-end
     This function adds a new function FUNCTION to the list of
     functions installed in the (list) hook HOOK (a symbol).

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

          text-mode-hook
              => (#<closure fill-mode-on>)
          (add-hook 'text-mode-hook my-function)
              => (#<closure my-function> #<closure fill-mode-on>)

 -- Function: remove-hook hook function
     This function removes the function FUNCTION from the list of
     functions stored in the (list) hook HOOK (a symbol).

     _All_ instances of FUNCTION are deleted from the hook.

   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, _all_ functions are called. In an `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 `or' type hook aborts when a function returns a
true result.

 -- Function: call-hook hook arg-list #!optional type
     Call the hook named by the symbol HOOK, passing all functions the
     arguments in the list ARG-LIST. Note that HOOK may also be the
     actual list of functions to call.

     TYPE defines how the return values of each function in the hook
     are treated. If TYPE is false they are ignored, if TYPE is the
     symbol `and' the hook aborts after a function returns false, if
     TYPE is `or' the hook aborts when a function returns true.

     In all cases the value returned by the last-evaluated function is
     returned.


File: librep.info,  Node: Files,  Next: Processes,  Prev: Hooks,  Up: The language

5.26 Files
==========

Librep allows you to manipulate files in the operating system's filing
system; a special type of Lisp object, a "file object", is used to
represent files which have been opened for reading or writing (through
the streams mechanism, *note 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 `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


File: librep.info,  Node: File Names,  Next: File Objects,  Up: Files

5.26.1 File Names
-----------------

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

 -- Function: file-name-absolute-p file-name
     Returns true when FILE-NAME is not specified relative to the
     current directory.

 -- Function: file-name-directory file-name
     This function returns the directory part of the file name string
     FILE-NAME. This is the substring of FILE-NAME defining the
     directory containing the file.

          (file-name-directory "/tmp/foo")
              => "/tmp/"

          (file-name-directory "foo")
              => ""

          (file-name-directory "foo/bar/")
              => "foo/bar/"

 -- Function: file-name-nondirectory file-name
     Returns the substring of the file name FILE-NAME which is _not_
     the directory part.

          (file-name-nondirectory "/tmp/foo")
              => "foo"

          (file-name-nondirectory "foo")
              => "foo"

          (file-name-nondirectory "foo/bar/")
              => ""

 -- Function: file-name-as-directory file-name
     Returns a string through which the item in the file system named by
     FILE-NAME can be referred to as a directory.

          (file-name-as-directory "./foo")
              => "./foo/"

          (file-name-as-directory "./foo/")
              => "./foo/"

 -- Function: directory-file-name directory-name
     Returns a string through which the directory named by
     DIRECTORY-NAME can be referred to as a file.

          (directory-file-name "./foo/")
              => "./foo"

          (directory-file-name "./foo")
              => "./foo"

 -- Function: expand-file-name file-name #!optional base-dir
     Expands FILE-NAME assuming that it specifies a file relative to
     BASE-DIR. If BASE-DIR is undefined it is taken as the current
     value of the `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:

       1. BASE-DIR (or `default-directory') is absolute,

       2. FILE-NAME is already absolute.

          (expand-file-name "foo" "./bar")
              => "bar/foo"

     Note for file handler implementors: when a handler is called for
     the `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 `.'
     and `..' entries or whatever).

 -- Function: canonical-file-name file-name
     This function returns the canonical name of the file referred to
     by the string 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.

          (canonical-file-name "foo")
              => "/home/john/src/librep/man/foo"

 -- Function: local-file-name file-name
     Librep supports extensible file handling (*note 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
     FILE-NAME, if it is found in the local system, or false, if the
     file does not.

          (local-file-name "foo")
              => "/home/john/src/librep/man/foo"

          (local-file-name "/john@tango:foo")
              => ()

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

          (make-temp-name)
              => "/tmp/00088aaa"

          (make-temp-name)
              => "/tmp/00088baa"

 -- Variable: default-directory
     This variable names the current working directory. All relative
     file names are interpreted starting from this location in the file
     system.


File: librep.info,  Node: File Objects,  Next: File Information,  Prev: File Names,  Up: Files

5.26.2 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 (*note Streams::).

 -- Function: filep object
     This function returns true when its argument is a file object.

* Menu:

* Creating File Objects::       Opening files
* Destroying File Objects::     Closing files
* Functions on File Objects::   Functions operating on file objects


File: librep.info,  Node: Creating File Objects,  Next: Destroying File Objects,  Up: File Objects

5.26.2.1 Creating File Objects
..............................

 -- Function: open-file file-name mode
     This function opens the file called FILE-NAME (*note File Names::)
     and returns the new file object.

     The MODE argument is a symbol defining the access modes used to
     open the file with, the options are:

    `read'
          Open an existing file for reading only.

    `write'
          Open the file for writing only, if the file exists it is
          truncated to zero length. Otherwise a new file is created.

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

The three standard I/O streams are also available as file handles.

 -- Function: stdin-file
     Return a file object representing the interpreters standard input.

 -- Function: stdout-file
     Return a file object representing the interpreters standard output.

 -- Function: stderr-file
     Return a file object representing the interpreters standard error.

   Attempting to close any of these files will result in the associated
stream being connected to `/dev/null'.


File: librep.info,  Node: Destroying File Objects,  Next: Functions on File Objects,  Prev: Creating File Objects,  Up: File Objects

5.26.2.2 Destroying File Objects
................................

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.

 -- Function: close-file file-object
     This function closes the file pointed to by the file object
     FILE-OBJECT.

     Subsequently, any stream accesses FILE-OBJECT are illegal and will
     signal an error.


File: librep.info,  Node: Functions on File Objects,  Prev: Destroying File Objects,  Up: File Objects

5.26.2.3 Functions on File Objects
..................................

 -- Function: seek-file file #!optional offset where
     When called as `(seek-file FILE)', returns the distance in bytes
     from the start of the file that the next character would be read
     from.

     When called as `(seek-file FILE OFFSET [WHERE])' alters the
     position from which the next byte will be read. WHERE can be one
     of the values:

    `()'
          OFFSET bytes after the current position.

    `start'
          OFFSET bytes after the beginning of the file.

    `end'
          OFFSET bytes before the end of the file.

     Note that not all files may be seekable; if `(seek-file FILE)'
     returns false, indicating that the current position is unknown,
     any attempts to set the current position will also fail.

 -- Function: flush-file file
     This function flushes any buffered output to the file object FILE
     to disk.

 -- Function: file-binding file
     Returns the name of the file which the file object FILE is
     currently bound to. Returns false if the file is currently unbound
     (i.e. `close-file' was called on it).

   The next three functions are used when non-local files are being
accessed. See *Note File Handlers:: for more details.

 -- Function: file-bound-stream file
     If the file object 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.

 -- Function: file-handler-data file
     Return the file-handler-specific data associated with the file
     object FILE.

 -- Function: set-file-handler-data file data
     Set the handler-specific data of file object FILE to DATA.  This
     should only be done by the handler owning the file.

   It's also possible to register a callback function to be invoked when
input is available on a file,

 -- Function: set-input-handler local-file function
     Arrange for FUNCTION to be called whenever pending input is
     available on LOCAL-FILE, a file object bound to a file in the
     local file space.

     Note that this makes LOCAL-FILE subsequently do non-blocking input.

     This function is normally only useful when LOCAL-FILE represents a
     pipe or socket.


File: librep.info,  Node: File Information,  Next: Manipulating Files,  Prev: File Objects,  Up: Files

5.26.3 File Information
-----------------------

A number of functions exist which when given the name of a file return
one of the attributes relating to that file.

 -- Function: file-exists-p file-name
     Returns true when a file FILE-NAME exists.

 -- Function: file-regular-p file-name
     Returns true when the file FILE-NAME is a `normal' file. This means
     that it isn't a directory, device, symbolic link or whatever.

 -- Function: file-directory-p file-name
     Returns true when the file FILE-NAME is a directory.

 -- Function: file-symlink-p file-name
     Returns true when the file FILE-NAME is a symbolic link.

 -- Function: file-readable-p file-name
     Returns true when the file FILE-NAME is readable.

 -- Function: file-writable-p file-name
     Returns true when the file FILE-NAME is writable.

 -- Function: file-executable-p file-name
     Returns true when the file FILE-NAME is executable.

 -- Function: file-owner-p file-name
     Returns true when the ownership of the file FILE-NAME is the same
     as that of any files written by the editor.

 -- Function: file-gid file-name
     Returns the gid of the file FILE-NAME, as integer.

 -- Function: file-uid file-name
     Returns the uid of the file FILE-NAME, as integer.

 -- Function: file-size file-name
     Returns the number of bytes stored in the file named FILE-NAME.

 -- Function: file-nlinks file-name
     Returns the number of hard links pointing to the file FILE-NAME. If
     FILE-NAME has only one name the number will be one.

 -- Function: file-modes file-name
     This function returns the access permissions of the file FILE-NAME.
     This will be an integer whose format is undefined; it differs from
     operating system to operating system.

 -- Function: file-modes-as-string file-name
     Returns a ten-character string describing the attibutes of the file
     called FILE-NAME

          (file-modes-as-string ".")
              => "drwxr-sr-x"

 -- Function: set-file-modes file-name modes
     This function sets the access permissions of the file FILE-NAME to
     the integer MODES (as returned by the `file-modes' function).

 -- Function: file-modtime file-name
     Returns the system time at the last modification to the file
     FILE-NAME, this will be in the usual timestamp format, *Note
     Timestamps::.

 -- Function: file-newer-than-file-p file-name1 file-name2
     This function returns true if the file FILE-NAME1 was modified
     more recently than the file FILE-NAME2 was.


File: librep.info,  Node: Manipulating Files,  Next: Manipulating Directories,  Prev: File Information,  Up: Files

5.26.4 Manipulating Files
-------------------------

 -- Command: delete-file file-name
     This function deletes the file called FILE-NAME. When called
     interactively FILE-NAME is prompted for.

 -- Command: rename-file file-name new-name
     This function attempts to change the name of the file NEW-NAME to
     NEW-NAME.

     This won't work from one file system to another or if a file called
     NEW-NAME already exists, in these cases an error is signalled.

     This prompts for its arguments when called interactively.

 -- Command: copy-file file-name destination-name
     Creates a new copy of the file FILE-NAME with the name
     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.


File: librep.info,  Node: Manipulating Directories,  Next: Manipulating Symlinks,  Prev: Manipulating Files,  Up: Files

5.26.5 Manipulating Directories
-------------------------------

 -- Command: make-directory directory-name
     Create a new directory called DIRECTORY-NAME.

 -- Command: delete-directory directory-name
     Delete the directory called DIRECTORY-NAME. This only succeeds if
     the directory in question is empty, otherwise an error is
     signalled.

 -- Function: directory-files directory-name
     Returns a list of the names of all items in the directory whose
     name is DIRECTORY-NAME. The names in the list will be relative to
     the directory DIRECTORY-NAME.

          (directory-files "/tmp/foo"
              => ("bar" "subdir" "xyz" "." "..")


File: librep.info,  Node: Manipulating Symlinks,  Next: File Handlers,  Prev: Manipulating Directories,  Up: Files

5.26.6 Manipulating Symbolic Links
----------------------------------

 -- Function: make-symlink name contents
     Create a symbolic link called NAME, containing the string CONTENTS.

 -- Function: read-symlink name
     Return the string that is the contents of the symbolic link called
     NAME. Signals an error if no such link exists.


File: librep.info,  Node: File Handlers,  Next: Remote Files,  Prev: Manipulating Symlinks,  Up: Files

5.26.7 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 "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 (*note Regular Expressions::).

   For example, in Unix, a leading tilde `~' expands to the home
directory. See below.

 -- Variable: file-handler-alist
     This variable contains a list of file handler declarations, each
     one of the form `(REGEXP . FUNCTION)'. Whenever a file operation
     is performed on a file whose name matches REGEXP, FUNCTION is
     invoked to perform the action. The function is called as
     `(FUNCTION OPERATION ARGS...)', where OPERATION and ARGS are from
     the original call.

     For example if the `file-handler-alist' contains the entry `("^~"
     . tilde-file-handler)', then all file operations on files starting
     with a tilde are redirected to the `tilde-file-handler' function.

     Thus if a form `(file-exists-p "~/foo")' is executed, it would
     result in a call to `tilde-file-handler' as `(tilde-file-handler
     'file-exists-p "~/foo")'.

   The list of operations that may be redirected to a file handler is:
`file-name-absolute-p', `expand-file-name', `local-file-name',
`canonical-file-name', `file-name-nondirectory', `file-name-directory',
`file-name-as-directory', `directory-file-name', `open-file',
`close-file', `flush-file', `seek-file', `write-buffer-contents',
`read-file-contents', `insert-file-contents', `delete-file',
`rename-file', `copy-file', `copy-file-to-local-fs',
`copy-file-from-local-fs', `make-directory', `delete-directory',
`file-exists-p', `file-regular-p', `file-readable-p', `file-writable-p',
`file-directory-p', `file-symlink-p', `file-owner-p', `file-nlinks',
`file-size', `file-modes', `file-modes-as-string', `set-file-modes',
`file-modtime', `directory-files', `make-symlink', `read-symlink'.

   There are several undefined functions in this list. The
`write-buffer-contents', `read-file-contents', and
`insert-file-contents' pertain to the Jade text editor. The other two
are defined as follows.

 -- 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 FILE-NAME, to the file
     on the local file system LOCAL-NAME.

 -- Operation: copy-file-from-local-fs local-name file-name
     Called when copying files between file handlers, this operation
     should copy the local file FILE-NAME to the file matching the
     handler FILE-NAME.

   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 `open-file' operation, it is
possible to create file handles from arbitrary streams.

 -- Function: make-file-from-stream file-name stream handler
     Return a new file object that refers to the logical file called
     FILE-NAME, that is not in the local filing system. All access to
     the file object will be directed through the stream object STREAM,
     and the file handler function HANDLER.

   An alternative method of opening remote files is to use a temporary
file in the local file system with either one (`read' or `write'
modes), or two (`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 `seek-file' operation.

Default File Handlers
---------------------

Librep provides the following file handlers by default:

   * Tilde expansion

     In Unix, a leading tilde `~' is expanded to the user's home
     directory.

   * Archives as directories

     Some archive files' contents are treated like a directory, by
     adding "#tar/". For example, the file `foo/bar.jl' stored in
     `/dir/baz.tar.gz' can be accessed with
          (load "/dir/baz.tar.gz#tar/foo/bar")
     Supported compressions are gz with suffixes `gz' and `tgz', bzip2
     with `bz2', lzma with `xz', `lz' and `lzma'.


File: librep.info,  Node: Remote Files,  Prev: File Handlers,  Up: Files

5.26.8 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 `remote.jl' Lisp library.

   Accessing a file name matching the regular expression:

     ^/(([a-zA-Z0-9._-]+)@)?([a-zA-Z0-9._-]+):

for example `/john@host.com:file' refers to a file called `file' owned
by the user `john', on the system `host.com'.

   If no username is specified explicitly, two variables are used to
select the user:

 -- Variable: remote-host-user-alist
     An alist mapping host regexps to the default user name to use for
     remote file connections to that host.

 -- Variable: remote-default-user
     User name to use for remote file connections when otherwise
     unspecified. By default the current user name on the local system.

   Two variables control how individual hosts are matched to methods of
accessing files.

 -- Variable: remote-auto-backend-alist
     An alist of `(HOST-REGEXP . BACKEND-TYPE)' mapping host names to
     methods of accessing remote files.

 -- Variable: remote-default-backend
     A symbol defining the method to use for otherwise unselected hosts.

   A method of accessing files, or a "backend" is a symbol whose
`remote-backend' property names a function to call when files need to
be accessed. For example the `ftp' backend is initialised as:

     (put 'ftp 'remote-backend remote-ftp-handler)

   The backend function is called as `(FUNCTION SPLIT-NAME OPERATION
ARGS)'. The SPLIT-NAME is a three-element list, `(USER-OR-NIL HOST
FILE)' defining the file to be accessed. The other options are as usual.
Further details can be found in the `remote.jl', `remote-ftp.jl' and
`remote-rcp.jl' Lisp source files.

   The `ftp' backend is currently the most well-developed, several
functions and variables may be used to customise its behaviour.

 -- Function: remote-ftp-add-passwd user host passwd
     Add the string PASSWD as the password for the FTP session
     connecting to USER@HOST.

 -- Variable: remote-ftp-show-messages
     When true (the default), messages are displayed as FTP commands are
     executed.

 -- Variable: remote-ftp-display-progress
     When true (the default) display progress of FTP transfers.

 -- Variable: remote-ftp-anon-users
     A regular expression matching the user names for "anonymous" FTP
     sessions.

 -- Variable: remote-ftp-anon-passwd
     The string to send as the passwd of an anonymous FTP session. By
     default the current uses email address.

   There is a problem with the `ftp' backend however; due to
limitations in the FTP protocol, not all Librep file operations are
supported, with the most obvious exception being the `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 `rsh' to connect to the
remote host in question, then the `rep' backend may be used.

   The `rep-remote' program distributed with Librep must exist on the
remote host, this is executed via `rsh' and provides a protocol for
executing all of Librep's file operations on that host. See the
`lisp/remote-rep.jl' file in the distribution for more details.


File: librep.info,  Node: Processes,  Next: String Functions,  Prev: Files,  Up: The language

5.27 Processes
==============

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 `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 `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


File: librep.info,  Node: Process Objects,  Next: Asynchronous Processes,  Up: Processes

5.27.1 Process Objects
----------------------

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

 -- Function: processp object
     This function returns true when its argument is a process object.

   The programmer-accessible components of a process object are,

"Output stream"
     A normal Lisp output stream (*note Output Streams::), all data
     which the subprocess outputs to its `stdout' channel is copied to
     this output stream. *Note Process I/O::.

"Error stream"
     A normal Lisp output stream (*note Output Streams::), all data
     which the subprocess outputs to its `stderr' channel is copied to
     this output stream. Unless explicitly specified error output goes
     to the `stdout' stream. *Note Process I/O::.

"State change function"
     A Lisp function, called each time the state of the subprocess
     being run on the object changes. *Note Process States::.

"Program name"
     The name of the program (a string) to execute when the subprocess
     is created.

"Program arguments"
     A list of strings defining the arguments which the program executed
     is given.

"Directory"
     When a subprocess is started its current working directory is set
     to the directory named by this component of its process object.

"Connection type"
     Asynchronous subprocesses (*note 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.

 -- Function: make-process #!optional output-stream state-function
          directory program args
     This functions creates and returns a new process object. _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.

   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.

 -- Function: process-prog process
     Returns the value of the program name component of the process
     object PROCESS.

 -- Function: set-process-prog process prog-name
     Sets the value of the program name component of the process object
     PROCESS to the string PROG-NAME, then returns PROG-NAME.

 -- Function: process-args process
     Returns the value of the program arguments component of the
     process object PROCESS.

 -- Function: set-process-args process arg-list
     Sets the value of the program arguments component of the process
     object PROCESS to the list ARG-LIST, then returns ARG-LIST.

 -- Function: process-dir process
     Returns the value of the directory component of the process object
     PROCESS.

 -- Function: set-process-dir process directory
     Sets the value of the directory component of the process object
     PROCESS to the string DIRECTORY, then returns DIRECTORY.

 -- Variable: process-environment
     This is a list of environment variable definitions, as well as
     being used by the `setenv' and `getenv' functions (*note
     Environment Variables::), it also provides the environment of all
     started subprocesses.

          (car process-environment)
              => "LOGNAME=john"

 -- Function: active-processes
     Returns a list containing all active (i.e. running or stopped)
     process objects.


File: librep.info,  Node: Asynchronous Processes,  Next: Synchronous Processes,  Prev: Process Objects,  Up: Processes

5.27.2 Asynchronous Processes
-----------------------------

An "asynchronous process" is one that runs in parallel with Lisp
evaluation, basically this means that once the subprocess has been
started (by the `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 (*note Process States::).
Alternatively the `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 `stdin', `stdout' and `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 `*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.

 -- Function: start-process #!optional process program #!rest args
     This function starts an asynchronous subprocess running on the
     process object PROCESS. If PROCESS is undefined a new process
     object is created (by calling the function `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 `process-error' is signalled.

     The optional argument PROGRAM is a string defining the name of the
     program to execute, it will be searched for in all the directories
     in the `PATH' environment variable. The 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 `ls' program asynchronously, its
     output is sent to the `standard-output' stream.

          (let
              ((process (make-process standard-output)))
            (start-process process "ls" "-s"))

   Note that when Librep exits it kills all of its asynchronous
subprocesses which are still running without warning.

 -- Function: process-connection-type process
     Returns the value of the connection type component of the process
     object PROCESS. See the documentation of the
     `set-process-connection-type' function for the values this may
     take.

 -- Function: set-process-connection-type process symbol
     Sets the value of the connection type component of the process
     object PROCESS to SYMBOL, then returns SYMBOL.

     SYMBOL should be one of the following symbols,

    `pty'
          Use pseudo-terminals to connect to subprocesses running
          asynchronously on this process object.

    `pipe'
          Use standard Unix pipes to connect, this is the default value
          of this component.

    `socketpair'
          Uses a connected pair of sockets.

   Note that currently only the `pipe' connection type allows the
normal and error output streams of the process to be separated.


File: librep.info,  Node: Synchronous Processes,  Next: Process I/O,  Prev: Asynchronous Processes,  Up: Processes

5.27.3 Synchronous Processes
----------------------------

When a "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 `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 `stdin' channel of a synchronous process to a
named file.

   For shell command invocation, see *Note Shell Commands::.

 -- Function: call-process #!optional process input-file-name program
          #!rest args
     This function starts a process running on the process object
     PROCESS. If PROCESS is undefined a new process object is created
     by calling the `make' function.

     If defined, the string INPUT-FILE-NAME names the file to connect
     to the standard input of the subprocess, otherwise the subprocess'
     input comes from the null device (`/dev/null' on UNIX).

     The optional arguments PROGRAM and 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
     `process-environment' variable.

     If any of the optional parameters are unspecified they should have
     been set in the 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
     `process-exit-value' function, see *Note Process Information::.

     If, for some reason, the new subprocess can't be created an error
     of type `process-error' is signalled.

   The following function definition is taken from the `gzip.jl' file,
it shows how the `call-process' function can be used to uncompress a
file into a buffer (for Jade).

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

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


File: librep.info,  Node: Process I/O,  Next: Process States,  Prev: Synchronous Processes,  Up: Processes

5.27.4 Process I/O
------------------

It is only possible for lisp programs to explicitly send input data to
_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
`stdin' channel of the subprocess.

   With synchronous processes, the only control over input data possible
is by giving the `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.

 -- Function: process-output-stream process
     Returns the value of the output stream component of the process
     object PROCESS.

 -- Function: set-process-output-stream process stream
     Sets the value of the output stream component of the process object
     PROCESS to the stream STREAM, then returns STREAM.

   By default the `stdout' and `stderr' streams are combined, use the
`set-process-error-stream' function to separate them.  (Note that this
currently only works with `pipe' connection types.)

 -- Function: process-error-stream process
     Returns the value of the error stream component of the process
     object PROCESS.

 -- Function: set-process-error-stream process stream
     Sets the value of the error stream component of the process object
     PROCESS to the stream STREAM, then returns STREAM.

   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 `accept-process-output' or `sit-for' functions are called.

 -- Function: accept-process-output #!optional seconds milliseconds
     Wait SECONDS plus 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.

 -- Function: sit-for #!optional seconds milliseconds
     Wait for input to arrive and be processed. No more than SECONDS
     seconds plus 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
     `accept-process-output' when Librep is embedded in another
     application, or an extension has been loaded that provides an event
     loop (such as the `gtk' binding). In this case other input forms,
     such as user input, for example, can preempt the timeout.

     This function is exported by the `rep.system' module.

   *Note Streams::.


File: librep.info,  Node: Process States,  Next: Signalling Processes,  Prev: Process I/O,  Up: Processes

5.27.5 Process States
---------------------

Each process object has a "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,

"running"
     This state means that the subprocess using this process object is
     currently running, i.e. it hasn't been stopped.

"stopped"
     Means that the subprocess has been temporarily suspended from
     running.

"unused"
     This means that the process object is free to have a new
     subprocess created on it.

   Predicates exist which test whether a given process object is in one
of these states.

 -- Function: process-running-p process-object
     Returns true when PROCESS-OBJECT is in the running state.

 -- Function: process-stopped-p process-object
     Returns true when PROCESS-OBJECT is in the stopped state.

 -- Function: process-in-use-p process-object
     Returns true when PROCESS-OBJECT is _not_ in the unused state.

   The following two functions are used to stop and then subsequently
continue a process running.

 -- Function: stop-process process-object #!optional whole-group
     This function suspends execution of the subprocess running on the
     process object PROCESS-OBJECT.

     If WHOLE-GROUP is true all subprocesses in the process group of
     PROCESS-OBJECT are stopped.

 -- Function: continue-process process-object #!optional whole-group
     Use this function to continue a subprocess executing after it has
     been stopped (by the `stop-process' function).

     If WHOLE-GROUP is true all subprocesses in the process group of
     PROCESS-OBJECT are continued.

   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.

 -- Function: process-function process
     Returns the value of the state change function component of the
     process object PROCESS.

 -- Function: set-process-function process function
     Sets the value of the state change function component of the
     process object PROCESS to the function FUNCTION, then returns
     FUNCTION.


File: librep.info,  Node: Signalling Processes,  Next: Process Information,  Prev: Process States,  Up: Processes

5.27.6 Signalling Processes
---------------------------

 -- Function: interrupt-process process-object #!optional whole-group
     Sends the `SIGINT' signal to PROCESS-OBJECT.

 -- Function: kill-process process-object #!optional whole-group
     Sends the `SIGKILL' signal to the PROCESS-OBJECT.

   Note that the functions `stop-process' and `continue-process' also
send signals to the subprocess.

 -- Function: signal-process process signal #!optional whole-group
     Send the signal SIGNAL to the process PROCESS; if WHOLE-GROUP is
     true the signal is also sent to all processes in the process group
     of PROCESS.

     PROCESS may be either a Lisp process object, or an integer
     defining the pid of the process to signal (not necessarily started
     by Librep).

     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 `SIG' removed, for example the `SIGINT' signal would be
     sent by using the symbol `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.

   As with the UNIX `kill' system call, `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.


File: librep.info,  Node: Process Information,  Next: Shell Commands,  Prev: Signalling Processes,  Up: Processes

5.27.7 Process Information
--------------------------

 -- Function: process-id process-object
     This function returns the operating-system identifier associated
     with the subprocess currently running on the process object
     PROCESS-OBJECT.

 -- Function: process-exit-value process-object
     Returns the integer representing the return code of the last
     subprocess to be run on PROCESS-OBJECT.

     If no subprocess has been run on PROCESS-OBJECT, PROCESS-OBJECT is
     currently in the running state or the last subprocess exited
     abnormally (i.e. from a terminal signal) false is returned.

 -- Function: 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 PROCESS-OBJECT.

     Note that the exit status is _not_ the value given to the `exit'
     function in a C program, use the `process-exit-value' to access
     this value.

     If no process has been run on PROCESS-OBJECT, or the process is
     currently in the running state false is returned.


File: librep.info,  Node: Shell Commands,  Prev: Process Information,  Up: Processes

5.27.8 Executing Shell Commands
-------------------------------

Convenient shell invocatino is possible, with its I/O going to the same
places as the interpreter's.

 -- Function: system command
     Execute the shell command COMMAND synchronously, returning its
     exit status. An error will be signalled if the shell process could
     not be started.

     The `stdin', `stdout' and `stderr' streams of the shell are left
     as in the interpreter process.

     The subprocesses environment is copied from the current value of
     the `process-environment' variable.

   Note that the exit status is _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 (*note Synchronous Processes::).
Interrupt the interpreter, it will send progressively harder-to-ignore
signals to the child each interrupt, until it is eventually terminated.


File: librep.info,  Node: String Functions,  Next: utf-8,  Prev: Processes,  Up: The language

5.28 String Functions
=====================

 -- Function: translate-string string map
     Applies the MAP to each character in the STRING. 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 STRING contains the character `A', with ASCII code
     65, then it would be replaced by the 65th character in the string
     MAP.

     Note that the STRING really is modified, no copy is made

 -- Variable: upcase-table
     A `translate-string' compatible translation map to convert
     lowercase characters to uppercase characters.

 -- Variable: downcase-table
     A map to convert uppercase characters to lowercase.

 -- Variable: flatten-table
     A translation map to convert newline characters to spaces.

     (translate-string "Foo" upcase-table)
         => "FOO"

     (translate-string "Foo" downcase-table)
         => "foo"

 -- Function: complete-string template list #!optional ignore-case
     Return a string whose beginning matches the string TEMPLATE, and
     is unique in the set of all strings in LIST which also match
     TEMPLATE. If IGNORE-CASE is true, all matching ignores case of
     characters.

          (complete-string "foo" '("bar" "foobar" "forbarf" "foobat"))
              => "fooba"

 -- Function: string-head-eq string-1 string-2
     Returns t if STRING-2 matches the beginning of STRING-1.

          (string-head-eq "foobar" "foo")
              => t

          (string-head-eq "foo" "foobar")
              => ()

 -- Function: string-upper-case-p string
     Return true if STRING contains no lower case characters.

 -- Function: string-lower-case-p string
     Return true if STRING contains no upper case characters.

 -- Function: string-capitalized-p string
     Return true if the first character of STRING is upper case.

 -- Function: string-upcase string
     Return a new string, an upper case copy of STRING.

 -- Function: string-downcase string
     Return a new string, a lower case copy of STRING.

 -- Function: capitalize-string string
     Return a new string, a copy of STRING with the first character in
     upper case.

 -- Function: mapconcat function sequence separator
     Call FUNCTION for each member of SEQUENCE, concatenating the
     results. Between each pair of results, insert SEPARATOR.  Return
     the resulting string.

 -- Function: string->number string &optional radix
     Return the number represented by STRING. If RADIX is specified,
     the number is parsed from that base, otherwise base 10 is assumed.

 -- Function: number->string num &optional radix
     Return a string containing a printed representation of the number
     NUM. If RADIX is specified, print the number in that base,
     otherwise print it in base 10.


File: librep.info,  Node: utf-8,  Next: Regular Expressions,  Prev: String Functions,  Up: The language

5.29 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 `rep.util.utf8'.

 -- Function: utf8-string-length string
     Returns the number of characters of utf-8 encoded STRING.

 -- Function: utf8-substring string start #!optional end
     Returns the portion of STRING, encoded in utf-8, starting at
     character number START and ending at the character before END (or
     the end of the string if END is not given). All indices start at
     zero.


File: librep.info,  Node: Regular Expressions,  Next: Time and Date,  Prev: utf-8,  Up: The language

5.30 Regular Expressions
========================

Regular expressions (or "regexps") are a powerful method of matching
patterns in strings. Librep uses the `regexp(3)' implementation by
Henry Spencer, with some modifications that I have made. It comes with
this banner:

     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:

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

       2. The origin of this software must not be misrepresented, either
          by explicit claim or by omission.

       3. Altered versions must be plainly marked as such, and must not
          be misrepresented as being the original software.

* Menu:

* Regexp Syntax::               How to write regular expressions
* Regexp Functions::            How to use them


File: librep.info,  Node: Regexp Syntax,  Next: Regexp Functions,  Up: Regular Expressions

5.30.1 Regular Expression Syntax
--------------------------------

The syntax of a regular expression is as follows (this is adapted from
the manual page):

   A regular expression is zero or more "branches", separated by `|'.
It matches anything that matches one of the branches.

   A branch is zero or more "pieces", concatenated. It matches a match
for the first, followed by a match for the second, etc.

   A piece is an "atom" possibly followed by `*', `+', or `?'. An atom
followed by `*' matches a sequence of 0 or more matches of the atom. An
atom followed by `+' matches a sequence of 1 or more matches of the
atom. An atom followed by `?' 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 "range" (see below), `.' (matching any
single character), `^' (matching the null string at the beginning of
the input string), `$' (matching the null string at the end of the
input string), one of the strings `\s', `\S', `\w', `\W', `\d', `\D',
`\b', `\B', or a `\' followed by a single character (matching that
character), or a single character with no other significance (matching
that character).

   A "range" is a sequence of characters enclosed in `[]'. It normally
matches any single character from the sequence. If the sequence begins
with `^', it matches any single character _not_ from the rest of the
sequence. If two characters in the sequence are separated by `-', this
is shorthand for the full list of ASCII characters between them (e.g.
`[0-9]' matches any decimal digit). To include a literal `]' in the
sequence, make it the first character (following a possible `^'). To
include a literal `-', make it the first or last character.

   Also, any of the `*', `+' or `?' operators can be suffixed by a `?'
character (i.e. `*?', `+?', `??'). The meaning of the operator remains
the same but it becomes "non-greedy". This means that it will match the
_smallest_ number of characters satisfying the regular expression,
instead of the default behaviour which is to match the _largest_.

   The backslash-introduced atoms have the following meanings:

`\s'
     Match any whitespace character.

`\S'
     Match any non-whitespace character.

`\w'
     Match any alphanumeric or underscore character.

`\W'
     Match any non-(alphanumeric or underscore) character.

`\d'
     Match any numeric character.

`\D'
     Match any non-numeric character.

`\b'
     Match the null string between two adjacent `\w' and `\W'
     characters (in any order).

`\B'
     Match the null string that is not between two adjacent `\w' and
     `\W' characters.

Some example legal regular expressions could be:

`ab*a+b'
     Matches an `a' followed by zero or more `b' characters, followed by
     one or more `a' characters, followed by a `b'. For example,
     `aaab', `abbbab', etc...

`(one|two)_three'
     Matches `one_three' or `two_three'.

`^cmd_[0-9]+'
`^cmd_\d+'
     Matches `cmd_' followed by one or more digits, it must start at the
     beginning of the line.


File: librep.info,  Node: Regexp Functions,  Prev: Regexp Syntax,  Up: Regular Expressions

5.30.2 Regexp Functions
-----------------------

These functions are exported by the `rep.regexp' module.

 -- Function: quote-regexp string
     Return a version of STRING, such that when used as a regexp, it
     will match the original contents of STRING verbatim, and nothing
     else. This involves quoting regexp meta-characters.

          (quote-regexp "abc")
              => "abc"

          (quote-regexp "a+c")
              => "a\\+c"

 -- Function: string-match regexp string #!optional start ignore-case
     Returns true if the string STRING matches the regular expression
     REGEXP. The string matches if executing the regexp at _any_
     position in the string succeeds.

     When defined, START is the index of the first character to start
     matching at (counting from zero). When IGNORE-CASE is true the
     case of matched strings are ignored. Note that character classes
     are still case-significant.

          (string-match "ab+c" "abbbc")
              => t

          (string-match "ab+c" "xxxabbbcyyy")
              => t

 -- Function: string-looking-at regexp string #!optional start
          ignore-case
     Similar to `string-match', but only returns true if STRING matches
     REGEXP starting at the character at index START in the string (or
     the first character if START is undefined).

          (string-looking-at "ab+c" "abbbc" 0)
              => t

          (string-looking-at "ab+c" "xxxabbbcyyy" 0)
              => ()

          (string-looking-at "ab+c" "xxxabbbcyyy" 3)
              => t

 -- Function: match-start #!optional n
     Returns the position at which the N'th parenthesised expression
     started in the last successful regexp match. If 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.

          (string-match "x*(foo|bar)y" "xxxbary")
              => t

          (match-start 1)
              => 3

 -- Function: match-end #!optional n
     Similar to `match-start', but returns the position of the
     character following the matched item.

          (string-match "x*(foo|bar)y" "xxxbary")
              => t

          (match-end 1)
              => 6

   A common use of regular expressions is to match a string, then
replace certain portions of the string with other text.

 -- Function: expand-last-match template
     Expand the TEMPLATE substituting the parenthesised expressions
     from the most recent successfully matched regular expression.

     TEMPLATE may contain the following substitution-inducing escape
     sequences:

    `\0'
    `\&'
          Substitute the whole string matched by the last regexp

    `\N'
          Substitute the N'th parenthensised expression, where 1 <= N
          <= 9.

    `\\'
          Substitute a single backslash character.

          (string-match "x*(foo|bar)y" "xxxbary")
              => t

          (expand-last-match "test-\\1-ing")
              => "test-bar-ing"

     Note that double backslashes are required due to the read syntax of
     strings (*note Strings::).

     If you call `expand-last-match' after a failed match, the returned
     value is not predictable.

 -- Function: string-replace regexp template string
     Returns the string created by replacing all matches of REGEXP in
     STRING with the result of expanding TEMPLATE using the
     `expand-last-match' function.

          (string-replace "-" "_" "foo-bar-baz")
              => "foo_bar_baz"

          (string-replace "&(optional|rest)" "#!\\1" "(a &optional b &rest c)")
              => "(a #!optional b #!rest c)"

 -- Function: string-split regexp string
     Return a list of substrings of `string', each delimited by
     `regexp'.

          (string-split ":" "paths/are:often/seperated:by/colon")
              => ("paths/are/" "often/seperated" "by/colon")


File: librep.info,  Node: Time and Date,  Next: System Information,  Prev: Regular Expressions,  Up: The language

5.31 Time and Date
==================

This section describes how time and date values are handled in Librep.
These function are exported by the `rep.system' module:

* Menu:

* Timestamps::                  Internal representation of time
* Formatting Dates::            Creating strings from timestamps
* Parsing Dates::               Reading textual dates


File: librep.info,  Node: Timestamps,  Next: Formatting Dates,  Up: Time and Date

5.31.1 Timestamps
-----------------

As in UNIX, Librep measures time as the number of seconds since January
1st, 1970 (known as the "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).

 -- Function: current-time
     Return the number of seconds since the epoch, in a cons-cell.

          (current-time)
              => (10744 . 61063)

 -- Function: fix-time timestamp
     Ensure that the two parts of 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.

 -- Function: time-later-p timestamp-1 timestamp-2
     Returns true if TIMESTAMP-1 is later than TIMESTAMP-2.

   On the plus side, this scheme won't wrap around as quickly as UNIX's
`time_t' will ;-)

   The `rep.util.time' module also provides some functions for
manipulating timestamps:

 -- Function: time->seconds timestamp
     Convert TIMESTAMP to an integer, the number of seconds since the
     epoch that it represents.

 -- Function: seconds->time seconds
     Convert from an integer SECONDS to a timestamp object.

 -- Function: time- timestamp-1 timestamp-2
     Return the number of seconds difference between TIMESTAMP-1 and
     TIMESTAMP-2.

 -- Constant: seconds-per-day
     The number of seconds in a 24-hour day.


File: librep.info,  Node: Formatting Dates,  Next: Parsing Dates,  Prev: Timestamps,  Up: Time and Date

5.31.2 Formatting Dates
-----------------------

Given a timestamp value it is possible to format it as a string, in
many different formats.

 -- Function: current-time-string #!optional timestamp format
     Return a string defining TIMESTAMP according to the string FORMAT.
     If TIMESTAMP is undefined, the current time is used.

     The FORMAT string may include any of the formatting characters
     from the C library's `strftime(3)' function. If undefined a
     standard, fixed-width, format is used:

          (current-time-string)
              => "Wed Jun  2 18:07:53 1999"

     Some of the possible formatting substitutions include (this is
     copied from the GNU libc manual, *note (libc)Formatting Date and
     Time::):

    `%a'
          The abbreviated weekday name according to the current locale.

    `%A'
          The full weekday name according to the current locale.

    `%b'
          The abbreviated month name according to the current locale.

    `%B'
          The full month name according to the current locale.

    `%c'
          The preferred date and time representation for the current
          locale.

    `%d'
          The day of the month as a decimal number (range `01' to `31').

    `%H'
          The hour as a decimal number, using a 24-hour clock (range
          `00' to `23').

    `%I'
          The hour as a decimal number, using a 12-hour clock (range
          `01' to `12').

    `%j'
          The day of the year as a decimal number (range `001' to
          `366').

    `%m'
          The month as a decimal number (range `01' to `12').

    `%M'
          The minute as a decimal number.

    `%p'
          Either `am' or `pm', according to the given time value; or the
          corresponding strings for the current locale.

    `%S'
          The second as a decimal number.

    `%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.

    `%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.

    `%w'
          The day of the week as a decimal number, Sunday being `0'.

    `%x'
          The preferred date representation for the current locale, but
          without the time.

    `%X'
          The preferred time representation for the current locale, but
          with no date.

    `%y'
          The year as a decimal number, but without a century (range
          `00' to `99').

    `%Y'
          The year as a decimal number, including the century.

    `%Z'
          The time zone or name or abbreviation (empty if the time zone
          can't be determined).

    `%%'
          A literal `%' character.

          (current-time-string nil "%Y-%m-%d")
              => "1999-06-02"


File: librep.info,  Node: Parsing Dates,  Prev: Formatting Dates,  Up: Time and Date

5.31.3 Parsing Dates
--------------------

The `date' Lisp library provides rudimentary support for parsing date
and time descriptions to their individual components, and to
timestamps. Evaluate the form `(require 'date)' to load this library.

 -- Function: parse-date string #!optional start
     Returns a vector encoding the date described by STRING. If 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:

    `date-vec-day-abbrev'
          The abbreviated name of the day of the week.

    `date-vec-day'
          The numeric day of the month, counting from one.

    `date-vec-month-abbrev'
          The abbreviated name of the month.

    `date-vec-month'
          The numeric month of the year, counting from January equals
          one.

    `date-vec-year'
          The numeric year.

    `date-vec-hour'
          The numeric hour of the day.

    `date-vec-minute'
          The numeric minute of the hour.

    `date-vec-second'
          The numeric second of the minute.

    `date-vec-timezone'
          If true, a string defining the timezone.

    `date-vec-epoch-time'
          The timestamp (*note Timestamps::), including the effects of
          the timezone, if given.

          (current-time-string)
              => "Wed Jun  2 18:37:17 1999"

          (parse-date (current-time-string))
              => ["Wed" 2 "Jun" 6 1999 18 37 17 0 (10744 . 67037)]

          (parse-date "1999-06-02")
              => ["Tue" 2 "Jun" 6 1999 0 0 0 0 (10744 . 0)]

          (parse-date "June 6, 1999")
              => ["" 0 "Jun" 6 1999 0 0 0 0 (10742 . 0)]

          (aref (parse-date "June 6, 1999") date-vec-epoch-time)
              => (10742 . 0)

   XXX provide more information on accepted formats, outputs for
incomplete descriptions, etc...


File: librep.info,  Node: System Information,  Next: User Information,  Prev: Time and Date,  Up: The language

5.32 System Information
=======================

These definitions are all exported by the `rep.system' module.

 -- Variable: operating-system
     A symbol naming the current operating system. The only current
     option is `unix'.

 -- Function: 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)

 -- Variable: rep-build-id
     A string describing the environment under which Librep was built.
     This will always have the format `DATE by USER@HOST, for ARCH.'.

          rep-build-id
              => "Mon May 17 1999 by john@tizer.dcs.warwick.ac.uk, for sparc-sun-solaris2.6."

 -- Variable: rep-version
     A string describing the current release of Librep.

          rep-version
              => "1.0"


File: librep.info,  Node: User Information,  Next: Environment Variables,  Prev: System Information,  Up: The language

5.33 User Information
=====================

These functions are exported by the `rep.system' module.

 -- Function: user-login-name
     This function returns a string containing the login name of the
     user.

          (user-login-name)
              => "john"

 -- Function: user-full-name #!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 REAL-NAME is a string, it defines the name that will be
     returned by subsequent calls to this function.

          (user-full-name)
              => "John Harper"

 -- Function: user-home-directory #!optional user
     This function returns the home directory of the user whose login
     name is USER, or the current user if USER is undefined. The
     returned string will be as returned by `file-name-as-directory'
     (i.e. terminated by a `/' character under UNIX)

          (user-home-directory)
              => "/home/john/"


File: librep.info,  Node: Environment Variables,  Next: Command Line Options,  Prev: User Information,  Up: The language

5.34 Environment Variables
==========================

These functions are exported by the `rep.system' module.

 -- Function: getenv variable-name
     This function returns the value (a string) of the environment
     variable called VARIABLE-NAME. If the specified variable doesn't
     exist false is returned.

          (getenv "OSTYPE")
              => "Linux"

 -- Function: setenv variable-name new-value
     This function sets the value of the environment variable called
     VARIABLE-NAME to NEW-VALUE. NEW-VALUE can either be a string
     containing the new contents of the variable or false, in which
     case the environment variable is deleted.

 -- Function: unsetenv variable-name
     Deletes any variable in `process-environment' named VARIABLE-NAME.

   See also *Note Process Objects:: for the description of the
`process-environment' variable.


File: librep.info,  Node: Command Line Options,  Next: Timers,  Prev: Environment Variables,  Up: The language

5.35 Command Line Options
=========================

As noted earlier any unused command line arguments are made available
to scripts through the `command-line-args' variable (*note
Invocation::).

 -- Variable: command-line-args
     The list of unused command line arguments, in their original order.

   The `get-command-line-option' function may be used to scan this list
of arguments. The `rep.system' module exports this function.

 -- Function: get-command-line-option option #!optional requires-arg
     Returns t if OPTION was specified on the command line (OPTION is
     typically a phrase beginning with `--').

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

     (setq command-line-args '("--foo" "bar"))
         => ("--foo" "bar")
     (get-command-line-option "--foo" t)
         => "bar"
     command-line-args
         => ()

     (setq command-line-args '("--foo=bar"))
         => ("--foo=bar")
     (get-command-line-option "--foo" t)
         => "bar"
     command-line-args
         => ()


File: librep.info,  Node: Timers,  Next: Sleeping,  Prev: Command Line Options,  Up: The language

5.36 Asynchronous Timers
========================

The `rep.io.timers' module (*note 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 `recursive-edit' is currently in progress. A timer is
called between cycles of event loop.

 -- Function: make-timer function #!optional seconds milliseconds
     Create and return a new timer object. It will be set to call the
     Lisp function FUNCTION after SECONDS seconds plus MILLISECONDS
     milliseconds. FUNCTION will be called with a single argument, the
     timer object that has just fired.

     If both SECONDS and MILLISECONDS are undefined, or zero, the timer
     will be created but won't call FUNCTION.

     After the time interval has passed, and FUNCTION has been called,
     the timer _will not_ be restarted. Use the `set-timer' function to
     reset it.

 -- Function: delete-timer timer
     Prevent the timer object TIMER from calling the Lisp function
     associated with it. Use the `set-timer' function to reset it.

 -- Function: set-timer timer #!optional seconds milliseconds
     Reset the timer object TIMER. If either/both of SECONDS and
     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.


File: librep.info,  Node: Sleeping,  Next: Beeping,  Prev: Timers,  Up: The language

5.37 Sleeping
=============

 -- Function: sleep-for seconds #!optional milliseconds
     Pause for a SECONDS (plus the optional MILLISECONDS component)
     long period of time. Input becoming available will _not_ break the
     sleep (*note Process I/O::).

     This function is exported by the `rep.system' module.


File: librep.info,  Node: Beeping,  Next: i18n,  Prev: Sleeping,  Up: The language

5.38 Beeping
============

Use this function to attract the user's attention.

 -- Function: beep
     Ring a bell somewhere.


File: librep.info,  Node: i18n,  Next: Messages,  Prev: Beeping,  Up: The language

5.39 Internationalisation
=========================

Librep has support for internationalisation (or i18n) of text messages,
using the GNU `gettext' implementation (*note Overview: (gettext)Top.),
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 `gettext'. Import the `rep.i18n.gettext' module to
load them.

 -- Function: _ string
     Attempt to find a native language equivalent of STRING. If no
     equivalent is found the original string is returned.

     Note that this function is always defined, even if the `gettext'
     module hasn't been required. In this case it always returns the
     original string.

 -- Function: bindtextdomain domain directory
     Tell `gettext' that message catalogues for message domain DOMAIN
     (a string) can be found under the directory called DIRECTORY.

 -- Function: textdomain domain
     Note that any strings that are to be translated in the future
     (until the next call to `textdomain') are in the domain called
     DOMAIN (a string).

   The usual method of constructing message catalogue templates (`.pot'
files) is to run `xgettext' on the C source files of the program (that
have been annotated for i18n). librep provides the `rep-xgettext'
program to perform the same task for files of Lisp code.


File: librep.info,  Node: Messages,  Next: Debugging,  Prev: i18n,  Up: The language

5.40 Messages
=============

The `message' function will show the user a small message (typically no
more than a single column of text). In graphical applications it
_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 `stderr' stream, followed by a line
break.

 -- Function: message #!optional display-now
     Displays a one-line message, the string MESSAGE. If 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 `rep.system' module.


File: librep.info,  Node: Debugging,  Next: Tips,  Prev: Messages,  Up: The language

5.41 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 `Ctrl-Meta-f' and `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.

 -- Command: trace symbol
     This command marks the symbol 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 SYMBOL is prompted for.

 -- Command: untrace symbol
     The opposite of `trace'--unmarks the symbol.

 -- Function: break
     This function causes the debugger to be entered immediately. By
     putting the form `(break)' at suitable points in your program
     simple breakpoints can be created.

 -- Command: step form
     This function invokes the debugger to step through the form FORM.

     When called interactively FORM is prompted for.

 -- Function: backtrace #!optional stream
     Prints a description of the current Lisp function call stack to
     STREAM (or `standard-output' if STREAM is undefined).

          (backtrace (current-buffer))
               -| #<subr backtrace> ((current-buffer)) nil
               -| #<closure eval-and-print> ((backtrace (current-buffer))) t
               => t

     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.

   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,

`step'
`s'
     Step into the current form; this means that in a list form the
     debugger is used to evaluated each argument in turn.

`next'
`n'
     Continue evaluating forms normally until the next form at the
     current level is entered, then re-enter the debugger.

`continue'
`c'
     Continue execution normally. Note that this command is the one to
     use when an error has been trapped.

`return FORM'
`r FORM'
     Evaluate FORM then return this value as the result of the current
     form.

`print FORM'
`p FORM'
     Evaluate FORM, then print its value.

`form'
`f'
     Print the form being debugged.

`backtrace'
`b'
     Print a backtrace of the current Lisp call stack.

   Entering a null string repeats the previous `next', `step', or
`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 `=> '.

   Note that it is also possible to make certain types of errors invoke
the debugger immediately they are signalled, see *Note Errors::. Also
note that the debugger is unable to step through compiled Lisp code.


File: librep.info,  Node: Tips,  Prev: Debugging,  Up: The language

5.42 Tips
=========

This section of the manual gives advice about programming in Librep.

   For advice on getting the most out of the compiler, see *Note
Compilation Tips::.

* Menu:

* Comment Styles::              Different types of comments


File: librep.info,  Node: Comment Styles,  Up: Tips

5.42.1 Comment Styles
---------------------

As already described, single-line comments in Lisp are introduced by a
semi-colon (`;') character. By convention a different number of
semi-colons is used to introduce different types of comments,

`;'
     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 `Meta-;' can be used to insert a comment of this type.

     For example,

          (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

`;;'
     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,

          (let
              ((fname (concat file-name ?c)))
            ;; Be sure to remove any partially written dst-file.
            (when (file-exists-p fname)
              (delete-file fname)))

     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,

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

`;;;'
     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,

          ;;; Notes:

          ;;; Instruction Encoding
          ;;; ====================
          ;;; Instructions which get an argument (with opcodes of zero up to
          ...

`;;;;'
     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,

          ;;;; compiler.jl -- Simple compiler for Lisp files/forms

   If you adhere to these standards the indentation functions provide by
the Lisp mode will indent your comments to the correct depth.


File: librep.info,  Node: librep Internals,  Next: Function index,  Prev: The language,  Up: Top

6 librep Internals
******************

Sorry, it has little chance to be written. Some informations can be
found at `http://sawfish.wikia.com/wiki/Librep_Internals'.


File: librep.info,  Node: Function index,  Next: Variable index,  Prev: librep Internals,  Up: Top

Function index
**************

[index]
* Menu:

* *:                                     Arithmetic Functions.
                                                              (line  26)
* +:                                     Arithmetic Functions.
                                                              (line  12)
* -:                                     Arithmetic Functions.
                                                              (line  15)
* /:                                     Arithmetic Functions.
                                                              (line  29)
* /=:                                    Comparison Predicates.
                                                              (line  19)
* 1+:                                    Arithmetic Functions.
                                                              (line  46)
* 1-:                                    Arithmetic Functions.
                                                              (line  52)
* <:                                     Comparison Predicates.
                                                              (line  29)
* <=:                                    Comparison Predicates.
                                                              (line  32)
* =:                                     Comparison Predicates.
                                                              (line  16)
* >:                                     Comparison Predicates.
                                                              (line  22)
* >=:                                    Comparison Predicates.
                                                              (line  26)
* _:                                     i18n.                (line  16)
* abs:                                   Real Number Functions.
                                                              (line  11)
* accept-process-output:                 Process I/O.         (line  49)
* access-structures:                     Using Other Modules. (line  43)
* acos:                                  Mathematical Functions.
                                                              (line  28)
* active-processes:                      Process Objects.     (line 100)
* add-hook:                              Normal Hooks.        (line  15)
* all-threads:                           Creating Threads.    (line  31)
* alpha-char-p:                          Characters.          (line  33)
* alphanumericp:                         Characters.          (line  51)
* and:                                   Conditional Structures.
                                                              (line 132)
* append:                                Building Lists.      (line  68)
* apply:                                 Calling Functions.   (line  16)
* apropos:                               Obarrays.            (line  42)
* aref:                                  Array Functions.     (line  10)
* arrayp:                                Array Functions.     (line   7)
* aset:                                  Array Functions.     (line  22)
* asin:                                  Mathematical Functions.
                                                              (line  25)
* assoc:                                 Association Lists.   (line  29)
* assoc-regexp:                          Association Lists.   (line  62)
* assq:                                  Association Lists.   (line  37)
* atan:                                  Mathematical Functions.
                                                              (line  31)
* atom:                                  Cons Cells.          (line  44)
* autoload:                              Autoloading.         (line  20)
* backquote:                             Backquoting.         (line  18)
* backtrace:                             Debugging.           (line  56)
* beep:                                  Beeping.             (line   9)
* bindtextdomain:                        i18n.                (line  24)
* boundp:                                Void Variables.      (line  12)
* break:                                 Debugging.           (line  46)
* bytecodep:                             Compilation Functions.
                                                              (line  64)
* call-hook:                             Normal Hooks.        (line  43)
* call-process:                          Synchronous Processes.
                                                              (line  21)
* call-with-current-continuation:        Continuations.       (line  30)
* call-with-dynamic-root:                Thread Contexts.     (line  12)
* call/cc:                               Continuations.       (line  19)
* canonical-file-name:                   File Names.          (line  86)
* capitalize-string:                     String Functions.    (line  69)
* car:                                   Cons Cells.          (line  50)
* case:                                  Conditional Structures.
                                                              (line  84)
* catch:                                 Catch and Throw.     (line  56)
* cdr:                                   Cons Cells.          (line  60)
* ceiling:                               Real Number Functions.
                                                              (line  21)
* char-downcase:                         Characters.          (line  73)
* char-upcase:                           Characters.          (line  59)
* close-file:                            Destroying File Objects.
                                                              (line  12)
* closure-function:                      Closures.            (line  88)
* closure-name:                          Closures.            (line  57)
* closure-structure:                     Closures.            (line  61)
* closurep:                              Closures.            (line  54)
* compile-directory:                     Compilation Functions.
                                                              (line  32)
* compile-file:                          Compilation Functions.
                                                              (line  20)
* compile-form:                          Compilation Functions.
                                                              (line   9)
* compile-function:                      Compilation Functions.
                                                              (line  16)
* compile-module:                        Compilation Functions.
                                                              (line  46)
* complete-string:                       String Functions.    (line  36)
* concat:                                Strings.             (line  84)
* cond:                                  Conditional Structures.
                                                              (line  44)
* condition-case:                        Errors.              (line  57)
* cons:                                  Cons Cells.          (line  17)
* consp:                                 Cons Cells.          (line  24)
* continue-process:                      Process States.      (line  47)
* copy-file:                             Manipulating Files.  (line  20)
* copy-file-from-local-fs:               File Handlers.       (line  56)
* copy-file-to-local-fs:                 File Handlers.       (line  51)
* copy-sequence:                         Sequence Functions.  (line  26)
* copy-stream:                           Output Functions.    (line  18)
* cos:                                   Mathematical Functions.
                                                              (line  19)
* current-structure:                     Module Functions.    (line  14)
* current-thread:                        Creating Threads.    (line  26)
* current-time:                          Timestamps.          (line  15)
* current-time-string:                   Formatting Dates.    (line  10)
* datum-ref:                             Datums.              (line  23)
* datum-set:                             Datums.              (line  27)
* declare:                               Compiler Declarations.
                                                              (line  12)
* defconst:                              Defining Variables.  (line  44)
* define <1>:                            Definitions.         (line  47)
* define:                                Defining Variables.  (line  10)
* define-datum-printer:                  Datums.              (line  34)
* define-interface:                      Module Interfaces.   (line  22)
* define-macro:                          Definitions.         (line  60)
* define-record-discloser:               Records.             (line  73)
* define-record-type:                    Records.             (line  21)
* define-special-variable:               Defining Variables.  (line  40)
* define-structure:                      Module Definition.   (line  11)
* define-structures:                     Module Definition.   (line  49)
* defmacro:                              Defining Macros.     (line  14)
* defun:                                 Defining Named Functions.
                                                              (line  10)
* defvar:                                Defining Variables.  (line  17)
* defvar-setq:                           Defining Variables.  (line  36)
* delete:                                Modifying Lists.     (line  65)
* delete-directory:                      Manipulating Directories.
                                                              (line  10)
* delete-file:                           Manipulating Files.  (line   7)
* delete-from-queue:                     Queues.              (line  40)
* delete-if:                             Mapping Functions.   (line  39)
* delete-if-not:                         Mapping Functions.   (line  49)
* delete-timer:                          Timers.              (line  28)
* delq:                                  Modifying Lists.     (line  87)
* denominator:                           Rational Functions.  (line  12)
* dequeue:                               Queues.              (line  22)
* digit-char-p:                          Characters.          (line  47)
* directory-file-name:                   File Names.          (line  53)
* directory-files:                       Manipulating Directories.
                                                              (line  15)
* disassemble:                           Disassembly.         (line  15)
* do:                                    Looping Structures.  (line  30)
* documentation:                         Docstrings.          (line  10)
* elt:                                   Sequence Functions.  (line  44)
* enqueue:                               Queues.              (line  19)
* eq:                                    Equality Predicates. (line   7)
* eq-hash:                               Hash Tables.         (line  65)
* eql:                                   Equality Predicates. (line  39)
* equal:                                 Equality Predicates. (line  22)
* equal-hash:                            Hash Tables.         (line  69)
* error:                                 Errors.              (line  27)
* eval:                                  Evaluation.          (line  27)
* eval-after-load:                       Load Function.       (line  96)
* eval-when-compile:                     Compiler Declarations.
                                                              (line  95)
* evenp:                                 Numeric Predicates.  (line  31)
* exact->inexact:                        Rational Functions.  (line  15)
* exactp:                                Numeric Predicates.  (line  13)
* exp:                                   Mathematical Functions.
                                                              (line   9)
* expand-file-name:                      File Names.          (line  63)
* expand-last-match:                     Regexp Functions.    (line  80)
* expt:                                  Mathematical Functions.
                                                              (line  38)
* featurep:                              Obsolete Aspects of Modules.
                                                              (line  18)
* file-binding:                          Functions on File Objects.
                                                              (line  33)
* file-bound-stream:                     Functions on File Objects.
                                                              (line  41)
* file-directory-p:                      File Information.    (line  17)
* file-executable-p:                     File Information.    (line  29)
* file-exists-p:                         File Information.    (line  10)
* file-gid:                              File Information.    (line  36)
* file-handler-data:                     Functions on File Objects.
                                                              (line  47)
* file-modes:                            File Information.    (line  49)
* file-modes-as-string:                  File Information.    (line  54)
* file-modtime:                          File Information.    (line  65)
* file-name-absolute-p:                  File Names.          (line  12)
* file-name-as-directory:                File Names.          (line  43)
* file-name-directory:                   File Names.          (line  16)
* file-name-nondirectory:                File Names.          (line  30)
* file-newer-than-file-p:                File Information.    (line  70)
* file-nlinks:                           File Information.    (line  45)
* file-owner-p:                          File Information.    (line  32)
* file-readable-p:                       File Information.    (line  23)
* file-regular-p:                        File Information.    (line  13)
* file-size:                             File Information.    (line  42)
* file-symlink-p:                        File Information.    (line  20)
* file-uid:                              File Information.    (line  39)
* file-writable-p:                       File Information.    (line  26)
* filep:                                 File Objects.        (line  11)
* filter:                                Mapping Functions.   (line  65)
* find-symbol:                           Obarrays.            (line  33)
* fix-time:                              Timestamps.          (line  21)
* floor:                                 Real Number Functions.
                                                              (line  14)
* fluid:                                 Fluid Variables.     (line  22)
* fluid-set:                             Fluid Variables.     (line  26)
* flush-file:                            Functions on File Objects.
                                                              (line  29)
* format:                                Formatted Output.    (line   7)
* funcall:                               Calling Functions.   (line  12)
* functionp:                             Functions.           (line  25)
* garbage-collect:                       Garbage Collection.  (line  18)
* gcd:                                   Integer Functions.   (line  24)
* gensym:                                Creating Symbols.    (line  28)
* get:                                   Property Lists.      (line  30)
* get-command-line-option:               Command Line Options.
                                                              (line  17)
* get-output-stream-string:              Output Streams.      (line  37)
* get-structure:                         Module Functions.    (line  26)
* getenv:                                Environment Variables.
                                                              (line   9)
* has-type-p:                            Datums.              (line  31)
* if:                                    Conditional Structures.
                                                              (line  13)
* inexact->exact:                        Real Number Functions.
                                                              (line   7)
* inexactp:                              Numeric Predicates.  (line  16)
* input-stream-p:                        Streams.             (line  21)
* integerp:                              Numeric Predicates.  (line  19)
* intern:                                Interning.           (line  27)
* intern-structure:                      Module Functions.    (line  30)
* intern-symbol:                         Interning.           (line  39)
* interrupt-process:                     Signalling Processes.
                                                              (line   7)
* keywordp:                              Keyword Symbols.     (line  20)
* kill-process:                          Signalling Processes.
                                                              (line  10)
* last:                                  Accessing List Elements.
                                                              (line  35)
* lcm:                                   Integer Functions.   (line  28)
* length:                                Sequence Functions.  (line  10)
* let <1>:                               Looping Structures.  (line  64)
* let:                                   Local Variables.     (line  32)
* let*:                                  Local Variables.     (line  92)
* let-fluids:                            Fluid Variables.     (line  41)
* letrec:                                Local Variables.     (line 111)
* list:                                  Building Lists.      (line  35)
* list*:                                 Building Lists.      (line  48)
* listp:                                 Lists.               (line  15)
* load:                                  Load Function.       (line   7)
* local-file-name:                       File Names.          (line 100)
* log:                                   Mathematical Functions.
                                                              (line  12)
* logand:                                Bitwise Functions.   (line  20)
* logior:                                Bitwise Functions.   (line  30)
* lognot:                                Bitwise Functions.   (line  44)
* logxor:                                Bitwise Functions.   (line  37)
* lower-case-p:                          Characters.          (line  44)
* lsh:                                   Bitwise Functions.   (line  10)
* macroexpand:                           Macro Expansion.     (line  18)
* macroexpand-1:                         Macro Expansion.     (line  42)
* macrop:                                Macros.              (line  23)
* make-closure:                          Closures.            (line  85)
* make-datum:                            Datums.              (line  19)
* make-directory:                        Manipulating Directories.
                                                              (line   7)
* make-file-from-stream:                 File Handlers.       (line  68)
* make-fluid:                            Fluid Variables.     (line  18)
* make-guardian:                         Guardians.           (line  18)
* make-keyword:                          Keyword Symbols.     (line  13)
* make-list:                             Building Lists.      (line  54)
* make-mutex:                            Mutexes.             (line  12)
* make-obarray:                          Obarrays.            (line  26)
* make-process:                          Process Objects.     (line  55)
* make-queue:                            Queues.              (line  15)
* make-string:                           Strings.             (line  73)
* make-string-input-stream:              Input Streams.       (line  45)
* make-string-output-stream:             Output Streams.      (line  33)
* make-suspended-thread:                 Creating Threads.    (line  22)
* make-symbol:                           Creating Symbols.    (line  12)
* make-symlink:                          Manipulating Symlinks.
                                                              (line   7)
* make-table:                            Hash Tables.         (line  17)
* make-temp-name:                        File Names.          (line 116)
* make-thread:                           Creating Threads.    (line  15)
* make-timer:                            Timers.              (line  15)
* make-vector:                           Vectors.             (line  33)
* make-weak-table:                       Hash Tables.         (line  24)
* makunbound:                            Void Variables.      (line  15)
* mapc:                                  Mapping Functions.   (line  21)
* mapcar:                                Mapping Functions.   (line  11)
* mapconcat:                             String Functions.    (line  73)
* match-end:                             Regexp Functions.    (line  67)
* match-start:                           Regexp Functions.    (line  51)
* max:                                   Comparison Predicates.
                                                              (line  38)
* maybe-obtain-mutex:                    Mutexes.             (line  22)
* member:                                Accessing List Elements.
                                                              (line  45)
* memq:                                  Accessing List Elements.
                                                              (line  57)
* message:                               Messages.            (line  14)
* min:                                   Comparison Predicates.
                                                              (line  42)
* mod:                                   Integer Functions.   (line  19)
* modulo:                                Integer Functions.   (line  18)
* mutexp:                                Mutexes.             (line  15)
* nconc:                                 Modifying Lists.     (line  21)
* negativep:                             Numeric Predicates.  (line  37)
* not:                                   Conditional Structures.
                                                              (line 145)
* nreverse:                              Modifying Lists.     (line  53)
* nth:                                   Accessing List Elements.
                                                              (line  13)
* nthcdr:                                Accessing List Elements.
                                                              (line  25)
* null:                                  Lists.               (line  19)
* number->string:                        String Functions.    (line  82)
* numberp:                               Numbers.             (line  20)
* numerator:                             Rational Functions.  (line   9)
* obtain-mutex:                          Mutexes.             (line  18)
* oddp:                                  Numeric Predicates.  (line  28)
* open-file:                             Creating File Objects.
                                                              (line   7)
* open-structures:                       Using Other Modules. (line  42)
* or:                                    Conditional Structures.
                                                              (line 121)
* output-stream-p:                       Streams.             (line  24)
* parse-date:                            Parsing Dates.       (line  11)
* peek-char:                             Input Functions.     (line  11)
* positivep:                             Numeric Predicates.  (line  34)
* prin1:                                 Output Functions.    (line  40)
* prin1-to-string:                       Output Functions.    (line  51)
* princ:                                 Output Functions.    (line  58)
* print:                                 Output Functions.    (line  27)
* process-args:                          Process Objects.     (line  75)
* process-connection-type:               Asynchronous Processes.
                                                              (line  58)
* process-dir:                           Process Objects.     (line  83)
* process-error-stream:                  Process I/O.         (line  36)
* process-exit-status:                   Process Information. (line  20)
* process-exit-value:                    Process Information. (line  12)
* process-function:                      Process States.      (line  59)
* process-id:                            Process Information. (line   7)
* process-in-use-p:                      Process States.      (line  34)
* process-output-stream:                 Process I/O.         (line  24)
* process-prog:                          Process Objects.     (line  67)
* process-running-p:                     Process States.      (line  28)
* process-stopped-p:                     Process States.      (line  31)
* processp:                              Process Objects.     (line  17)
* prog1:                                 Sequencing Structures.
                                                              (line  34)
* prog2:                                 Sequencing Structures.
                                                              (line  42)
* progn:                                 Sequencing Structures.
                                                              (line  22)
* provide:                               Obsolete Aspects of Modules.
                                                              (line  22)
* put:                                   Property Lists.      (line  41)
* queue->list:                           Queues.              (line  32)
* queue-empty-p:                         Queues.              (line  26)
* queue-length:                          Queues.              (line  37)
* queuep:                                Queues.              (line  29)
* quote:                                 Quoting.             (line  34)
* quote-regexp:                          Regexp Functions.    (line   9)
* quotient:                              Integer Functions.   (line  10)
* random:                                Random Numbers.      (line   9)
* rassoc:                                Association Lists.   (line  50)
* rassq:                                 Association Lists.   (line  58)
* rationalp:                             Numeric Predicates.  (line  22)
* read <1>:                              The Lisp Reader.     (line  11)
* read:                                  Input Functions.     (line  36)
* read-char:                             Input Functions.     (line   7)
* read-chars:                            Input Functions.     (line  16)
* read-from-string:                      Input Functions.     (line  42)
* read-line:                             Input Functions.     (line  23)
* read-symlink:                          Manipulating Symlinks.
                                                              (line  10)
* realp:                                 Numeric Predicates.  (line  25)
* release-mutex:                         Mutexes.             (line  27)
* remainder:                             Integer Functions.   (line  13)
* remote-ftp-add-passwd:                 Remote Files.        (line  54)
* remove:                                Building Lists.      (line 113)
* remove-hook:                           Normal Hooks.        (line  29)
* remove-if:                             Mapping Functions.   (line  57)
* remove-if-not:                         Mapping Functions.   (line  58)
* remq:                                  Building Lists.      (line 117)
* rename-file:                           Manipulating Files.  (line  11)
* require:                               Using Other Modules. (line  41)
* reverse:                               Building Lists.      (line 121)
* round:                                 Real Number Functions.
                                                              (line  27)
* rplaca:                                Cons Cells.          (line  73)
* rplacd:                                Cons Cells.          (line  84)
* run-byte-code:                         Compilation Functions.
                                                              (line  52)
* seconds->time:                         Timestamps.          (line  40)
* seek-file:                             Functions on File Objects.
                                                              (line   7)
* sequencep <1>:                         Sequences.           (line  13)
* sequencep:                             Sequence Functions.  (line   7)
* set:                                   Setting Variables.   (line  26)
* set-closure-function:                  Closures.            (line  92)
* set-closure-structure:                 Closures.            (line  64)
* set-file-handler-data:                 Functions on File Objects.
                                                              (line  51)
* set-file-modes:                        File Information.    (line  61)
* set-input-handler:                     Functions on File Objects.
                                                              (line  58)
* set-interface:                         Module Interfaces.   (line  36)
* set-process-args:                      Process Objects.     (line  79)
* set-process-connection-type:           Asynchronous Processes.
                                                              (line  64)
* set-process-dir:                       Process Objects.     (line  87)
* set-process-error-stream:              Process I/O.         (line  40)
* set-process-function:                  Process States.      (line  63)
* set-process-output-stream:             Process I/O.         (line  28)
* set-process-prog:                      Process Objects.     (line  71)
* set-timer:                             Timers.              (line  32)
* setcar:                                Cons Cells.          (line  88)
* setcdr:                                Cons Cells.          (line  89)
* setenv:                                Environment Variables.
                                                              (line  17)
* setplist:                              Property Lists.      (line  56)
* setq:                                  Setting Variables.   (line  16)
* signal:                                Errors.              (line  14)
* signal-process:                        Signalling Processes.
                                                              (line  16)
* sin:                                   Mathematical Functions.
                                                              (line  16)
* sit-for:                               Process I/O.         (line  55)
* sleep-for:                             Sleeping.            (line   7)
* sort:                                  Modifying Lists.     (line  93)
* space-char-p:                          Characters.          (line  55)
* special-form-p:                        Special Forms.       (line  23)
* special-variable-p:                    Scope and Extent.    (line  63)
* sqrt:                                  Mathematical Functions.
                                                              (line  34)
* start-process:                         Asynchronous Processes.
                                                              (line  30)
* stderr-file:                           Creating File Objects.
                                                              (line  33)
* stdin-file:                            Creating File Objects.
                                                              (line  27)
* stdout-file:                           Creating File Objects.
                                                              (line  30)
* step:                                  Debugging.           (line  51)
* stop-process:                          Process States.      (line  40)
* streamp:                               Streams.             (line  18)
* string->number:                        String Functions.    (line  78)
* string-capitalized-p:                  String Functions.    (line  60)
* string-downcase:                       String Functions.    (line  66)
* string-equal:                          Strings.             (line 134)
* string-hash:                           Hash Tables.         (line  59)
* string-head-eq:                        String Functions.    (line  45)
* string-lessp:                          Strings.             (line 153)
* string-looking-at:                     Regexp Functions.    (line  37)
* string-lower-case-p:                   String Functions.    (line  57)
* string-match:                          Regexp Functions.    (line  20)
* string-replace:                        Regexp Functions.    (line 110)
* string-split:                          Regexp Functions.    (line 121)
* string-upcase:                         String Functions.    (line  63)
* string-upper-case-p:                   String Functions.    (line  54)
* string<:                               Strings.             (line 138)
* string=:                               Strings.             (line 120)
* stringp:                               Strings.             (line  70)
* structure:                             Module Definition.   (line  12)
* structure-accessible:                  Module Functions.    (line  40)
* structure-exports-p:                   Module Functions.    (line  45)
* structure-imports:                     Module Functions.    (line  39)
* structure-interface:                   Module Interfaces.   (line  33)
* structure-name:                        Module Functions.    (line  23)
* structurep:                            Module Functions.    (line  11)
* subr-name:                             Functions.           (line  41)
* subrp:                                 Functions.           (line  38)
* substring:                             Strings.             (line 104)
* symbol-hash:                           Hash Tables.         (line  62)
* symbol-name:                           Symbol Attributes.   (line  12)
* symbol-plist:                          Property Lists.      (line  50)
* symbol-value:                          Variables.           (line  16)
* symbolp:                               Symbols.             (line  12)
* system:                                Shell Commands.      (line  10)
* system-name:                           System Information.  (line  13)
* table-bound-p:                         Hash Tables.         (line  38)
* table-ref:                             Hash Tables.         (line  34)
* table-set:                             Hash Tables.         (line  42)
* table-size:                            Hash Tables.         (line  54)
* table-unset:                           Hash Tables.         (line  46)
* table-walk:                            Hash Tables.         (line  49)
* tablep:                                Hash Tables.         (line  11)
* tan:                                   Mathematical Functions.
                                                              (line  22)
* textdomain:                            i18n.                (line  28)
* thread-delete:                         Deleting Threads.    (line  12)
* thread-deleted-p:                      Deleting Threads.    (line  19)
* thread-forbid:                         Manipulating Threads.
                                                              (line  46)
* thread-join:                           Manipulating Threads.
                                                              (line  23)
* thread-permit:                         Manipulating Threads.
                                                              (line  49)
* thread-suspend:                        Manipulating Threads.
                                                              (line  13)
* thread-suspended-p:                    Manipulating Threads.
                                                              (line  38)
* thread-wake:                           Manipulating Threads.
                                                              (line  33)
* thread-yield:                          Manipulating Threads.
                                                              (line   7)
* threadp:                               Creating Threads.    (line  11)
* throw:                                 Catch and Throw.     (line  67)
* time-:                                 Timestamps.          (line  43)
* time->seconds:                         Timestamps.          (line  36)
* time-later-p:                          Timestamps.          (line  27)
* trace:                                 Debugging.           (line  35)
* translate-string:                      String Functions.    (line   7)
* truncate:                              Real Number Functions.
                                                              (line  24)
* unintern:                              Interning.           (line  50)
* unless:                                Conditional Structures.
                                                              (line  39)
* unsetenv:                              Environment Variables.
                                                              (line  23)
* untrace:                               Debugging.           (line  43)
* unwind-protect:                        Cleanup Forms.       (line  11)
* upper-case-p:                          Characters.          (line  40)
* useless-function:                      Descriptions.        (line  32)
* user-full-name:                        User Information.    (line  16)
* user-home-directory:                   User Information.    (line  26)
* user-login-name:                       User Information.    (line   9)
* utf8-string-length:                    utf-8.               (line  12)
* utf8-substring:                        utf-8.               (line  15)
* vector:                                Vectors.             (line  23)
* vectorp:                               Vectors.             (line  20)
* when:                                  Conditional Structures.
                                                              (line  30)
* while:                                 Looping Structures.  (line  85)
* with-fluids:                           Fluid Variables.     (line  30)
* with-internal-definitions:             Definitions.         (line  64)
* without-interrupts:                    Manipulating Threads.
                                                              (line  52)
* write:                                 Output Functions.    (line   7)
* zerop:                                 Numeric Predicates.  (line  40)


File: librep.info,  Node: Variable index,  Next: Concept index,  Prev: Function index,  Up: Top

Variable index
**************

[index]
* Menu:

* after-gc-hook:                         Garbage Collection.  (line  36)
* after-load-alist:                      Load Function.       (line  90)
* backtrace-on-error:                    Errors.              (line  49)
* command-line-args <1>:                 Rep execution.       (line  37)
* command-line-args:                     Command Line Options.
                                                              (line  11)
* date-vec-day:                          Parsing Dates.       (line  23)
* date-vec-day-abbrev:                   Parsing Dates.       (line  20)
* date-vec-epoch-time:                   Parsing Dates.       (line  48)
* date-vec-hour:                         Parsing Dates.       (line  36)
* date-vec-minute:                       Parsing Dates.       (line  39)
* date-vec-month:                        Parsing Dates.       (line  29)
* date-vec-month-abbrev:                 Parsing Dates.       (line  26)
* date-vec-second:                       Parsing Dates.       (line  42)
* date-vec-timezone:                     Parsing Dates.       (line  45)
* date-vec-year:                         Parsing Dates.       (line  33)
* debug-on-error:                        Errors.              (line  31)
* default-directory:                     File Names.          (line 127)
* dl-load-path:                          Load Function.       (line  79)
* downcase-table:                        String Functions.    (line  24)
* features:                              Obsolete Aspects of Modules.
                                                              (line  14)
* file-handler-alist:                    File Handlers.       (line  17)
* flatten-table:                         String Functions.    (line  27)
* format-hooks-alist:                    Formatted Output.    (line  93)
* garbage-threshold:                     Garbage Collection.  (line  22)
* grains-of-sand:                        Descriptions.        (line  10)
* idle-garbage-threshold:                Garbage Collection.  (line  27)
* lisp-lib-directory:                    Load Function.       (line  83)
* load-filename:                         Load Function.       (line  61)
* load-path:                             Load Function.       (line  65)
* max-lisp-depth:                        Evaluation.          (line  39)
* obarray:                               Obarrays.            (line  22)
* operating-system:                      System Information.  (line   9)
* print-escape:                          Output Functions.    (line  73)
* print-length:                          Output Functions.    (line  89)
* print-level:                           Output Functions.    (line  93)
* process-environment:                   Process Objects.     (line  91)
* remote-auto-backend-alist:             Remote Files.        (line  32)
* remote-default-backend:                Remote Files.        (line  36)
* remote-default-user:                   Remote Files.        (line  25)
* remote-ftp-anon-passwd:                Remote Files.        (line  69)
* remote-ftp-anon-users:                 Remote Files.        (line  65)
* remote-ftp-display-progress:           Remote Files.        (line  62)
* remote-ftp-show-messages:              Remote Files.        (line  58)
* remote-host-user-alist:                Remote Files.        (line  21)
* rep-build-id:                          System Information.  (line  18)
* rep-version:                           System Information.  (line  25)
* seconds-per-day:                       Timestamps.          (line  47)
* standard-error:                        Output Streams.      (line  54)
* standard-input:                        Input Streams.       (line  53)
* standard-output:                       Output Streams.      (line  50)
* upcase-table:                          String Functions.    (line  20)


File: librep.info,  Node: Concept index,  Prev: Variable index,  Up: Top

Concept index
*************

[index]
* Menu:

* Accessing list elements:               Accessing List Elements.
                                                               (line  6)
* Acknowledgment:                        Acknowledgment.       (line  6)
* Alists:                                Association Lists.    (line  6)
* Anonymous functions:                   Closures.             (line  6)
* Arguments, command line:               Command Line Options. (line  6)
* Arithmetic Functions:                  Arithmetic Functions. (line  6)
* Array functions:                       Array Functions.      (line  6)
* Arrays:                                Sequences.            (line  6)
* Association lists:                     Association Lists.    (line  6)
* Asynchronous processes:                Asynchronous Processes.
                                                               (line  6)
* Asynchronous timers:                   Timers.               (line  6)
* Atom:                                  Cons Cells.           (line 40)
* Autoload forms:                        Autoload Forms.       (line  6)
* Autoloading:                           Autoloading.          (line  6)
* Backquoting:                           Backquoting.          (line  6)
* Beeping:                               Beeping.              (line  6)
* Bitwise functions:                     Bitwise Functions.    (line  6)
* Block structured definitions:          Definitions.          (line  6)
* Boolean values:                        nil and t.            (line  6)
* Boolean values, predicate functions:   Predicate Functions.  (line  6)
* Bugs, patches, reporting:              Reporting bugs/patches/etc.
                                                               (line  6)
* Building lists:                        Building Lists.       (line  6)
* Calendar date and time:                Time and Date.        (line  6)
* Calling functions:                     Calling Functions.    (line  6)
* Catch and throw:                       Catch and Throw.      (line  6)
* Characters:                            Characters.           (line  6)
* Circular lists:                        Infinite Lists.       (line  6)
* Cleanup forms:                         Cleanup Forms.        (line  6)
* Closure:                               Closures.             (line  6)
* Command line options:                  Command Line Options. (line  6)
* Comment styles:                        Comment Styles.       (line  6)
* Comments:                              Read Syntax.          (line 13)
* Comparison predicates:                 Comparison Predicates.
                                                               (line  6)
* Compilation functions:                 Compilation Functions.
                                                               (line  6)
* Compilation tips:                      Compilation Tips.     (line  6)
* Compilation, disassembly of forms:     Disassembly.          (line  6)
* Compiled Lisp:                         Compiled Lisp.        (line  6)
* Compiler declarations:                 Compiler Declarations.
                                                               (line  6)
* Compiling macros:                      Compiling Macros.     (line  6)
* Conditional structures:                Conditional Structures.
                                                               (line  6)
* Cons cells:                            Cons Cells.           (line  6)
* Continuations:                         Continuations.        (line  6)
* Control Structures:                    Control Structures.   (line  6)
* Control structures, conditionals:      Conditional Structures.
                                                               (line  6)
* Control structures, looping:           Looping Structures.   (line  6)
* Control structures, non-local exits:   Non-Local Exits.      (line  6)
* Control structures, sequencing:        Sequencing Structures.
                                                               (line  6)
* Copying:                               Copying.              (line  6)
* Creating file objects:                 Creating File Objects.
                                                               (line  6)
* Creating symbols:                      Creating Symbols.     (line  6)
* Creating threads:                      Creating Threads.     (line  6)
* Data types:                            Data Types.           (line  6)
* Data types, datums:                    Datums.               (line  6)
* Data types, hash tables:               Hash Tables.          (line  6)
* Data types, queues:                    Queues.               (line  6)
* Data types, records:                   Records.              (line  6)
* Data types, summary of:                Types Summary.        (line  6)
* Date and time:                         Time and Date.        (line  6)
* Date and time, timestamps:             Timestamps.           (line  6)
* Dates, formatting as strings:          Formatting Dates.     (line  6)
* Dates, parsing:                        Parsing Dates.        (line  6)
* Datums:                                Datums.               (line  6)
* Debugging:                             Debugging.            (line  6)
* Declarations, compiler:                Compiler Declarations.
                                                               (line  6)
* Defining macros:                       Defining Macros.      (line  6)
* Defining named functions:              Defining Named Functions.
                                                               (line  6)
* Defining variables:                    Defining Variables.   (line  6)
* Definitions, block structured:         Definitions.          (line  6)
* Deleting threads:                      Deleting Threads.     (line  6)
* Descriptions:                          Descriptions.         (line  6)
* Destroying file objects:               Destroying File Objects.
                                                               (line  6)
* Disassembly:                           Disassembly.          (line  6)
* Distribution conditions:               Copying.              (line  6)
* Docstrings:                            Docstrings.           (line  6)
* Documentation Strings:                 Docstrings.           (line  6)
* Embedding librep:                      librep Internals.     (line  6)
* Environment variables:                 Environment Variables.
                                                               (line  6)
* Equality predicates:                   Equality Predicates.  (line  6)
* Errors:                                Errors.               (line  6)
* Escape sequences in strings:           Strings.              (line 21)
* Evaluating Lisp forms:                 Evaluation.           (line  6)
* Evaluation:                            Evaluation.           (line  6)
* Executing rep scripts implicitly:      Shebang invocation.   (line  6)
* Executing shell commands:              Shell Commands.       (line  6)
* Expansion, of macros:                  Macro Expansion.      (line  6)
* Exports, implicit:                     Implicit Exports.     (line  6)
* Features:                              Obsolete Aspects of Modules.
                                                               (line  6)
* File Handlers:                         File Handlers.        (line  6)
* File handlers, remote files:           Remote Files.         (line  6)
* File information:                      File Information.     (line  6)
* File names:                            File Names.           (line  6)
* File objects:                          File Objects.         (line  6)
* File objects, creating:                Creating File Objects.
                                                               (line  6)
* File objects, destroying:              Destroying File Objects.
                                                               (line  6)
* File objects, functions:               Functions on File Objects.
                                                               (line  6)
* Files:                                 Files.                (line  6)
* Files, closing:                        Destroying File Objects.
                                                               (line  6)
* Files, manipulating:                   Manipulating Files.   (line  6)
* Files, manipulating directories:       Manipulating Directories.
                                                               (line  6)
* Files, opening:                        Creating File Objects.
                                                               (line  6)
* Files, remote:                         Remote Files.         (line  6)
* Fluid variables:                       Fluid Variables.      (line  6)
* Formatted output:                      Formatted Output.     (line  6)
* Formatting dates:                      Formatting Dates.     (line  6)
* Forms, autoload:                       Autoload Forms.       (line  6)
* Forms, constant:                       Self-Evaluating Forms.
                                                               (line  6)
* Forms, function call:                  Function Call Forms.  (line  6)
* Forms, macro call:                     Macro Call Forms.     (line  6)
* Forms, self-evaluating:                Self-Evaluating Forms.
                                                               (line  6)
* Forms, special:                        Special Forms.        (line  6)
* Forms, symbol:                         Symbol Forms.         (line  6)
* Forms, variable:                       Symbol Forms.         (line  6)
* Function call forms:                   Function Call Forms.  (line  6)
* Function exits:                        Function Exits.       (line  6)
* Functions:                             Functions.            (line  6)
* Functions as hooks:                    Functions As Hooks.   (line  6)
* Functions on File Objects:             Functions on File Objects.
                                                               (line  6)
* Functions, anonymous:                  Closures.             (line  6)
* Functions, block structured:           Definitions.          (line  6)
* Functions, calling:                    Calling Functions.    (line  6)
* Functions, compilation:                Compilation Functions.
                                                               (line  6)
* Functions, defining:                   Defining Named Functions.
                                                               (line  6)
* Functions, descriptions of:            Descriptions.         (line  6)
* Functions, input:                      Input Functions.      (line  6)
* Functions, lambda expressions:         Lambda Expressions.   (line  6)
* Functions, loading:                    Load Function.        (line  6)
* Functions, local:                      Local Functions.      (line  6)
* Functions, mapping:                    Mapping Functions.    (line  6)
* Functions, output:                     Output Functions.     (line  6)
* Garbage collection:                    Garbage Collection.   (line  6)
* Garbage collection, guardians:         Guardians.            (line  6)
* Guardians:                             Guardians.            (line  6)
* Hash tables:                           Hash Tables.          (line  6)
* Hooks:                                 Hooks.                (line  6)
* Hooks, functions as:                   Functions As Hooks.   (line  6)
* Hooks, normal:                         Normal Hooks.         (line  6)
* Implicit Exports:                      Implicit Exports.     (line  6)
* Infinite lists:                        Infinite Lists.       (line  6)
* Input and output:                      Streams.              (line  6)
* Input functions:                       Input Functions.      (line  6)
* Input streams:                         Input Streams.        (line  6)
* Integer functions:                     Integer Functions.    (line  6)
* Integers:                              Numbers.              (line  6)
* Interactive enviroment:                Interactive environment.
                                                               (line  6)
* Interface, C:                          librep Internals.     (line  6)
* Internals:                             librep Internals.     (line  6)
* Internationalisation:                  i18n.                 (line  6)
* Interning:                             Interning.            (line  6)
* Introduction:                          Introduction.         (line  6)
* Introduction, Lisp:                    Rep's Lisp Introduction.
                                                               (line  6)
* Invocation:                            Invocation.           (line  6)
* Jade:                                  About.                (line  6)
* Keyword symbols:                       Keyword Symbols.      (line  6)
* Lambda expressions:                    Lambda Expressions.   (line  6)
* librep internals:                      librep Internals.     (line  6)
* librep Internals:                      librep Internals.     (line  6)
* Licence:                               Copying.              (line  6)
* Lisp forms, evaluating:                Evaluation.           (line  6)
* List forms:                            List Forms.           (line  6)
* List structure:                        List Structure.       (line  6)
* Lists:                                 Lists.                (line  6)
* Lists, accessing elements:             Accessing List Elements.
                                                               (line  6)
* Lists, association:                    Association Lists.    (line  6)
* Lists, building:                       Building Lists.       (line  6)
* Lists, circular:                       Infinite Lists.       (line  6)
* Lists, mapping:                        Mapping Functions.    (line  6)
* Lists, modifying:                      Modifying Lists.      (line  6)
* Load function:                         Load Function.        (line  6)
* Loading:                               Loading.              (line  6)
* Loading programs:                      Loading.              (line  6)
* Loading, on reference:                 Autoloading.          (line  6)
* Local functions:                       Local Functions.      (line  6)
* Local variables:                       Local Variables.      (line  6)
* Looping structures:                    Looping Structures.   (line  6)
* Macro call forms:                      Macro Call Forms.     (line  6)
* Macro expansion:                       Macro Expansion.      (line  6)
* Macros:                                Macros.               (line  6)
* Macros, backquoting:                   Backquoting.          (line  6)
* Macros, compiling:                     Compiling Macros.     (line  6)
* Macros, defining:                      Defining Macros.      (line  6)
* Manipulating files:                    Manipulating Files.   (line  6)
* Manipulating Symbolic Links:           Manipulating Symlinks.
                                                               (line  6)
* Manipulating threads:                  Manipulating Threads. (line  6)
* Manual notation:                       Notation.             (line  6)
* Mapping functions:                     Mapping Functions.    (line  6)
* Matching strings:                      Regexp Functions.     (line  6)
* Mathematical functions:                Mathematical Functions.
                                                               (line  6)
* Messages:                              Messages.             (line  6)
* Modifying lists:                       Modifying Lists.      (line  6)
* Modules:                               Modules.              (line  6)
* Modules, and special variables:        Modules and Special Variables.
                                                               (line  6)
* Modules, definition of:                Module Definition.    (line  6)
* Modules, interfaces:                   Module Interfaces.    (line  6)
* Mutexes:                               Mutexes.              (line  6)
* Mutual exclusion devices:              Mutexes.              (line  6)
* Names of files:                        File Names.           (line  6)
* News:                                  News.                 (line  6)
* nil and t:                             nil and t.            (line  6)
* Non-local exits:                       Non-Local Exits.      (line  6)
* Non-local exits, catch and throw:      Catch and Throw.      (line  6)
* Non-local exits, cleanup forms:        Cleanup Forms.        (line  6)
* Non-local exits, errors:               Errors.               (line  6)
* Non-local exits, function exits:       Function Exits.       (line  6)
* Normal hooks:                          Normal Hooks.         (line  6)
* Notation:                              Notation.             (line  6)
* Number, Read Syntax:                   Number Read Syntax.   (line  6)
* Numbers:                               Numbers.              (line  6)
* Numbers, arithmetic functions:         Arithmetic Functions. (line  6)
* Numbers, bitwise functions:            Bitwise Functions.    (line  6)
* Numbers, integer functions:            Integer Functions.    (line  6)
* Numbers, mathematical functions:       Mathematical Functions.
                                                               (line  6)
* Numbers, predicates on:                Numeric Predicates.   (line  6)
* Numbers, pseudo random:                Random Numbers.       (line  6)
* Numbers, rational functions:           Rational Functions.   (line  6)
* Numbers, real number functions:        Real Number Functions.
                                                               (line  6)
* Numbers, types:                        Types of Numbers.     (line  6)
* Numeric predicates:                    Numeric Predicates.   (line  6)
* Obarrays:                              Obarrays.             (line  6)
* Obsolete Aspects of Modules:           Obsolete Aspects of Modules.
                                                               (line  6)
* Options, command line:                 Command Line Options. (line  6)
* Output functions:                      Output Functions.     (line  6)
* Output streams:                        Output Streams.       (line  6)
* Output, formatted:                     Formatted Output.     (line  6)
* Parsing dates:                         Parsing Dates.        (line  6)
* Portability in Number:                 Types of Numbers.     (line  6)
* Predicate functions:                   Predicate Functions.  (line  6)
* Predicates on numbers:                 Numeric Predicates.   (line  6)
* Predicates, comparison:                Comparison Predicates.
                                                               (line  6)
* Predicates, equality:                  Equality Predicates.  (line  6)
* Predicates, type:                      Type Predicates.      (line  6)
* Printed representation:                Printed Representation.
                                                               (line  6)
* Process I/O:                           Process I/O.          (line  6)
* Process information:                   Process Information.  (line  6)
* Process objects:                       Process Objects.      (line  6)
* Process states:                        Process States.       (line  6)
* Processes:                             Processes.            (line  6)
* Processes, asynchronous:               Asynchronous Processes.
                                                               (line  6)
* Processes, signalling:                 Signalling Processes. (line  6)
* Processes, synchronous:                Synchronous Processes.
                                                               (line  6)
* Programs, loading:                     Loading.              (line  6)
* Property lists:                        Property Lists.       (line  6)
* Pseudo-random numbers:                 Random Numbers.       (line  6)
* Queues:                                Queues.               (line  6)
* Quoting:                               Quoting.              (line  6)
* Random numbers:                        Random Numbers.       (line  6)
* Rational functions:                    Rational Functions.   (line  6)
* Read syntax:                           Read Syntax.          (line  6)
* Read Syntax of Numbers:                Number Read Syntax.   (line  6)
* Read-eval-print loop:                  Interactive environment.
                                                               (line  6)
* Reader, the Lisp:                      The Lisp Reader.      (line  6)
* Reading directories:                   Manipulating Directories.
                                                               (line  6)
* Real number functions:                 Real Number Functions.
                                                               (line  6)
* Records:                               Records.              (line  6)
* Regexp functions:                      Regexp Functions.     (line  6)
* Regexp syntax:                         Regexp Syntax.        (line  6)
* Regexps:                               Regular Expressions.  (line  6)
* Regular expression syntax:             Regexp Syntax.        (line  6)
* Regular expressions:                   Regular Expressions.  (line  6)
* Remote files:                          Remote Files.         (line  6)
* rep, the Lisp dialect:                 The language.         (line  6)
* Reporting bugs, patches, etc:          Reporting bugs/patches/etc.
                                                               (line  6)
* Sawfish:                               About.                (line  6)
* Scope and extent:                      Scope and Extent.     (line  6)
* Scripts, executing implicitly:         Shebang invocation.   (line  6)
* Self-evaluating forms:                 Self-Evaluating Forms.
                                                               (line  6)
* Sequence functions:                    Sequence Functions.   (line  6)
* Sequences:                             Sequences.            (line  6)
* Sequences, cons cells:                 Cons Cells.           (line  6)
* Sequencing structures:                 Sequencing Structures.
                                                               (line  6)
* Setting variables:                     Setting Variables.    (line  6)
* Shebang invocation:                    Shebang invocation.   (line  6)
* Shell commands, executing:             Shell Commands.       (line  6)
* Signalling processes:                  Signalling Processes. (line  6)
* Sleeping:                              Sleeping.             (line  6)
* Special forms:                         Special Forms.        (line  6)
* Streams:                               Streams.              (line  6)
* Streams, formatted output:             Formatted Output.     (line  6)
* Streams, input:                        Input Streams.        (line  6)
* Streams, input functions:              Input Functions.      (line  6)
* Streams, output:                       Output Streams.       (line  6)
* Streams, output functions:             Output Functions.     (line  6)
* String functions:                      String Functions.     (line  6)
* String matching:                       Regexp Functions.     (line  6)
* Strings, escape sequences:             Strings.              (line 21)
* Style, comments:                       Comment Styles.       (line  6)
* Subprocesses:                          Processes.            (line  6)
* Symbol attributes:                     Symbol Attributes.    (line  6)
* Symbol forms:                          Symbol Forms.         (line  6)
* Symbol syntax:                         Symbol Syntax.        (line  6)
* Symbolic Links, manipulating:          Manipulating Symlinks.
                                                               (line  6)
* Symbols:                               Symbols.              (line  6)
* Symbols, creating:                     Creating Symbols.     (line  6)
* Symbols, interning:                    Interning.            (line  6)
* Symbols, keywords:                     Keyword Symbols.      (line  6)
* Symbols, obarrays:                     Obarrays.             (line  6)
* Symbols, property lists:               Property Lists.       (line  6)
* Synchronous processes:                 Synchronous Processes.
                                                               (line  6)
* Syntax of objects:                     Read Syntax.          (line  6)
* Syntax of regexps:                     Regexp Syntax.        (line  6)
* System information:                    System Information.   (line  6)
* t:                                     nil and t.            (line  6)
* The language:                          The language.         (line  6)
* The Lisp reader:                       The Lisp Reader.      (line  6)
* The REPL:                              Interactive environment.
                                                               (line  6)
* Thread contexts:                       Thread Contexts.      (line  6)
* Thread implementation notes:           Thread Implementation Notes.
                                                               (line  6)
* Threads:                               Threads.              (line  6)
* Threads, creating:                     Creating Threads.     (line  6)
* Threads, deleting:                     Deleting Threads.     (line  6)
* Threads, manipulating:                 Manipulating Threads. (line  6)
* Threads, mutexes:                      Mutexes.              (line  6)
* Time and date:                         Time and Date.        (line  6)
* Time, formatting as strings:           Formatting Dates.     (line  6)
* Time, parsing:                         Parsing Dates.        (line  6)
* Timers, asynchronous:                  Timers.               (line  6)
* Timestamps:                            Timestamps.           (line  6)
* Tips:                                  Tips.                 (line  6)
* Tips, comment styles:                  Comment Styles.       (line  6)
* Tips, compilation:                     Compilation Tips.     (line  6)
* Type predicates:                       Type Predicates.      (line  6)
* Types of Numbers:                      Types of Numbers.     (line  6)
* Types summary:                         Types Summary.        (line  6)
* User information:                      User Information.     (line  6)
* utf-8:                                 utf-8.                (line  6)
* Variables:                             Variables.            (line  6)
* Variables, defining:                   Defining Variables.   (line  6)
* Variables, descriptions of:            Descriptions.         (line  6)
* Variables, fluid:                      Fluid Variables.      (line  6)
* Variables, local:                      Local Variables.      (line  6)
* Variables, scope and extent of:        Scope and Extent.     (line  6)
* Variables, setting:                    Setting Variables.    (line  6)
* Variables, void:                       Void Variables.       (line  6)
* Void variables:                        Void Variables.       (line  6)



Tag Table:
Node: Top733
Node: Copying1436
Node: Introduction2830
Node: About3044
Node: Reporting bugs/patches/etc4396
Node: Acknowledgment5364
Node: News5972
Node: Invocation48367
Node: Rep execution48573
Node: Shebang invocation49884
Node: Interactive environment50950
Node: The language57171
Node: Rep's Lisp Introduction60276
Node: Features as Lisp60901
Node: nil and t61698
Node: The Lisp Reader63389
Node: Notation63976
Ref: Notation-Footnote-164702
Node: Descriptions65107
Node: Crash course for Elisp users67226
Node: Data Types73136
Node: Types Summary75228
Node: Read Syntax76834
Node: Printed Representation79853
Node: Equality Predicates80666
Node: Comparison Predicates82300
Node: Type Predicates84025
Node: Garbage Collection84624
Node: Numbers86267
Ref: Numbers-Footnote-187265
Node: Types of Numbers87348
Ref: Types of Numbers-Footnote-188778
Ref: Types of Numbers-Footnote-288902
Node: Numeric Predicates89035
Node: Number Read Syntax90204
Node: Arithmetic Functions92159
Node: Integer Functions93662
Node: Rational Functions94723
Node: Real Number Functions95160
Node: Mathematical Functions96112
Node: Bitwise Functions97288
Node: Random Numbers98703
Node: Characters99267
Node: Sequences101426
Node: Cons Cells102284
Node: Lists104860
Node: List Structure105982
Node: Building Lists108257
Node: Accessing List Elements113215
Node: Modifying Lists115133
Node: Association Lists119343
Node: Infinite Lists121573
Node: Vectors122913
Node: Strings124214
Node: Array Functions129243
Node: Sequence Functions130269
Node: Symbols131690
Node: Symbol Syntax132558
Node: Symbol Attributes133747
Node: Obarrays135026
Node: Creating Symbols137334
Node: Interning138381
Node: Property Lists140591
Node: Keyword Symbols142680
Node: Evaluation143364
Node: Symbol Forms145549
Node: List Forms146371
Node: Function Call Forms147484
Node: Macro Call Forms150041
Node: Special Forms150649
Node: Autoload Forms151678
Node: Self-Evaluating Forms152333
Node: Quoting153016
Node: Variables154396
Node: Local Variables155487
Node: Setting Variables160567
Node: Scope and Extent162315
Node: Void Variables164521
Node: Defining Variables165425
Node: Fluid Variables167573
Node: Functions170082
Node: Lambda Expressions171961
Ref: Lambda Expressions-Footnote-1177735
Ref: Lambda Expressions-Footnote-2177805
Node: Closures177957
Node: Defining Named Functions180994
Node: Predicate Functions182406
Node: Local Functions183379
Node: Calling Functions184015
Node: Mapping Functions184895
Node: Macros187634
Node: Defining Macros188797
Node: Backquoting190266
Node: Macro Expansion191768
Node: Compiling Macros193858
Node: Definitions195251
Node: Modules197819
Node: Informal Module Introduction198467
Node: Introduction on Modules201589
Node: Simple Module Definition202552
Node: Module and File203993
Node: Using Other Modules204755
Node: Modules and Special Variables206637
Node: Module Functions207668
Node: Implicit Exports209424
Node: Module Definition210085
Node: Module Interfaces212554
Node: Obsolete Aspects of Modules213885
Node: Control Structures214844
Node: Sequencing Structures215664
Node: Conditional Structures217454
Node: Looping Structures223473
Node: Non-Local Exits227135
Node: Catch and Throw227851
Node: Function Exits231431
Node: Cleanup Forms231926
Node: Errors233201
Node: Continuations236845
Node: Threads240304
Node: Thread Contexts240848
Node: Creating Threads241593
Node: Deleting Threads242913
Node: Manipulating Threads243772
Node: Mutexes245839
Node: Thread Implementation Notes246945
Node: Loading247665
Node: Load Function248478
Node: Autoloading252374
Node: Compiled Lisp253543
Node: Compilation Functions254989
Node: Compiler Declarations257441
Node: Compilation Tips262063
Node: Disassembly267287
Node: Docstrings269401
Node: Datums270377
Node: Queues271804
Node: Records273175
Node: Hash Tables276725
Node: Guardians279265
Ref: Guardians-Footnote-1281591
Node: Streams281832
Node: Input Streams283058
Node: Output Streams285264
Node: Input Functions287406
Node: Output Functions289464
Node: Formatted Output292585
Node: Hooks295915
Node: Functions As Hooks296557
Node: Normal Hooks297104
Node: Files299368
Node: File Names300610
Node: File Objects305170
Node: Creating File Objects305778
Node: Destroying File Objects307037
Node: Functions on File Objects307703
Node: File Information310125
Node: Manipulating Files312751
Node: Manipulating Directories313719
Node: Manipulating Symlinks314507
Node: File Handlers314968
Node: Remote Files319391
Node: Processes322722
Node: Process Objects323876
Node: Asynchronous Processes327787
Node: Synchronous Processes331245
Node: Process I/O334293
Node: Process States337405
Node: Signalling Processes339789
Node: Process Information341267
Node: Shell Commands342476
Node: String Functions343714
Node: utf-8346738
Node: Regular Expressions347418
Node: Regexp Syntax348633
Node: Regexp Functions351800
Node: Time and Date355985
Node: Timestamps356462
Node: Formatting Dates358109
Node: Parsing Dates361103
Node: System Information363219
Node: User Information364184
Node: Environment Variables365310
Node: Command Line Options366306
Node: Timers367545
Node: Sleeping369113
Node: Beeping369521
Node: i18n369734
Node: Messages371252
Node: Debugging372043
Node: Tips376292
Node: Comment Styles376610
Node: librep Internals379386
Node: Function index379653
Node: Variable index418814
Node: Concept index422822

End Tag Table
