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))
Last updated 13 February 2012. Copyright Magnus Myreen 2011-2012.