%%
%% This is file `README'.
%%
%%  License: Modified BSD - see LICENSE file.
%%

===== LISP on TeX --- A LISP interpreter on TeX ======
Version 1.3
Author : HAKUTA Shizuya <hak7a3@live.jp>

==== Introduction ====
LISP on TeX is a LISP interpreter written only with TeX macros.
It works as a style file of LaTeX.
LISP on TeX adopts static scoping, dynamic typing, and eager evaluation.
We can program easily with LISP on TeX.

==== Files ====

README             : This file.
--------------------------------------------------------------------------------------
LICENCE            : About LICENCE.
--------------------------------------------------------------------------------------
lisp-on-tex.sty    : Main routine. (evaluator)
--------------------------------------------------------------------------------------
lisp-prim.sty      : Primitive functions. (Automatically loaded by lisp.sty)
--------------------------------------------------------------------------------------
lisp-read.sty      : Parser. (Automatically loaded by lisp.sty)
--------------------------------------------------------------------------------------
lisp-arith.sty     : Arithmetical functions. (Automatically loaded by lisp.sty)
--------------------------------------------------------------------------------------
lisp-string.sty    : Functions which manipulates strings. 
                   : (Automatically loaded by lisp.sty)
--------------------------------------------------------------------------------------
lisp-latexutil.sty : Utility functions for LaTeX.
                   : (Automatically loaded by lisp.sty)
--------------------------------------------------------------------------------------
lisp-util.sty      : Utility functions written with LISP on TeX.
                   : (Automatically loaded by lisp.sty)
--------------------------------------------------------------------------------------
lisp-mod-fpnum.sty : The module which enables us to use fixed point numbers.
                   : See the "Fixed Point Numbers" section in this document.
--------------------------------------------------------------------------------------
test.tex           : test code (using qstest.sty).
--------------------------------------------------------------------------------------
examples/*         : Example files. See the "Examples" section.
--------------------------------------------------------------------------------------
tug2013/*          : The slide and examples used on TUG2013. 
--------------------------------------------------------------------------------------
==== Usage ====
To use LISP on TeX, write

  \usepackage{lisp}

in the preamble of document. 

We can load module files
using \usepackage. For example, the command

  \usepackage{lisp-mod-fpnum}

loads the module of fixed point numbers. 

It the document, we can start LISP interpreter with \lispinterp.
For example,

  \lispinterp{(\texprint :1)}

outputs "1".

To get more detail, please read example files. 
It is the better way to know about LISP on TeX.

==== Examples ====
  * fact.tex
    -- Calculate the factorial function.
  * rocket.tex
    -- Show how to use "mutable" locations. 
  * fpnum-mandelbrot.tex
    -- Calculate the mandelbrot set.
    -- It takes a long long time to typeset.
  * showfont.tex
    -- Show glyphs of selected font.
    -- It works on XeLaTeX.
  * repl.tex
    -- The Read-Eval-Print Loop interpretor of lisp-on-tex.
  * nqueen.tex
    -- Calculate 5-queens problem.

==== Syntax ====
The syntax of LISP on TeX is the following;

<S-exp>   ::= <cons> 
            | <int> 
            | <string> 
            | <symbol>
            | <bool>
            | <nil>
            | <p-module>
            | <skip>
            | <dimen>
<cons>    ::= (<S-exp>+) | (<S-exp> . <S-exp>)
<int>     ::= :[TeX's integer]
<string>  ::= '[TeX's tokens]'
<symbol>  ::= [a control sequence]
<bool>    ::= /t | /f
<nil>     ::= ()
<p-module>::= +{<modname>::<tokens>}
<modname> ::= [TeX's tokens]
<tokens>  ::= [TeX's tokens]
<skip>    ::= @[TeX's skip]
<dimen>   ::= ![TeX's dimen]

==== Functions and Others ====
=== Special Forms ===
  * (\define \symbol <S-exp>) 
      -- Binds the evaluation result of <S-exp> to \symbol.
  * (\lambda <ptn> <S-exp>)
      -- Lambda abstraction. The bind pattern <ptn> has the following syntax;
  	     <ptn> ::= <symbol> | (<symbol>*) | (<symbol>+ . <symbol>)
  * (\quote <S-exp>) 
      -- Return <S-exp>.
  * (\lispif <S-exp 1> <S-exp 2> <S-exp 3>)
      -- Branch. The type of the evaluation result of <S-exp 1> must be bool.
  * (\defmacro \symbol <Lambda abstraction>)
      -- Define a macro.
  * (\begin <S-exp>+)
      -- Evaluate all arguments in a sequential order
         and returns the the evaluation result of the last argument.
  * (\defineM \symbol <S-exp>)
      -- Binds the evaluation result of <S-exp> to \symbol
         and the location which binds \symbol becomes "mutable".
  * (\setB \symbol <S-exp>)
      -- If location of which binds \symbol is "mutable", 
         the evaluation result of <S-exp> is stored in the location.

=== Evaluation ===
  * (\eval <S-exp>)
     -- Evaluate <S-exp> in the current environment.
  * (\apply <func> <list>)
     -- Evaluate (<func> <args>) where <list> = (<args>).

=== Types ===
  * (\intQ <S-exp>)
     -- If the evaluation result of <S-exp> is an integer, it returns /t.
         Otherwise, it returns /f.
     -- Likewise, \pairQ, \booleanQ, \symbolQ, \stringQ, \dimenQ, \skipQ,
         \nilQ, \funcQ, \closureQ, and \macroQ are defined.
  * (\listQ <S-exp>)
     -- Return /t iff <S-exp> is a nil or a cons cell.
        Otherwise, it returns /f. 
  * (\procedureQ <S-exp>)
     -- Return /t iff <S-exp> is a closure or a function (or a macro).
  * (\intTOstring <integer>)
     -- convert the argument into a string.

=== Arithmetical Functions ===
  * (\+ <S-exp>*)
     -- Addition.
     -- If, the argument is empty, it returns 0.
  * (\- <S-exp>+)
     -- Subtraction.
  * (\* <S-exp>*)
     -- Multiplication.
     -- If, the argument is empty, it returns 1.
  * (\/ <S-exp>+)
     -- Division.
  * (\mod <int 1> <int 2>)
     -- Modulus.
  * (\< <S-exp 1> <S-exp 2>)
     -- Let n be the evaluation result of <S-exp 1> and m be that of <S-exp 2>.
         If n < m, it returns /t. Otherwise, it returns /f.
  * (\> <S-exp 1> <S-exp 2>)
     -- Let n be the evaluation result of <S-exp 1> and m be that of <S-exp 2>.
         If n > m, it returns /t. Otherwise, it returns /f.
  * (\leq <int 1> <int 2>)
     -- Return (<int 1> <= <int 2>)
  * (\geq <int 1> <int 2>)
     -- Return (<int 1> >= <int 2>)
  * (\isZeroQ <int>)
     -- Return (<int> == 0)
  * (\positiveQ <int>)
     -- Return (<int> > 0)
  * (\negativeQ <int>)
     -- Return (<int> < 0)
  * (\max <int 1> <int 2> ... )
     -- Return the max value of the arguments
  * (\min <int 1> <int 2> ... )
     -- Return the minimal value of the arguments

=== Manipulation of Strings ===
  * (\concat <string 1> <string 2>)
     -- Concatenate two strings.
  *  (\group <string>)
     -- Grouping.
     -- If <string> is 'foo\bar{baz}', it returns '{foo\bar{baz}}'.
  * (\ungroup <string>)
     -- Ungrouping.
     -- If <string> is '{foo\bar{baz}}', it returns 'foo\bar{baz}'.
  * (\expand <string>)
     -- Expand macros in string.

=== Manipulation of Cons Cells ===
  * (\cons <S-exp 1> <S-exp 2>)
     -- Create a cons cell: the CAR of the cell is the evaluation result of
         <S-exp 1> and the CDR of the cell is  the evaluation result of
         <S-exp 2>.
  * (\car <cons>)
     -- Get CAR part of the argument.
  * (\cdr <cons>)
     -- Get CAR part of the argument.
  * (\length <list>)
     -- If the argument is "list", count the length of the argument.
     -- We define the term "list" as following;
           - The value nil.
           - A cons cell whose CDR is "list".
  * (\nth <list> <int>)
     -- Get the <int>-th element of the <list>.
     -- The numbering starts from 0. 

=== Logical Functions ===
  * (\and <bool 1> <bopl 2> ...)
  * (\or <bool 1> <bopl 2> ...)
  * (\not <bool>)

=== Misc ===
  * (\= <S-exp 1> <S-exp 2>)
     -- If the evaluation result of <S-exp 1> equals that of <S-exp 2>,
        it returns /t. Otherwise, it returns /f.
  * (\print <S-exp>)
     -- Write the evaluation result of <S-exp> as LISP on TeX form.
  * (\texprint <S-exp>)
     -- Write the evaluation result of <S-exp> as useful form in TeX.
  * (\immediatewrite)
     -- Flush the output buffer immediately.
     -- It may brake the evaluation routine.
  * (\message <str>)
     -- Write <str> to console.
  * (\map <proc> <list 1> <list 2> ...)
     -- Mapping function like Scheme's map.
  * (\let <bindings> <body>)
     -- Let bindings.
  * (\letM <bindings> <body>)
     -- Let bindings (mutable).
  * (\letrec <bindings> <body>)
     -- Let bindings (recursive and mutable).
==== Fixed Point Numbers ====
  * +{fpnum::<fixed point number>}
     -- Create an fixed point number.
  * (\fpplus <S-exp>*)
     -- Addition.
     -- If, the argument is empty, it returns 0.0.
  * (\fpmunus <S-exp>+)
     -- Subtraction.
  * (\fpmul <S-exp>*)
     -- Multiplication.
     -- If, the argument is empty, it returns 1.0.
  * (\fplt <S-exp 1> <S-exp 2>)
     -- Let n be the evaluation result of <S-exp 1> and m be that of <S-exp 2>.
         If n < m, it returns /t. Otherwise, it returns /f.
==== Continuations ====
  * (\callOCC <closure>)
     -- One shot continuations.
     -- It calls (<closure> c) where c is the current continuation.

==== CHANGELOG ====
  * Jul. 12, 2014 : 1.3
     -- Add one shot continuations.
     -- Add some arithmetical functions.
     -- Debug environment.
  * Jan. 03, 2014 : 1.2
     -- Added TUG2013's examples.
     -- Improved the performance.
  * Aug. 10, 2013 : 1.1
     -- Added \letrec and \expand.
     -- debug
  * Mar. 04, 2013 : 1.0