README for Mixlua

* What is Mixlua?
  ---------------
  Mixlua is a library for Lua 5.1 who provide an onload preprocessor for lua
  files and allow mixing of Lua code with other data.
  It provide loadstring and loadfile function similar to Lua ones but with
  aditional argument for specifing how the data element are recognized and
  handled, and produce a regular lua compiled chunk with additional material
  for handleing the data.

* Example of use:
  ---------------
  Imagine an application who have a table like this one :
    infos = {
      {key = "foo", value = "dummy 1"},
      {key = "bar", value = "dummy 2"},
      ...
    }

  If you want to export it in various formats, you just have to build some
  templates like this one for an xml output :
    <?xml version="1.0" />
    <infos>
      $[ for _, item in ipairs(infos) do ]$
        <item key="$[=item.key]$" value="$[=item.value]$" />
      $[ end $]
    </infos>

  If you load this file with :
    mix.loadfile("template.xml", "$[", "$]")

  The xml file with all data will be printed on stdout. If you prefer to save
  it elsewhere, there is no problems, just give an output function to mixlua
  and it will be ok :
    function output(str) io.stderr:write(str) end)
    mix.loadfile("template.xml", "$[", "]$", nil, "ouput")

  You can see Mixlua as something like the PHP preprocessor but in more
  powerfull.

* Usage:
  ------
  Mixlua expose only two function loadstring and loadfile. They work exactly
  the same way, except for the first parameter who is a filename for loadfile
  and a string for loadfile.

  The next two parameters are two string who represent the tag used to surround
  block of lua code embeded in the data, they must be given and must not be
  empty.

  The parameter four is a string who mark an expression statement instead of a
  code statement. More on this a below. The default value is "=".

  And the last parameter is the name of the output function, by default
  "io.write". (this must be the name of the function, not the function itself
  cause Mixlua is just a preprocessor who do texte transformation)

  When processed throught Mixlua, all data section are transformed into string
  and given as the argument to the output function. Lua code are kept untouched
  and lua expression are also given to the output function but untouched.
  So, for example the example given before will be translated to :
    io.write('<?xml version="1.0" />\
    <infos>\
      ') for _, item in ipairs(infos) do io.write('\
        <item key="')io.write(item.key)io.write('" value="')io.write(item.value)io.write('" />\
      ') end io.write('\
    </infos>')

  And this is passed to the Lua compiler to produce a chunk of compiled code.
  The execution of this chunk will produce the output file.

  In the preprocess, Mixlua escape data in a way that the line numbers are
  kept unchanged so syntax error are reported correctly. And in the Lua
  blocks, all string and comment for are skipped correctly so they can embed
  the delimiter without any risk to corrupt the output.

* Real case example:
  ------------------
  For example the luapage loading of Cgilua by the Kepler Project can be donne
  easily using :
    mix.loadfile("filename", "<?lua", "?>", "=")
  With the advantage that the "?>" closing tag can now appear in a lua string or
  comment.

  Another advantage is that after loading the page is now a complied lua chunk
  that can be executed in different environement and so producing different
  pages depending on the request.
  This allow to implement easily a caching of the templates.