MoonScript Compiler API
Autocompiling with the
After installing MoonScript, you can include the
moonscript module to make
any Lua script MoonScript aware.
moonscript is required, Lua’s package loader is updated to search for
.moon files on any subsequent calls to
require. The search path for
files is based on the current
package.path value in Lua when
required. Any search paths in
package.path ending in
.lua are copied,
rewritten to end in
.moon, and then inserted in
moonloader is the function that is responsible for searching
package.moonpath for a file available to be included. It is inserted in the
second position of the
package.loaders table. This means that a matching
will be loaded over a matching
.lua file that has the same base name.
For more information on Lua’s
package.loaders see Lua Reference Manual
moonloader, when finding a valid path to a
.moon file, will parse and
compile the file in memory. The code is then turned into a function using the
load function, which is run as the module.
If you are executing MoonScript code with the included
moon command line tool
then it is not required to include this module before including any other
This module contains an assortment of functions for loading and compiling MoonScript code from within Lua.
The module provides
loadstring functions, which are
analogous to the similarly named Lua functions. The major difference is that
they load MoonScript code instead of Lua code.
All of these functions can take an optional last argument, a table of options.
The only option right now is
implicitly_return_root. Setting this to
makes it so the file does not implicitly return its last statement.
One more useful function is provided:
to_lua. This function takes a string of
MoonScript code and returns the compiled Lua result along with the line mapping
table. If there are any errors then
nil and the error message are returned.
Similar to the
load* functions from above,
to_lua can take an optional
final argument of a table of options.
The second return value of
to_lua is useful if you want to perform line
number reversal. It’s a table where the key is a Lua line number and the value
is a character offset from the original MoonScript source.
If you need finder grained control over the compilation process you can use the raw parse and compile modules.
Parsing converts a string of MoonScript into an abstract syntax tree. Compiling converts an abstract syntax tree into a Lua code string.
Knowledge of this API may be useful for creating tools to aid the generation of Lua code from MoonScript code. For example, you could build a macro system by analyzing and manipulating the abstract syntax tree. Be warned though, the format of the abstract syntax tree is undocumented and may change in the future.
Here is a quick example of how you would compile a MoonScript string to a Lua
String (This is effectively the same as the
to_lua function described above):