heol

Heol is a Lisp system for the Uxn virtual machine.

Heol is a 16-bit Lisp designed to fit comfortably inside Uxn with Varvara bindings. 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 flag is #t, otherwise returns the value of the third.

(if #t 
	123 
	456)

Arithmetic

Arithmetic operators apply on all the items of a list and follow the prefix notation:

(* (+ 1 3 5) 19) ; 171

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). One difference to be mindful of, is that and will not evaluate any argument after the first nil value. 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

Loops

We now have the parts needed to make a loop and print the state of each step.

(define count-down 
	(lambda (n)
		(if (< n 0)
			n 
			(and 
				(print n)
				(count-down (- n 1))))))

(count-down 9)

9876543210

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) difference of n1 to nk
• (* n1 n2 ... nk) product of n1 to nk
• (/ n1 n2 ... nk) quotient of n1 to nk
• (% n1 n2 ... nk) remainder of n1 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 ()
• (dotimes (i x) fn) run fn for x times
• (print x) print value of x, returns x
• (deo port x) send x to a Varvara port

• Source, Latest.
• Repository, Uxntal

incoming: functional oscean 2026 2025