- A brief introduction to using this lisp.
- Getting started setting variables, defining functions, etc.
- A list of primitives we have implemented.
- This describes the functions we support, whether implemented in lisp or golang.
- For example
(car),(cdr),(file:lines),(shell), etc.
If you have the yal repository cloned locally then you should be able to build and install in the standard way:
$ go build .
$ go install .If you don't have the repository installed, but you have a working golang toolset then installation should be as simple as:
$ go install github.com/skx/yal@latestIf neither of those options suit, you may download the most recent binary from our release page.
Once installed there are two ways to execute code:
- By specifying an expressions on the command-line:
yal -e '(print (os))'
- By passing the name of a file containing lisp code to read and execute:
yal test.lisp
The yal interpreter allows (optional) documentation to be attached to functions, both those implemented in golang and those written in lisp, there is another command-line flag to dump that information from the standard library and built-in functions:
yal -h- Shows all functions which contain help-text, in sorted order.
- Examples are included where available.
A reasonable amount of sample code can be found in the various included examples:
- test.lisp shows many things.
- fibonacci.list calculate the first 25 numbers of the Fibonacci sequence.
- fizzbuzz.lisp is a standalone sample of solving the fizzbuzz problem.
- mtest.lisp shows some macro examples.
As noted there is a standard-library of functions which are loaded along with any user-supplied script. These functions are implemented in lisp and also serve as a demonstration of syntax and features:
Running these example will produce output, for example:
$ yal fibonacci.lisp
1st fibonacci number is 1
2nd fibonacci number is 1
3rd fibonacci number is 2
4th fibonacci number is 3
5th fibonacci number is 5
6th fibonacci number is 8
7th fibonacci number is 13
8th fibonacci number is 21
9th fibonacci number is 34
10th fibonacci number is 55
11th fibonacci number is 89
12th fibonacci number is 144
13th fibonacci number is 233
14th fibonacci number is 377
15th fibonacci number is 610
16th fibonacci number is 987
17th fibonacci number is 1597
18th fibonacci number is 2584
19th fibonacci number is 4181
20th fibonacci number is 6765
21st fibonacci number is 10946
22nd fibonacci number is 17711
The project has 100% test-coverage of all the internal packages, using the standard go facilities you can run those test-cases:
go test ./...In addition to the static-tests there is also support for the integrated fuzz-testing facility which became available with go 1.18+. Fuzz-testing essentially feeds the interpreter random input and hopes to discover crashes.
You can launch a series of fuzz-tests like so:
go test -fuzztime=300s -parallel=1 -fuzz=FuzzYAL -vSample output will look like this:
=== FUZZ FuzzYAL
...
fuzz: elapsed: 56m54s, execs: 163176 (0/sec), new interesting: 108 (total: 658)
fuzz: elapsed: 56m57s, execs: 16317
7B8A
6 (0/sec), new interesting: 108 (total: 658)
fuzz: elapsed: 57m0s, execs: 163183 (2/sec), new interesting: 109 (total: 659)
fuzz: elapsed: 57m3s, execs: 163433 (83/sec), new interesting: 110 (total: 660)
..
If you find a crash then it is either a bug which needs to be fixed, or a false-positive (i.e. a function reports an error which is expected) in which case the fuzz-test should be updated to add it to the list of known-OK results. (For example "division by zero" is a fatal error, so that's a known-OK result).
There is a simple benchmark included within this repository, computing the factorial of 100, to run this execute execute:
$ go test -run=Bench -bench=.To run the benchmark for longer add -benchtime=30s, or similar, to the command-line.
I also put together an external comparison of my toy scripting languages here:
This shows that the Lisp implementation isn't so slow, although it is not the fasted of the scripting languages I've implemented.
This repository was put together after experimenting with a scripting language, an evaluation engine, putting together a TCL-like scripting language, writing a BASIC interpreter and creating tutorial-style FORTH interpreter.
I've also played around with a couple of compilers which might be interesting to refer to:
- Brainfuck compiler:
- A math-compiler: