Heol is a Lisp system for the Uxn virtual machine.

Heol is a 16-bit experimental Lisp inspired by TinyLisp and designed to be embedded inside of Uxn applications. It's currently under development.

Playground

Execution consists of reducing expressions, atoms return their value, lists are treated as function applications where the first element is a function name and the rest, arguments. Arguments are evaluated before being passed to the function.

Lists

The (cons value list) procedure constructs pairs, the (car list) procedure extracts the first elements of the list, and the (cdr list) procedure extracts the rest.

(cons 'a '(b c)) ; (a b c)
(car '(a b c)) ; a
(cdr '(a b c)) ; (b c)

Logic

The (eq? a b) procedure results in a flag either #t or () provided that the values of the expressions being compared are both atoms, and either they are both the same number, or they are both the same symbol:

(eq? 'a 'a) ; #t
(eq? 'a 'b) ; ()

Given three expressions, the (if flag when-true else) returns the value of the second if the value of the expression test is #t, otherwise returns the value of the third.

(if #t 
	123 
	456)

Arithmetic

Arithmetic operators follows the prefix notation:

(* (+ 3 5) 19) ; 152

Procedures

A (lambda args exp) expression evaluates to a procedure. The environment which is in effect when a lambda expression is evaluated is enclosed in the newly created procedure, this is referred to as a closure. Given an expression, the (quote exp) procedure returns that expression as a value.

((lambda (x) (* x x)) 3) ; 9

The (define name exp) expression binds an expression to a name, making it possible to utilize that reference throughout the code.

(define double
	(lambda (x) (+ x x)))

(double 5)  ; 10

Sequencing operations

Heol does not have an explicit way of sequencing reduction(progn, begin, etc..) instead it uses (and x1 x2 ... xk), which returns the non-nil value. One difference to be mindful of, is that and will not evaluate any argument after the first one that returns false. This can still be an efficient way, for example, of printing a value and returning another.

(and
	(print 'hello)
	42) ; Prints "Hello", but returns 42

Programs

If we put it all together now:

(define fac 
	(lambda (n)
		(if (< n 2)
			1 
			(* n (fac (- n 1))))))

(print (fac 5)) ; 120

Summary

• (eval x) return evaluated x (such as when x was quoted)
• (quote x) special form, returns x unevaluated "as is"
• (cons x y) construct pair (x . y)
• (car p) car of pair p
• (cdr p) cdr of pair p
• (if x y z) if x is non-() then y else z
• (let* (v1 x1) (v2 x2) ... y) binds each variable vi to xi to evaluate y
• (lambda v x) construct a closure
• (define v x) define a named value globally
• (+ n1 n2 ... nk) sum of n1 to nk
• (- n1 n2 ... nk) n1 minus sum of n2 to nk
• (* n1 n2 ... nk) product of n1 to nk
• (/ n1 n2 ... nk) n1 divided by the product of n2 to nk
• (< n1 n2) #t if n1<n2, otherwise ()
• (eq? x y) #t if x equals y, otherwise ()
• (pair? x) #t if x is a non-empty list, a cons cell or closure
• (or x1 x2 ... xk) first x that is not (), otherwise ()
• (and x1 x2 ... xk) last x if all x are not (), otherwise ()
• (not x) #t if x is (), otherwise ()
• (print x) print value of x, returns x

• View Sources, Uxntal.
• Repository, Uxntal

incoming: functional 2025