4.2 KiB
{ target: "reference/api" template: "reference" title: "Compiler API" short_name: "api" }
MoonScript Compiler API
Autocompiling with the moonscript Module
After installing MoonScript, you can include the moonscript module to make
any Lua script MoonScript aware.
require "moonscript"
After moonscript is required, Lua's package loader is updated to search for
.moon files on any subsequent calls to require. The search path for .moon
files is based on the current package.path value in Lua when moonscript is
required. Any search paths in package.path ending in .lua are copied,
rewritten to end in .moon, and then inserted in package.moonpath.
The 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 .moon file
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
—
package.loaders
The 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
built in 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
MoonScript modules.
moonscript.base Module
moonscript = require "moonscript.base"
This module contains an assortment of functions for loading and compiling MoonScript code from within Lua.
The module provides load, loadfile, loadstring functions, which are
analogous to the similarly named Lua functions. The major difference is that
they load MoonScript code instead of Lua code.
moonscript = require "moonscript.base"
fn = moonscript.loadstring 'print "hi!"'
fn!
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 false
makes it so the file does not implicitly return its last statement.
moonscript = require "moonscript.base"
fn = moonscript.loadstring "10"
print fn! -- prints "10"
fn = moonscript.loadstring "10", implicitly_return_root: false
print fn! -- prints nothing
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.
import to_lua from require "moonscript.base"
lua_code, line_table = to_lua [[
x = 124
print "hello world #{x}"
]]
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.
Programmatically Compiling
If you need finer 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):
parse = require "moonscript.parse"
compile = require "moonscript.compile"
moon_code = [[(-> print "hello world")!]]
tree, err = parse.string moon_code
unless tree
error "Parse error: " .. err
lua_code, err, pos = compile.tree tree
unless lua_code
error compile.format_error err, pos, moon_code
-- our code is ready
print lua_code