\input texinfo  @c -*-Texinfo-*-
@setfilename librep.info
@settitle librep Manual
@footnotestyle end

@ifinfo
@dircategory Programming Languages
@direntry
* librep: (librep).		``Rep'' lisp language
@end direntry

This is @cite{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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

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.
@end ifinfo

@titlepage
@title librep
@subtitle A LISP extension language
@author John Harper
@page
@vskip 0pt plus 1filll
Copyright @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.
@end titlepage

@node Top, Copying, (dir), (dir)

@ifinfo
This document describes @code{librep} Lisp dialect.
@end ifinfo

@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
@end menu


@node Copying, Introduction, Top, Top
@chapter Copying
@cindex Copying
@cindex Distribution conditions
@cindex Licence

@code{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 @file{COPYING} in the distribution (or
@pxref{(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:

@itemize @bullet
@item
Henry Spencer's @code{regexp} implementation, with many modifications.
This is distributed under the terms of his copyright, see the file
@file{src/README.regexp} in the distribution.

@item
The public domain @code{sdbm} database library by Ozan Yigit.

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

@item
The GNU @code{gettext} implementation for internationalized message
catalogues.
@end itemize

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.

@node Introduction, News, Copying, Top
@chapter Introduction
@cindex Introduction

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

@node About, Reporting bugs/patches/etc, , Introduction
@section About
@cindex Sawfish
@cindex Jade

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

@noindent
Maintainer until Aug 2008: John Harper@*
Maintainer since Aug 2008: Christopher Bratusek

For more see: @url{http://sawfish.wikia.com/}.

For compilation instructions, read @file{README}.

For Lisp features, see @xref{Rep's Lisp Introduction}.

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


Original introduction by John Harper:

@code{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 @code{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.

@code{rep} stands for ``Read, Eval, Print'', the three main components of
any Lisp system.

@node Reporting bugs/patches/etc, Acknowledgment , About, Introduction
@section Reporting bugs/patches/etc
@cindex Reporting bugs, patches, etc
@cindex Bugs, patches, reporting

Known bugs are listed in the file @file{TODO}.

If the @code{librep} interpreter crashes it's probably a bug (unless
you're using the @code{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@dots{}

Please send any bug reports to the mailing list:
@email{sawfish-list@@gnome.org}.

To make a patch, please use @code{git diff} or @code{diff -u}.

@node Acknowledgment, , Reporting bugs/patches/etc, Introduction
@section Acknowledgment
@cindex Acknowledgment
Thanks to:

@itemize
@item Henry Spencer for his excellent regexp matcher

@item Ozan Yigit for SDBM

@item Rick Sladkey for the Emacs backquote implementation

@item Jamie Zawinski for the Emacs peephole optimiser patterns

@item Yukihiro Nakai for the first rep-gettext implementation

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

@item Aron Griffis for porting to Tru64

@item numerous other people for bug-reports and patches
@end itemize

@node News, Invocation, Introduction, Top

@include news.texi

@node Invocation, The language, News, Top
@chapter Invocation
@cindex Invocation

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

@node Rep execution, Shebang invocation, , Invocation
@section Rep execution

Call @code{rep} program to launch a stand-alone @code{librep}
environment:

@example
usage: rep [@var{rep-options}@dots{}] [@var{script} [@var{script-options}@dots{}]
@end example

@noindent
Where @var{rep-options} may be any of the following:

@table @samp
@item --version
Print the current version number and exit

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

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

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

@item -f @var{function}
Invoke the Lisp function @var{function} (with no arguments)

@item -l @var{file}
Try to load the Lisp file @var{file}, this is equivalent to evaluating
the form @samp{(load "@var{file}")}.

@item -q
Terminate the Lisp process and exit.
@end table

@vindex command-line-args
If @var{file} is given, it names the Lisp file to load, and
@samp{--batch-mode} is implied. Any @var{script-options} will be made
available to the script in the @code{command-line-args} variable.
See @xref{Command Line Options}.

After any arguments have been processed, it enters the interactive
environment, unless @samp{--batch-mode} was specified. See
@pxref{Interactive environment}.

@node Shebang invocation, Interactive environment, Rep execution, Invocation
@section Shebang invocation
@cindex Shebang invocation
@cindex Executing @code{rep} scripts implicitly
@cindex Scripts, executing implicitly

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

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

To work around this problem @code{rep} supports a slightly different
method of invocation; first look at this example:

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

;; Lisp code follows@dots{}
@end example

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

@node Interactive environment, , Shebang invocation, Invocation
@include repl.texi

@node The language, librep Internals, Invocation, Top
@include lang.texi


@node librep Internals, Function index, The language, Top
@include interface.texi


@node Function index, Variable index, librep Internals, Top
@unnumbered Function index

@printindex fn


@node Variable index, Concept index, Function index, Top
@unnumbered Variable index

@printindex vr


@node Concept index, , Variable index, Top
@unnumbered Concept index

@printindex cp

@contents
@bye