Installation and use

Installation

Luarocks

Both the compiler and Lua module can be installed using LuaRocks. First install LuaRocks if you don’t have it already, then run

luarocks install hurdy

from a terminal.

Windows binaries

Building on Windows (even when using LuaRocks) is more convoluted, so pre-built compiler and Lua module are provided on the releases page of the git repository.

Source

The source code for Hurdy can be found here. The compiler and the Lua library can be compiled (independently) from the source code using CMake (see README in the git repository).

Usage

Compiler

The compiler hurdyc can be run from the command line after installing it with LuaRocks or building it directly from source. The executable has three subcommands:

  • hurdyc file compiles a single Hurdy file to Lua. If the output file is not specified the result will be printed to the screen.

  • hurdyc folder compiles recursively all files with extension .hurdy file to Lua. The output folder must be specified, and the directory structure will be recreated.

  • hurdyc ast generates a JSON file containing the abstract syntax tree of a Hurdy file.

    Warning

    hurdyc ast is undocumented and the format of its output may change in future releases.

To get more information about the subcommands, run them with the -h flag, e.g.,

hurdyc folder -h

Lua library

The Lua library (which will be called hurdy.so, hurdy.dll, or hurdy.dylib depending on the operating system) can be loaded from Lua by making sure that it can be found (modifying package.cpath if necessary) and using

local hurdy = require("hurdy")

The hurdy tables includes the following fields

  • hurdy.searcher is a searcher function that can be added to package.searchers (or package.loaders in Lua 5.1) to allow require to load Hurdy file (by compiling them as they are loaded)

  • hurdy.path has the same format as package.path and is used by hurdy.searcher to decide if a file should be loaded as Hurdy. Modify it as necessary.

  • hurdy.compile is a function that takes a string containing Hurdy code and returns a string with the compiled Lua code

  • hurdy.loadstring is a function that takes a string containing Hurdy code and returns a compiled chuck that can be called to run it

  • hurdy.loadfile is a function that takes the filename of a Hurdy file, loads its content, and returns a compiled chuck that can be called to run it

  • hurdy.singleErrHandler(msg) is an error handler that takes a Lua error message as input and modifies it to remap the line number from the compiled Lua code to the one from the original Hurdy code (only works for chunks loaded through the library)

  • hurdy.tracebackErrHandler(msg, level) provides a traceback like debug.traceback, but remaps the line numbers for Hurdy chunks

  • hurdy.generate_AST(data, use_resolver) is a function that takes the string containing Hurdy code data and returns a table representing its abstract syntax tree. The optional boolean parameter use_resolver can be used to turn on/off the resolver, which processes the syntax tree to ensure that variables have been declared before being assigned to. use_resolver defaults to true if not provided or if nil is passed as the argument.

    Warning

    hurdy.generate_AST is undocumented and the format of its output may change in future releases.