Jitawa Manual
Installation
Download the latest version of Jitawa's
sources here.
To compile Jitawa, just run make in the directory of its
sources. The executable is called jitawa. You will need gcc
on a 64-bit x86 machine running Linux or Mac OS X.
Read-eval-print loop
Jitawa implements a simple read-eval-print loop. Jitawa
uses > as the prompt character; all other text is output
from Jitawa.
$ ./jitawa
Jitawa -- test version (built 2012-02-13 12:34:56)
Using default settings: heap[1Mcons], stack[1Mcons], symtable[64kB], code[1MB]
> '3
3
> (cons 5 '(6 7))
(5 6 7)
> (defun increment (n) (+ n 1))
NIL
> (increment 5)
6
Core language
Jitawa implements the following primitive Lisp operations
CONS CAR CDR CONSP NATP SYMBOLP EQUAL + - < SYMBOL-< IF OR
the following macros
AND LIST LET LET* COND FIRST SECOND THIRD FOURTH FIFTH DEFUN
and supports LAMBDA applications of the form:
((LAMBDA (v1 v2 ... vN) (...)) exp1 exp2 ... expN)
Note that all arithmetic is over natural numbers and the current
implementation does not support arbitrarily large numbers, e.g.
> (- 8 5)
3
> (- 5 8)
0
> (+ 1073741823 1)
ERROR: Arithmetic overflow.
Defining new functions
The user can define new functions using the special DEFUN
function. Recursion and mutual recursion are supported and tail-call
optimisation is done wherever possible. The following shows how
mutually recursive functions can be defined.
> (defun even (n) (if (equal n 0) t (odd (- n 1))))
NIL
> (defun odd (n) (if (equal n 0) nil (even (- n 1))))
NIL
This example shows that Jitawa accepts expressions that refer to functions
that have not yet been defined. It is not possible to overwrite
existing function definitions.
Special functions
DEFUN shown in the examples above is a macro which expands into a quoted application of DEFINE. For example, the above functions can equally well be defined using:
> (define 'even '(n) '(if (equal n 0) t (odd (- n 1))))
NIL
> (define 'odd '(n) '(if (equal n 0) nil (even (- n 1))))
NIL
This DEFINE function is one of four special functions:
DEFINE PRINT ERROR FUNCALL
The PRINT function takes any number of arguments, evaluates
each, prints them and then returns NIL, e.g.
> (print 5 (+ 6 7) (cons 2 3))
(PRINT 5 13 (2 . 3))
NIL
> (print (print 7) (print 8))
(PRINT 7)
(PRINT 8)
(PRINT NIL NIL)
NIL
The ERROR function does exactly the same except that it does
not return, instead it causes Jitawa to halt execution, e.g.
> (error 5 (+ 6 7) (cons 2 3))
(ERROR 5 13 (2 . 3))
ERROR: Runtime error caused by 'error' function.
The FUNCALL function allows dynamic function calls, e.g.
> (defun increment (n) (+ n 1))
NIL
> (funcall 'increment 8)
9
of course this can be made much more complicated
> (defun getname (n) (if (equal n 0) 'increment nil))
NIL
> (funcall (getname 0) 9)
10
Note that FUNCALL only works for user-defined functions.
Syntax
Jitawa allows numeric constants and symbols T
and NIL to be entered without quotes.
> 'T
T
> 'NIL
NIL
> T
T
> NIL
NIL
Jitawa performs only a few syntax check and those that it performs
(e.g. arity checking) attempt to emulate an interpreter-style
implementation, i.e. syntax errors are triggered only at runtime
(even though they are detected at compile time, i.e. at evaluation of
DEFINE). Example:
> (defun f (k n) (if (< 0 k) (car n) (car n n)))
NIL
> (f 8 '(a b))
A
> (f 0 '(a b))
ERROR: Runtime error caused by 'error' function.
Although all examples so far have used only single line input, input
expressions can span multiple lines. Example:
> '(1 2
> 3 4
> 5 6)
(1 2 3 4 5 6)
Jitawa implements an optimised abbreviation mechanism which allows for
very large inputs to be expressed and parsed efficiently. An example of these abbreviations:
> '(#1=(a #2=c) #2# #1# #1#)
((A C) C (A C) (A C))