summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/lisp-on-tex/README
blob: d3cec712624904b92e88224d945f5511ed1267c0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278

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