Lisp: from late Old English awlyspian, meaning "to lisp."
Awl is an experimental mini-language based on the Lisp family of programming languages.
It was written for fun and profit to learn more about interpreter
design, programming in C, and using
emscripten to transpile to JavaScript.
Note: This naturally goes without saying, but Awl is just an experimental learning project, which means that it is lacking in thorough testing and probably has many bugs. It should not be used for production code, lest it summon Undefined Behavior™ upon you.
That being said, experimenting and hacking on non-production-ready code just for fun can be worthwhile!
Here are a few examples that briefly demonstrate some of Awl's features.
Math:
; Math example
;;
(func (mean l) (/ (sum l) (len l)))
(func (variance l)
(let ((mu (mean l)))
(/
(sum (map (fn (x) (^ (- x mu) 2)) l))
(len l))))
(define xs {1 2 3 4 5 6})
(println (mean xs)) ; prints 3.5
(println (variance xs)) ; prints 2.916
Recursion:
; Recursive cycle
;;
(func (cycle xs)
(let ((f (fn (n)
(let ((i (% n (len xs))))
(cons (head (slice xs i (+ i 1)))
(list (fn () (f (+ n 1)))))))))
(fn () (f 0))))
(define xs {1 2 3 4})
(println ((cycle xs)))
(println ((head (tail ((cycle xs))))))
Mergesort:
; Merge sort
;;
(func (merge-sort l)
(if (<= (len l) 1)
l
(let ((middle (// (len l) 2))
(left (slice l 0 middle))
(right (slice l middle))
(left-sorted (merge-sort left))
(right-sorted (merge-sort right)))
(merge left-sorted right-sorted))))
(func (merge l r)
(if (nil? l)
r
(if (nil? r)
l
(let ((hl (head l))
(hr (head r)))
(if (< hl hr)
(cons hl (merge (tail l) r))
(cons hr (merge l (tail r))))))))
(println (merge-sort {4 3 2 1}))
; prints -> {1 2 3 4}
(println (merge-sort {54 83 1274 83 74 218 9}))
; prints -> {9 54 74 83 83 218 1274}
Most of Awl's dependencies are included in the repository, so you shouldn't
need to install anything other than the build tools. Awl takes advantage of
some new features in C11, so you will need a fairly recent C compiler.
- Both
clang(tested with version 3.5.0) andgcc(tested with version 4.7.2) are known to successfully compile - You'll need
make - To transpile to JavaScript, you'll need the emscripten toolkit, including
emcc. - To minify the output JavaScript from
emscripten, you'll needuglifyjs, but it isn't strictly necessary.
First, clone the repository, and then compile using make:
$ git clone https://github.com/voithos/awl.git
$ cd awl
$ make
This will create an awl binary under bin/.
You can also compile and execute tests:
$ make test
Or transpile to JavaScript (emcc will need to be in your $PATH):
$ make web
Clean up if you want to start over:
$ make clean
The awl binary can take a single argument - a path to a file to execute.
$ ./bin/awl [file]
If no argument is given, then it will drop into an interactive interpreter (REPL):
$ ./bin/awl
awl v0.x.y
Ctrl+D to exit
awl>
Awl is a mini-language that is inspired by the Lisp family of languages. Thus, it shares most of its features with Lisp and Scheme. These include:
- Dynamic typing
- First-class functions, including anonymous (lambda) functions
- Function closures
- Partial application
- Tail-call optimization
- Data immutability
- Lists as the primary data structure
- Homoiconicity - that is, similar representations of code and data
- Metaprogramming in the form of simple macros
Currently, Awl's data definition and manipulation capabilities are lacking, but this will hopefully be changed in the future.
Awl is an expression-based language. Basically everything is an expression, and can be arbitrarily nested. A program consists of a sequence of such expressions.
Awl supports inline comments using semicolons (;):
; Can go on its own line
(func (plus-one x)
(+ x 1)) ; Or at the end of a line
Printing to standard output can be done using print and println:
awl> (println "Hello sekai!")
Hello sekai!
Variables are created with define (which affects the local environment) and
global (which, as the name suggests, affects the global environment):
awl> (define foo 'bar')
awl> (println foo)
bar
| Type | Example | Description |
|---|---|---|
| Integer | 5, -9 |
A standard integer (long) |
| Floating point | -5., 3.14 |
A standard floating point (double) |
| Boolean | true, false |
A standard... boolean |
| String | "\"escapes\" OK", 'foobar' |
A string type - either single or double quotes |
| Q-Symbol | :like-in-ruby, :'foo' |
A quoted symbol (identifier), can also be written similar to strings |
| Q-Expr | {1 'b' (+ 1 2) x y} |
A quoted expression. The basic data structure - acts like a list |
| Dictionary | [:x 42 :y 'yes' :z {c}] |
A key-value store. Keys are Q-Symbols, values can be anything |
| Function | (fn (x) (/ 1 x)) |
An anonymous function. The basic mechanism of function definition |
| Error | (error 'somebody set up us the bomb') |
An error. Stops evaluation |
Function calls in Awl are defined as
S-Expressions (symbolic
expressions). They are syntactically enclosed in parentheses (). The first
argument of the expression must be a callable, and is evaluated in the current
environment with any following arguments as parameters (this is the iconic
"Polish notation" of Lisp).
awl> (+ 5 6)
11
awl> (println 'foo')
foo
When evaluating user-defined functions, partial application is done automatically for any unfilled arguments (this is currently not done for builtins). This makes it easy to use higher-order functions quickly:
awl> (define xs {1 2 3 4})
awl> (define square (map (fn (x) (* x x))))
awl> (square xs)
{1 4 9 16}
Variable and function identifiers, called "symbols," are evaluated to the values that they map to, except in certain special forms (e.g. when they are being defined):
awl> (define x 5)
awl> (+ x 6)
11
The primitive types evaluate to themselves.
Q-Expressions (quoted expressions, often referred to simply as 'lists') are
particularly important. They are enclosed inside curly braces {}. They are a
collection type and behave similar to lists in other languages. They can store
any number and mixture of primitive types. And they have one more important
ability: expressions that they contain which would normally be evaluated, such
as symbols and S-Expressions, are left unevaluated (i.e. they are "quoted").
This allows them to contain arbitrary code, and then be converted and evaluated
as S-Expressions:
awl> (head {1 2 3})
1
awl> (tail {1 2 3})
{2 3}
awl> (define x {* 3 (+ 2 2)})
awl> x
{* 3 (+ 2 2)}
awl> (eval x)
12
There are a few more expression types that are useful in special cases.
E-Expressions (escaped expressions) are denoted with a preceding backslash \,
and can be used to specifically evaluate a section within a Q-Expression
literal:
awl> {1 2 (+ 2 1)}
{1 2 (+ 2 1)}
awl> {1 2 \(+ 2 1)}
{1 2 3}
C-Expressions (concatenating expressions) are denoted with a preceding at-sign
@. They behave similarly to E-Expressions, with the exception that, when
given a list (Q-Expression), they "extract" the contents and include it
directly in the outer list:
awl> {1 2 \{3 4}}
{1 2 {3 4}}
awl> {1 2 @{3 4}}
{1 2 3 4}
Finally, there is another collection type that is slightly more mundane than
Q-Expressions and their ilk: Dictionaries. Dictionaries act as simple key-value
stores, and are similar to the dictionaries in other languages. They are
delimited with square brackets [], use Q-Symbols as their keys, and can store
any normal value:
awl> (dict-get [:foo 12 :bar 43] :foo)
12
awl> (dict-set [:x 1 :y 2] :z 3)
[:'x' 1 :'y' 2 :'z' 3]
Builtins usually behave like normal functions, but they also have the special
role of enabling some of Awl's basic features, since they are written in C (for
example, the fn builtin creates a new anonymous function).
Awl makes no distinction between "operators" (+, -, *) and other kinds of
builtins - they are simply named differently.
| Builtin | Signature | Description |
|---|---|---|
+ |
(+ [args...]) |
Addition. Takes 2 or more arguments |
- |
(- [args...]) |
Subtraction. Takes 2 or more arguments |
* |
(* [args...]) |
Multiplication. Takes 2 or more arguments |
/ |
(/ [args...]) |
Division. Promotes integers to floats if necessary. Takes 2 or more arguments |
// |
(// [args...]) |
Truncating division. Removes decimal remainder. Takes 2 or more arguments |
% |
(% [args...]) |
Modulo. Takes 2 or more arguments |
^ |
(^ [args...]) |
Power operator. Takes 2 or more arguments |
> |
(> [arg1] [arg2]) |
Greater than. Takes 2 arguments |
>= |
(>= [arg1] [arg2]) |
Greater than or equal to. Takes 2 arguments |
< |
(< [arg1] [arg2]) |
Less than. Takes 2 arguments |
<= |
(<= [arg1] [arg2]) |
Less than or equal to. Takes 2 arguments |
== |
(== [arg1] [arg2]) |
Equal to. Tests deep equality. Takes 2 arguments |
!= |
(!= [arg1] [arg2]) |
Unequal to. Tests deep equality. Takes 2 arguments |
and |
(and [arg1] [arg2]) |
Logical 'and'. Short circuiting. Takes 2 arguments |
or |
(or [arg1] [arg2]) |
Logical 'or'. Short circuiting. Takes 2 arguments |
not |
(not [arg1]) |
Logical 'not'. Takes 1 argument |
head |
(head [arg1]) |
Returns the extracted first element (head) of a list |
qhead |
(qhead [arg1]) |
Like head, except quotes symbols and S-Exprs |
tail |
(tail [arg1]) |
Returns the tail of a list, excluding the first element |
first |
(first [arg1]) |
Similar to head, but doesn't extract |
last |
(last [arg1]) |
Returns the last element of a list, unextracted |
except-last |
(except-last [arg1]) |
Returns the first section of a list, excluding the last element |
list |
(list [args...]) |
Returns a list containing the evaluated arguments |
eval |
(eval [arg1]) |
Evaluates a list as if it were an S-Expression |
append |
(append [args...]) |
Concatenates two or more lists |
cons |
(cons [arg1] [arg2]) |
Attaches a primitive type to the head of a list |
dict-get |
(dict-get [dict] [key]) |
Retrieves a value from a dict using a key |
dict-set |
(dict-set [dict] [key] [val]) |
Returns a new dict with a value set |
dict-del |
(dict-del [dict] [key]) |
Returns a new dict with a value deleted |
dict-haskey? |
(dict-haskey? [dict] [key]) |
Checks if a dict has a key set |
dict-keys |
(dict-keys [dict]) |
Returns a list of keys in the dictionary |
dict-vals |
(dict-vals [dict]) |
Returns a list of values in the dictionary |
len |
(len [arg1]) |
Returns the length of a collection |
reverse |
(reverse [arg1]) |
Reverses a collection |
slice |
(slice [c] [start] [end] [step]) |
Returns a slice of a collection based on start, stop, and step numbers |
if |
(if [pred] [then-branch] [else-branch]) |
If expression. Evaluates a predicate, and one of two branches based on the result |
define |
(define [sym] [value]) |
Defines a variable in the local environment |
global |
(global [sym] [value]) |
Defines a variable in the global environment |
let |
(let (([sym1] [val1])...) [expr]) |
Creates a local environment and defines variables within |
fn |
(fn ([args...]) [body]) |
Defines an anonymous function with the specified arguments and body. The function also retains the current environment as a closure |
macro |
(macro [name] ([args...]) [body]) |
Defines a macro that can operate on code before it is evaluated |
typeof |
(typeof [arg1]) |
Returns a string representing the type of the argument |
convert |
(convert [type] [value]) |
Converts a value to type, which is represented by a qsym,
as returned by typeof |
import |
(import [path]) |
Attempts to import the awl file at the given path |
print |
(print [arg1]) |
Prints to standard output |
println |
(println [arg1]) |
Prints to standard output, adding a newline |
random |
(random) |
Returns a floating point random number between 0 and 1 |
error |
(error [arg1]) |
|
exit |
(exit [arg1]) |
Exits the interactive REPL |
In addition to builtins, there exists a core library that Awl imports on startup. Among other things, this library aims to exercise some of Awl's features, as well as provide some basic functional tools.
| Symbol | Signature | Description |
|---|---|---|
nil |
Alias for {} |
|
func |
(func ([name] [args]) [body]) |
Macro that defines a named function |
int? |
(int? [arg1]) |
Checks that argument is an integer |
float? |
(float? [arg1]) |
Checks that argument is a floating point |
str? |
(str? [arg1]) |
Checks that argument is a string |
builtin? |
(builtin? [arg1]) |
Checks that argument is a builtin |
fn? |
(fn? [arg1]) |
Checks that argument is a user-defined function |
macro? |
(macro? [arg1]) |
Checks that argument is a macro |
bool? |
(bool? [arg1]) |
Checks that argument is a boolean |
qexpr? |
(qexpr? [arg1]) |
Checks that argument is a Q-Expression |
dict? |
(dict? [arg1]) |
Checks that argument is a Dictionary |
list? |
(list? [arg1]) |
Alias for qexpr? |
nil? |
(nil? [arg1]) |
Checks that argument is nil |
to-str |
(to-str [arg1]) |
Converts argument to a string |
to-qsym |
(to-qsym [arg1]) |
Converts argument to a Q-Symbol |
do |
(do [expr1] [expr2] ... [exprn]) |
Evaluates its arguments one by one, and returns the result of the last argument |
compose |
(compose [f] [g] [xs...]) |
Composes two functions |
flip |
(flip [f] [x] [y]) |
Takes a function and two argument, and flip the ordering of the arguments |
id |
(id [x]) |
The identity function, returns whatever is passed |
reduce |
(reduce [f] [l] [acc]) |
Reduces a list to a single value using a reducer function |
reduce-left |
(reduce-left [f] [l] [acc]) |
Like reduce, but traverses the list in the opposite direction |
map |
(map [f] [l]) |
Applies a function to each element of a list |
filter |
(filter [f] [l]) |
Uses a predicate function to filter out elements from a list |
any |
(any [f] [l]) |
Checks whether any value in list l satisfies f |
all |
(all [f] [l]) |
Checks whether all values in list l satisfy f |
sum |
(sum [l]) |
Sums elements of a list |
product |
(product [l]) |
Multiplies together elements of a list |
pack |
(pack [f] [args...]) |
Takes multiple argument and feeds it to a function as a single list argument |
unpack |
(unpack [f] [l]) |
Evaluates a function using a list of arguments |
nth |
(nth [n] [l]) |
Returns the nth element of a list |
zip |
(zip [lists...]) |
Returns a list of lists, each containing the i-th element of the argument lists |
take |
(take [n] [l]) |
Takes the first n elements of a list |
drop |
(drop [n] [l]) |
Drops the first n elements of a list, returning what's
left |
member? |
(member? [x] [l]) |
Checks if an element is a member of a list |
range |
(range [s] [e]) |
Returns a list of integers starting with s and going up to
e |
dict-items |
(dict-items [dict]) |
Returns a list of key-value pairs from the given dict |
random-between |
(random-between [s] [e]) |
Returns a random floating point between s and
e |
Many thanks goes to the following awesome libraries and open source projects, and their creators:
- mpc.c
- ptest.c
- linenoise
- clang / LLVM
- emscripten
- JQuery Terminal
Also, thanks goes to the creator of the free "Build Your Own Lisp" online book, which is what Awl was inspired from.