README.md

   1 # mal - Make a Lisp
   2
   3 ## Description
   4
   5 Mal is a Clojure inspired Lisp interpreter.
   6
   7 Mal is implemented in 26 different languages:
   8
   9 * Bash shell
  10 * C
  11 * C#
  12 * Clojure
  13 * CoffeeScript
  14 * Forth
  15 * Go
  16 * Haskell
  17 * Java
  18 * Javascript ([Online Demo](http://kanaka.github.io/mal))
  19 * Lua
  20 * GNU Make
  21 * mal itself
  22 * MATLAB
  23 * [miniMAL](https://github.com/kanaka/miniMAL)
  24 * OCaml
  25 * Perl
  26 * PHP
  27 * Postscript
  28 * Python
  29 * R
  30 * Racket
  31 * Ruby
  32 * Rust
  33 * Scala
  34 * Visual Basic.NET
  35
  36
  37 Mal is a [learning tool](process/guide.md). Each implementation of mal is separated into 11
  38 incremental, self-contained (and testable) steps that demonstrate core
  39 concepts of Lisp. The last step is capable of self-hosting (running
  40 the mal implemenation of mal).
  41
  42 The mal (make a lisp) steps are:
  43
  44 * [step0_repl](process/guide.md#step0)
  45 * [step1_read_print](process/guide.md#step1)
  46 * [step2_eval](process/guide.md#step2)
  47 * [step3_env](process/guide.md#step3)
  48 * [step4_if_fn_do](process/guide.md#step4)
  49 * [step5_tco](process/guide.md#step5)
  50 * [step6_file](process/guide.md#step6)
  51 * [step7_quote](process/guide.md#step7)
  52 * [step8_macros](process/guide.md#step8)
  53 * [step9_try](process/guide.md#step9)
  54 * [stepA_mal](process/guide.md#stepA)
  55
  56
  57 Mal was presented publicly for the first time in a lightning talk at
  58 Clojure West 2014 (unfortunately there is no video). See
  59 mal/clojurewest2014.mal for the presentation that was given at the
  60 conference (yes the presentation is a mal program).
  61
  62 ## Building/running implementations
  63
  64 ### Bash 4
  65
  66 ```
  67 cd bash
  68 bash stepX_YYY.sh
  69 ```
  70
  71 ### C
  72
  73 The C implementation of mal requires the following libraries (lib and
  74 header packages): glib, libffi6 and either the libedit or GNU readline library.
  75
  76 ```
  77 cd c
  78 make
  79 ./stepX_YYY
  80 ```
  81
  82 ### C# ###
  83
  84 The C# implementation of mal has been tested on Linux using the Mono
  85 C# compiler (mcs) and the Mono runtime (version 2.10.8.1). Both are
  86 required to build and run the C# implementation.
  87
  88 ```
  89 cd cs
  90 make
  91 mono ./stepX_YYY.exe
  92 ```
  93
  94
  95 ### Clojure
  96
  97 ```
  98 cd clojure
  99 lein with-profile +stepX trampoline run
 100 ```
 101
 102 ### CoffeeScript
 103
 104 ```
 105 sudo npm install -g coffee-script
 106 cd coffee
 107 coffee ./stepX_YYY
 108 ```
 109
 110 ### Forth
 111
 112 ```
 113 cd forth
 114 gforth stepX_YYY.fs
 115 ```
 116
 117 ### Go
 118
 119 You Go implementation of mal requires that go is installed on on the
 120 path. The implementation has been tested with Go 1.3.1.
 121
 122 ```
 123 cd go
 124 make
 125 ./stepX_YYY
 126 ```
 127
 128
 129 ### Haskell
 130
 131 Install the Haskell compiler (ghc/ghci), the Haskell platform and
 132 either the editline package (BSD) or the readline package (GPL). On
 133 Ubuntu these packages are: ghc, haskell-platform,
 134 libghc-readline-dev/libghc-editline-dev
 135
 136 ```
 137 cd haskell
 138 make
 139 ./stepX_YYY
 140 ```
 141
 142
 143 ### Java 1.7
 144
 145 The Java implementation of mal requires maven2 to build.
 146
 147 ```
 148 cd java
 149 mvn compile
 150 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY
 151     # OR
 152 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS"
 153 ```
 154
 155 ### Javascript/Node
 156
 157 ```
 158 cd js
 159 npm update
 160 node stepX_YYY.js
 161 ```
 162
 163 ### Lua
 164
 165 Running the Lua implementation of mal requires lua 5.1 or later,
 166 luarocks and the lua-rex-pcre library installed.
 167
 168 ```
 169 cd lua
 170 make  # to build and link linenoise.so
 171 ./stepX_YYY.lua
 172 ```
 173
 174 ### Mal
 175
 176 Running the mal implementation of mal involves running stepA of one of
 177 the other implementations and passing the mal step to run as a command
 178 line argument.
 179
 180 ```
 181 cd IMPL
 182 IMPL_STEPA_CMD ../mal/stepX_YYY.mal
 183
 184 ```
 185
 186 ### GNU Make 3.81
 187
 188 ```
 189 cd make
 190 make -f stepX_YYY.mk
 191 ```
 192
 193 ### OCaml 4.01.0
 194
 195 ```
 196 cd ocaml
 197 make
 198 ./stepX_YYY
 199 ```
 200
 201 ### MATLAB
 202
 203 The MATLAB implementation of mal has been tested with MATLAB version
 204 R2014a on Linux. Note that MATLAB is a commercial product. It should
 205 be fairly simple to support GNU Octave once it support classdef object
 206 syntax.
 207
 208 ```
 209 cd matlab
 210 ./stepX_YYY
 211 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY();quit;"
 212     # OR with command line arguments
 213 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY('arg1','arg2');quit;"
 214 ```
 215
 216 ### miniMAL
 217
 218 [miniMAL](https://github.com/kanaka/miniMAL) is small Lisp interpreter
 219 implemented in less than 1024 bytes of JavaScript. To run the miniMAL
 220 implementation of mal you need to download/install the miniMAL
 221 interpreter (which requires Node.js).
 222 ```
 223 # Download miniMAL itself
 224 git clone https://github.com/kanaka/miniMAL ../miniMAL.git
 225 export PATH=`pwd`/miniMAL.git:$PATH
 226 # Now run mal implementated in miniMAL
 227 cd miniMAL
 228 miniMAL ./stepX_YYY
 229 ```
 230
 231 ### Perl 5.8
 232
 233 For readline line editing support, install Term::ReadLine::Perl or
 234 Term::ReadLine::Gnu from CPAN.
 235
 236 ```
 237 cd perl
 238 perl stepX_YYY.pl
 239 ```
 240
 241
 242 ### PHP 5.3
 243
 244 The PHP implementation of mal requires the php command line interface
 245 to run.
 246
 247 ```
 248 cd php
 249 php stepX_YYY.php
 250 ```
 251
 252 ### Postscript Level 2/3
 253
 254 The Postscript implementation of mal requires ghostscript to run. It
 255 has been tested with ghostscript 9.10.
 256
 257 ```
 258 cd ps
 259 gs -q -dNODISPLAY -I./ stepX_YYY.ps
 260 ```
 261
 262 ### Python (2 or 3)
 263
 264 ```
 265 cd python
 266 python stepX_YYY.py
 267 ```
 268
 269 ### R
 270
 271 The R implementation of mal requires R (r-base-core) to run.
 272
 273 ```
 274 cd r
 275 make libs  # to download and build rdyncall
 276 Rscript stepX_YYY.r
 277 ```
 278
 279 ### Racket (5.3)
 280
 281 The Racket implementation of mal requires the Racket
 282 compiler/interpreter to run.
 283
 284 ```
 285 cd racket
 286 ./stepX_YYY.rb
 287 ```
 288
 289 ### Ruby (1.9+)
 290
 291 ```
 292 cd ruby
 293 ruby stepX_YYY.rb
 294 ```
 295
 296 ### Rust (0.13)
 297
 298 The rust implementation of mal requires the rust compiler and build
 299 tool (cargo) to build.
 300
 301 ```
 302 cd rust
 303 # Need patched pcre lib (should be temporary)
 304 git clone https://github.com/kanaka/rust-pcre cadencemarseille-pcre
 305 cargo build
 306 ./target/stepX_YYY
 307 ```
 308
 309 ### Scala ###
 310
 311 Install scala and sbt (http://www.scala-sbt.org/0.13/tutorial/Installing-sbt-on-Linux.html):
 312
 313 ```
 314 cd scala
 315 sbt 'run-main stepX_YYY'
 316     # OR
 317 sbt compile
 318 scala -classpath target/scala*/classes stepX_YYY
 319 ```
 320
 321 ### Visual Basic.NET ###
 322
 323 The VB.NET implementation of mal has been tested on Linux using the Mono
 324 VB compiler (vbnc) and the Mono runtime (version 2.10.8.1). Both are
 325 required to build and run the VB.NET implementation.
 326
 327 ```
 328 cd vb
 329 make
 330 mono ./stepX_YYY.exe
 331 ```
 332
 333
 334
 335 ## Running tests
 336
 337 The are nearly 500 generic Mal tests (for all implementations) in the
 338 `tests/` directory. Each step has a corresponding test file containing
 339 tests specific to that step. The `runtest.py` test harness uses
 340 pexpect to launch a Mal step implementation and then feeds the tests
 341 one at a time to the implementation and compares the output/return
 342 value to the expected output/return value.
 343
 344 To simplify the process of running tests, a top level Makefile is
 345 provided with convenient test targets.
 346
 347 * To run all the tests across all implementations (be prepared to wait):
 348
 349 ```
 350 make test
 351 ```
 352
 353 * To run all tests against a single implementation:
 354
 355 ```
 356 make test^IMPL
 357
 358 # e.g.
 359 make test^clojure
 360 make test^js
 361 ```
 362
 363 * To run tests for a single step against all implementations:
 364
 365 ```
 366 make test^stepX
 367
 368 # e.g.
 369 make test^step2
 370 make test^step7
 371 ```
 372
 373 * To run a specifc step against a single implementation:
 374
 375 ```
 376 make test^IMPL^stepX
 377
 378 # e.g
 379 make test^ruby^step3
 380 make test^ps^step4
 381 ```
 382
 383 ## License
 384
 385 Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public
 386 License 2.0). See LICENSE.txt for more details.
 387