Installation and use

The Lua library for Hurdy come in two versions, one written in C++ and one written in Lua. The standalone compiler is only included in the C++ distribution of Hurdy. Refer to the Q&A section for help deciding which version best fits your use case.

Installation

C++ version

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).

Pure Lua version

Luarocks

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

luarocks install hurdyl

Standalone

Alternatively the Lua files can be downloaded directly from the releases page of the git repository.

Source

The source code for the Lua version of the library can be found here. The library is written in Hurdy itself, all the files will need to be compiled to Lua before they can be used.

Usage

Compiler

The standalone 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.

Note

Specifying the minimum Lua version to target makes the compiler raise errors when it encounters features that require a more recent Lua version (e.g, bitwise operations require Lua 5.3+).

Using the --lines flag will add comments at the end of each compiled Lua line, indicating which line(s) of the source file it corresponds to.

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

    Usage: hurdyc file [-h] [--output VAR] [--lines] --target VAR input
    
    Compile a single hurdy file to Lua
    
    Positional arguments:
      input             Input hurdy file
    
    Optional arguments:
      -h, --help        shows help message and exits
      -v, --version     prints version information and exits
      -o, --output      Output Lua file
      --lines           Write line numbers from source code as comments
      --target          Specify the minimum Lua version to target. Must be one of {5.1, jit, 5.2, 5.3, latest}. 'jit' targets LuaJIT. [default: "latest"]
    
  • 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.

    Usage: hurdyc folder [-h] [--lines] --target VAR input output
    
    Compile recursively all hurdy files in a folder to Lua
    
    Positional arguments:
      input             Input folder
      output            Output folder
    
    Optional arguments:
      -h, --help        shows help message and exits
      -v, --version     prints version information and exits
      --lines           Write line numbers from source code as comments
      --target          Specify the minimum Lua version to target. Must be one of {5.1, jit, 5.2, 5.3, latest}. 'jit' targets LuaJIT. [default: "latest"]
    
  • 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.

    Usage: hurdyc ast [-h] [--output VAR] [--no-resolver] input
    
    Generate the abstract sytax tree for a hurdy file as a JSON file
    
    Positional arguments:
      input             Input hurdy file
    
    Optional arguments:
      -h, --help        shows help message and exits
      -v, --version     prints version information and exits
      -o, --output      Output JSON file
      --no-resolver     Disable resolve (does not ensure that variables have been declared before assigning to them)
    

Lua library

Loading the library

The C++ 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")

For the pure Lua version: assuming that the Lua files are located in the folder hurdyl which can be found by require (modifying package.path if necessary), it can be loaded as

local hurdy = require("hurdyl") -- only if package.path is set up to load init.lua if a folder name is passed to require

or

local hurdy = require("hurdyl.init")

Both versions provide the same fields and functions in the hurdy table, described below.

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.

  • _VERSION is a string representing the library version.

    Note

    The C++ and pure Lua libraries have indipendent version numbers!

Functions

  • hurdy.compile(source[, name][, target])

    Compiles a string containing Hurdy code to Lua.

    Parameters:
    • source (string) – String containing the Hurdy source code.

    • name (string or nil) – Optional identifier for the compiled Lua code. If provided, it is included in the compilation error messages.

    • target (string or nil) – Optional string identifying the minimum Lua version to target, so that the compiler will give errors if trying to use unsupported features. Must be one of "5.1", "jit", "5.2", "5.3", "latest". Defaults to "latest" if not provided or nil.

    Returns:

    The compiled Lua code as a string, and a line map array. The line map is an array of strings with an entry for each line of the compiled Lua code, indicating which line(s) of the Hurdy source code it corresponds to; each entry is a string containing either a single number (single line of the source code) or two numbers separated by a dash - (range of lines in the source code).

  • hurdy.loadstring(source[, chunkname])

    Compile a string containing Hurdy code to a Lua chunk that can be called to run it.

    Parameters:
    • source (string) – String containing the Hurdy source code.

    • chunkname (string or nil) – An optional identifier for the chunk, used in error messages (both during compilation and when running the chunk)

    Returns:

    The compiled chunk.

  • hurdy.loadfile(filename)

    Read the Hurdy file at filename and compile it to a Lua chunk that can be called to run it.

    Parameters:

    filename (string) – The location of the Hurdy file.

    Returns:

    The compiled chunk.

  • hurdy.singleErrHandler(msg)

    Modify a Lua error message to remap the line number from a compiled Hurdy chunk (obtained through hurdy.loadstring() or hurdy.loadfile()) to the one from the original Hurdy code. If the error was not from a Hurdy chunk the msg is unchanged.

    Parameters:

    msg (string) – The error message.

    Returns:

    The modified message.

  • hurdy.tracebackErrHandler([msg][, level])

    Provides a traceback like Lua’s debug.traceback, but remaps the line numbers for Hurdy chunks obtained through hurdy.loadstring() or hurdy.loadfile().

    Parameters:
    • msg (string or nil) – The optional error message.

    • level (number or nil) – The optional level at which to start the traceback. Defaults to 2.

    Returns:

    The traceback string.

  • hurdy.generate_AST(source[, useResolver])

    Construct a table representing the abstract syntax tree (AST) of a string containing Hurdy code.

    Warning

    The format the output table is undocumented and may change in future releases.

    Parameters:
    • source (string) – String containing the Hurdy source code.

    • useResolver (boolean or nil) – An optional flag that 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. Defaults to to true if not provided or if nil is passed as the argument.

    Returns:

    The AST table.