R: add time-ms. Readline history. Misc cleanups.

[jackhill/mal.git] / README.md

# mal - Make a Lisp

## Description

Mal is an interpreter for a subset of the Clojure programming
language. Mal is implemented from scratch in 16 different languages:

* Bash shell
* C
* C#
* Clojure
* Go
* Java
* Javascript ([Online Demo](http://kanaka.github.io/mal))
* GNU Make
* mal itself
* Perl
* PHP
* Postscript
* Python
* R
* Ruby
* Rust


Mal is also a learning tool. Each implementation of mal is separated
into 11 incremental, self-contained (and testable) steps that
demonstrate core concepts of Lisp. The last step is capable of
self-hosting (running the mal implemenation of mal).

The mal (make a lisp) steps are:

* step0_repl
* step1_read_print
* step2_eval
* step3_env
* step4_if_fn_do
* step5_tco
* step6_file
* step7_quote
* step8_macros
* step9_try
* stepA_interop


Mal was presented publicly for the first time in a lightning talk at
Clojure West 2014 (unfortunately there is no video). See
mal/clojurewest2014.mal for the presentation that was given at the
conference (yes the presentation is a mal program).

## Building/running implementations

### Bash 4

```
cd bash
bash stepX_YYY.sh
```

### C

The C implementation of mal requires the following libraries (lib and
header packages): glib, libffi6 and either the libedit or GNU readline library.

```
cd c
make
./stepX_YYY
```

### C# ###

The C# implementation of mal has been tested on Linux using the Mono
C# compiler (mcs) and the Mono runtime (version 2.10.8.1). Both are
required to build and run the C# implementation.

```
cd cs
make
mono ./stepX_YYY
```


### Clojure

```
cd clojure
lein with-profile +stepX trampoline run
```

### Go

```
cd go
make
./stepX_YYY
```


### Java 1.7

The Java implementation of mal requires maven2 to build.

```
cd java
mvn compile
mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY
    # OR
mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS"
```

### Javascript/Node

```
cd js
npm update
node stepX_YYY.js
```

### Mal

Running the mal implementation of mal involves running stepA of one of
the other implementations and passing the mal step to run as a command
line argument.

```
cd IMPL
IMPL_STEPA_CMD ../mal/stepX_YYY.mal

```

### GNU Make 3.81

```
cd make
make -f stepX_YYY.mk
```

### Perl 5.8

For readline line editing support, install Term::ReadLine::Perl or
Term::ReadLine::Gnu from CPAN.

```
cd perl
perl stepX_YYY.pl
```


### PHP 5.3

The PHP implementation of mal requires the php command line interface
to run.

```
cd php
php stepX_YYY.php
```

### Postscript Level 2/3

The Postscript implementation of mal requires ghostscript to run. It
has been tested with ghostscript 9.10.

```
cd ps
gs -q -dNODISPLAY -I./ stepX_YYY.ps
```

### Python (2 or 3)

```
cd python
python stepX_YYY.py
```

### R

The R implementation of mal requires R (r-base-core) to run.

```
cd r
make libs
Rscript stepX_YYY.rb
```

### Ruby (1.8)

```
cd ruby
ruby stepX_YYY.rb
```

### Rust (0.13)

The rust implementation of mal requires the rust compiler and build
tool (cargo) to build.

```
cd rust
# Need patched pcre lib (should be temporary)
git clone https://github.com/kanaka/rust-pcre cadencemarseille-pcre
cargo build
./target/stepX_YYY
```

## Running tests

The are nearly 400 generic Mal tests (for all implementations) in the
`tests/` directory. Each step has a corresponding test file containing
tests specific to that step. The `runtest.py` test harness uses
pexpect to launch a Mal step implementation and then feeds the tests
one at a time to the implementation and compares the output/return
value to the expected output/return value.

To simplify the process of running tests, a top level Makefile is
provided with convenient test targets.

* To run all the tests across all implementations (be prepared to wait):

```
make test
```

* To run all tests against a single implementation:

```
make test^IMPL

# e.g.
make test^clojure
make test^js
```

* To run tests for a single step against all implementations:

```
make test^stepX

# e.g.
make test^step2
make test^step7
```

* To run a specifc step against a single implementation:

```
make test^IMPL^stepX

# e.g
make test^ruby^step3
make test^ps^step4
```