This is Edition 1.0, last updated 27 November 1999, of The librep Manual, for librep, Version 0.8.

Copyright 1999 John Harper.

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

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

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

This is Edition 1.0 of its documentation, last updated 27 November 1999 for librep version 0.8.

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 see (emacs)Copying). I reserve the right to use a different licence in future releases.

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.

The only parts of librep which are not my own work are as follows:

  * Henry Spencer's regexp implementation, though I have made 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 internalized message catalogues.

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

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

librep is a dialect of Lisp, originally developed for embedding in other applications, but also suitable for general use. It was originally written to be mostly-compatible with Emacs Lisp, although there is no intention of having the two languages fully compatible. The main difference between the two dialects is that rep is lexically scoped and only has a single namespace.

librep started out as part of a text editor I wrote, which gradually warped into being an Emacs-clone as more features were added. I got so used to writing code in Lisp, it seemed a good idea to spin the Lisp core of the editor into it's own package. Maybe I should just have learned Common Lisp or Scheme, but there's something about re-inventing wheels...

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

Some of the features of librep are:

  * Contains its own byte-compiler and virtual machine

  * Lexically scoped (with dynamically scoped special variables)

  * Most ``standard'' Emacs Lisp functions, with some others from Common Lisp

  * Mostly-Perl-like regular expressions, including \s, \S, \w, \W, \d, \D, \b, \B, classes and ??, ?*, ?+ (non-greedy) operators (but none of the curly-brace quantifiers, and no matching of already-remembered expressions)

  * ``Virtual'' file handling, with FTP and rcp backends. Also supports tilde-expansion and read-only access to tar archives

  * Self-documenting

  * Support for executing untrusted code in a controlled environment

  * Spawn UNIX subprocesses (synchronously and asynchronously) with full control over all standard I/O (separate stdout and stderr)

  * Supports dynamically loaded shared libraries (a.k.a. ``plugins'')

  * Extensible type system (i.e. dynamically loaded libraries can define new types)

  * Extensible ``stream''-based input/output system, with many different stream types

  * Designed for embedding within other applications, or as a stand-alone interpreter

  * Separately available are GTK+ and MySQL bindings, included are SDBM and gettext bindings

     [file news.texi not included]

Invocation
**********

The rep program may be used to launch the stand-along librep environment:

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

Where REP-OPTIONS may be any of the following:

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

--version
     Print the current version number and exit

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

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

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

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

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

-q
     Terminate the Lisp process and exit.

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

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

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

Implicitly Interpreting rep Scripts
...................................

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

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

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

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

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

     ;; Lisp code follows...

     [file lang.texi not included]

     [file interface.texi not included]

Reporting bugs
**************

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.

To help me fix any bugs found 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 john@dcs.warwick.ac.uk.