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

   Copyright 1999-2000 John Harper.

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

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

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

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 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 (see Regular Expressions).

   For example, there is a convention under Unix that a user's home
directory can be accessed via the file name `~', even though there is
no such support from the operating system itself. So a file handler can
be (and has been) written that recognises all file names starting with
a tilde, translating them to the actual file in the file system.

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

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.

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.

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 (see Output Streams), all data
     which the subprocess outputs to its `stdout' channel is copied to
     this output stream. See Process I/O.

"Error stream"
     A normal Lisp output stream (see 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. See Process I/O.

"State change function"
     A Lisp function, called each time the state of the subprocess
     being run on the object changes. See 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 (see 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 (see
     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.

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

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.

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

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.

   See Streams.

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.

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.

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.

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.

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.

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 (see Strings).

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

Time and Date
=============

   This section describes how time and date values are handled in
`librep'.

Timestamps
----------

   As in UNIX, `librep' measures time as the number of seconds since
January 1st, 1970 (known as the "epoch"). For historical reasons rep
stores timestamps 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).

   These function are exported by the `rep.system' module:

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

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, see Formatting Date and Time (libc)):

    `%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"

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

Internationalisation
====================

   `librep' has support for internationalisation (or i18n) of text
messages, using the GNU `gettext' implementation (see Overview (gettext)),
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.

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"

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/"

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 Process Objects for the description of the
`process-environment' variable.