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 topackage.searchers
(orpackage.loaders
in Lua 5.1) to allowrequire
to load Hurdy file (by compiling them as they are loaded)hurdy.path
has the same format aspackage.path
and is used byhurdy.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 ornil
.
- 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()
orhurdy.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()
orhurdy.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 ifnil
is passed as the argument.
- Returns:
The AST table.