doc/manual/reading-guide.tex

   1 \section*{Reading guide}\r
   2 This manual tries to be as comprehensive as possible; however, you don't\r
   3 necessarily have to read all of it before starting to do interesting stuff with\r
   4 metalua. Here's a brief summary of what the different parts of the manual\r
   5 address, and why you might want to read them immediately---or not.\r
   6 \r
   7 \begin{itemize}\r
   8 \item{\bf Before reading this manual:} metalua is based on Lua, so\r
   9   you'll need a minimal level of Lua proficiency. You can probably get\r
  10   away without knowing much about metatables, environments or\r
  11   coroutines, but you need to be at ease with basic flow control,\r
  12   scoping rules, first-class functions, and the whole\r
  13   everything-is-a-table approach.\r
  14 \item{\bf Meta-programming in metalua:} this chapter exposes the generic principles\r
  15   of static meta-programming: meta-levels in sources, AST representation of\r
  16   code, meta-operators. You need to read this carefully if you plan to write any\r
  17   non-trivial meta-programming code and you've never used languages like, Common\r
  18   Lisp, camlp4 or Converge. If you're familiar with one of these, a cursory look\r
  19   over this chapter might be enough for you.\r
  20 \item{\bf Standard meta-programming libraries:} these are the tools that will allow\r
  21   you to manipulate code effectively; the more advanced an extension you want to\r
  22   write the more of these you'll want to know.\r
  23   \begin{itemize}\r
  24   \item{\bf mlp} is the dynamically extensible metalua parser. You need to know it\r
  25     if you want to change or extend the language's syntax\r
  26   \item{\bf gg} is the grammar generator, the library which lets you manipulate\r
  27     dynamic parsers. You need to know it in order to do anything useful with\r
  28     mlp.\r
  29   \item{\bf match} is an extension supporting structural pattern matching (which has\r
  30     almost nothing to do with regular expressions on strings). It's a construct\r
  31     taken from the ML language familly, which lets you manipulate advanced data\r
  32     structures in vrey powerful ways. It's extremely helpful, among others, when\r
  33     working with AST, i.e. for most interesting meta-programs.\r
  34   \item{\bf walk} is a code walker generator: smomething akin to a visitor pattern,\r
  35     which will help you to write code analysers or transformers. Whenever you\r
  36     want to find and transform all return statements in an AST, rename some\r
  37     conflicting local variables, check for the presence of nested for loops\r
  38     etc., you'll have to write a code walker, and walk will get you there much\r
  39     faster. \r
  40   \item{\bf hygiene} offers hygienic macros, i.e. protects you from accidental\r
  41     variable captures. As opposed to e.g. Scheme, macro writing is not limited\r
  42     to a term rewriting system in metalua, which lets more power to the\r
  43     programmer, but prevents from completely automating macro hygienization. If\r
  44     you wrote an extension and you want to raise it to production-quality,\r
  45     you'll need among others to protect its users from variable captures, and\r
  46     you'll need to hygienize it. If you don't feel like cluttering your code\r
  47     with dozens of {\tt gensym} calls, you'll want to use the macro hygienizer.\r
  48   \item{\bf dollar:} if you wrote a macro, but don't feel the need to give it a\r
  49     dedicated syntax extension, this library will let you call this macro as a\r
  50     regular function call, except that it will be prefixed with a ``{\tt\$}''.\r
  51   \end{itemize}\r
  52   \item{\bf General purpose libraries:} Lua strives at staying minimalist, and does\r
  53     not come with batteries included; you're expected to grab them separately,\r
  54     currently from luaforge, and eventually from a Lua Rocks repository. Metalua\r
  55     needs quite some support to run, and relies on a number of imported and\r
  56     custom-built libraries. Most of them can be reused for many other purposes\r
  57     including yours.\\\r
  58     A whole category of metalua users, who want to use third party libraries\r
  59     rather than reinventing their own wheels, will be primarily interested by\r
  60     these.\r
  61     \begin{itemize}\r
  62     \item{\bf metalua.runtime:} extensions to Lua core libraries: base, table,\r
  63       string.\r
  64     \item{\bf metalua.compiler:} mlc offers a consistent interface to metalua\r
  65       compilation and code representation transformers. 'package', 'loadstring',\r
  66       'dostring', 'loadfile' and 'dofile' are also updated to handle metalua\r
  67       source files.\r
  68     \item{\bf clopts} simplifies and unifies the handling of command line options\r
  69       for metalua programs.\r
  70     \item{\bf springs} brings together Lua Ring's handling of separate Lua universes\r
  71       with Pluto's communication capabilities.\r
  72     \item{\bf clist} offers an extended tables-as-list interface: lists by\r
  73       comprehension {\em \`a la} Haskell or Python, list chunks etc.\r
  74     \item{\bf xglobal} makes global variables declaration mandatory, for safer\r
  75       programming, with almost no runtime overhead, and a syntax consistant qith\r
  76       local variables declaration.\r
  77     \item{\bf anaphoric} introduces anaphoric control structures, akin to Common\r
  78       Lisp's {\tt aif}-familly macros.\r
  79     \item{\bf trycatch} provides a proper exception system, with reliable finally\r
  80       blocks and exception catching by structural pattern matching.\r
  81     \item{\bf log} eases the terminal logging of variables, mainly for those from\r
  82       the Printf-based School of Debugging.\r
  83     \item{\bf types} offers dynamic type checking to metalua programs. It supports\r
  84       variable typing as opposed to value typing, and advanced type system\r
  85       features (polymorphism, dependant types etc.).\r
  86     \end{itemize}\r
  87   \item{\bf Examples and tutorials}: this chapter lists a series of tiny\r
  88     meta-programs whose main purpose is didactic, and walks through the detailed\r
  89     implementation of a couple of non-trivial extensions.\r
  90 \end{itemize}\r