README-compiler.md

   1 Metalua Compiler
   2 ================
   3
   4 ## Metalua compiler
   5
   6 This module `metalua-compiler` depends on `metalua-parser`. Its main
   7 feature is to compile ASTs into Lua 5.1 bytecode, allowing to convert
   8 them into bytecode files and executable functions. This opens the
   9 following possibilities:
  10
  11 * compiler objects generated with `require 'metalua.compiler'.new()`
  12   support methods `:xxx_to_function()` and `:xxx_to_bytecode()`;
  13
  14 * Compile-time meta-programming: use of `-{...}` splices in source
  15   code, to generate code during compilation;
  16
  17 * Some syntax extensions, such as structural pattern matching and
  18   lists by comprehension;
  19
  20 * Some AST manipulation facilities such as `treequery`, which are
  21   implemented with Metalua syntax extensions.
  22
  23 ## What's new in Metalua 0.7
  24
  25 This is a major overhaul of the compiler's architecture. Some of the
  26 most noteworthy changes are:
  27
  28 * No more installation or bootstrap script. Some Metalua source files
  29   have been rewritten in plain Lua, and module sources have been
  30   refactored, so that if you just drop the `metalua` folder somewhere
  31   in your `LUA_PATH`, it works.
  32
  33 * The compiler can be cut in two parts:
  34
  35   * a parser which generates ASTs out of Lua sources, and should be
  36     either portable or easily ported to Lua 5.2;
  37
  38   * a compiler, which can turn sources and AST into executable
  39     Lua 5.1 bytecode and run it. It also supports compile-time
  40     meta-programming, i.e. code included between `-{ ... }` is
  41     executed during compilation, and the ASTs it produces are
  42     included in the resulting bytecode.
  43
  44 * Both parts are packaged as separate LuaRocks, `metalua-parser` and
  45   `metalua-compiler` respectively, so that you can install the former
  46   without the latter.
  47
  48 * The parser is not a unique object anymore. Instead,
  49   `require "metalua.compiler".new()` returns a different compiler
  50   instance every time it's called. Compiler instances can be reused on
  51   as many source files as wanted, but extending one instance's grammar
  52   doesn't affect other compiler instances.
  53
  54 * Included standard library has been shed. There are too many standard
  55   libs in Lua, and none of them is standard enough, offering
  56   yet-another-one, coupled with a specific compiler can only add to
  57   confusion.
  58
  59 * Many syntax extensions, which either were arguably more code samples
  60   than actual production-ready tools, or relied too heavily on the
  61   removed runtime standard libraries, have been removed.
  62
  63 * The remaining libraries and samples are:
  64
  65   * `metalua.compiler` converts sources into ASTs, bytecode,
  66     functions, and ASTs back into sources.
  67
  68   * `metalua` compiles and/or executes files from the command line,
  69     can start an interactive REPL session.
  70
  71   * `metalua.loader` adds a package loader which allows to use modules
  72     written in Metalua, even from a plain Lua program.
  73
  74   * `metalua.treequery` is an advanced DSL allowing to search ASTs in
  75     a smart way, e.g. "_search `return` statements which return a
  76     `local` variable but aren't in a nested `function`_".
  77
  78   * `metalua.extension.comprehension` is a language extension which
  79     supports lists by comprehension
  80     (`even = { i for i=1, 100 if i%2==0 }`) and improved loops
  81     (`for i=1, 10 for j=1,10 if i~=j do print(i,j) end`).
  82
  83   * `metalua.extension.match` is a language extension which offers
  84     Haskell/ML structural pattern matching
  85     (``match AST with `Function{ args, body } -> ... | `Number{ 0 } -> ...end``)
  86
  87    * **TODO Move basic extensions in a separate module.**
  88
  89 * To remove the compilation speed penalty associated with
  90   metaprogramming, when environment variable `LUA_MCACHE` or Lua
  91   variable `package.mcache` is defined and LuaFileSystem is available,
  92   the results of Metalua source compilations is cached. Unless the
  93   source file is more recent than the latest cached bytecode file, the
  94   latter is loaded instead of the former.
  95
  96 * The Luarock install for the full compiler lists dependencies towards
  97   Readline, LuaFileSytem, and Alt-Getopts. Those projects are
  98   optional, but having them automatically installed by LuaRocks offers
  99   a better user experience.
 100
 101 * The license has changed from MIT to double license MIT + EPL. This
 102   has been done in order to provide the IP guarantees expected by the
 103   Eclipse Foundation, to include Metalua in Eclipse's
 104   [Lua Development Tools](http://www.eclipse.org/koneki/ldt/).