Installation and use
====================

Installation
------------

Luarocks
^^^^^^^^

Both the compiler and Lua module can be installed using `LuaRocks <http://www.luarocks.org/>`_. First install
LuaRocks if you don't have it already, then run

.. code-block:: shell

  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 <https://codeberg.org/apicici/hurdy/releases>`_ of the git repository.

Source
^^^^^^

The source code for Hurdy can be found `here <https://codeberg.org/apicici/hurdy>`_. 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 :code:`hurdyc` can be run from the command line after installing it with LuaRocks or building it directly from source.
The executable has three subcommands:

- :code:`hurdyc file` compiles a single Hurdy file to Lua. If the output file is not specified the result will be printed to
  the screen.
- :code:`hurdyc folder` compiles recursively all files with extension :code:`.hurdy` file to Lua. The output folder must be specified,
  and the directory structure will be recreated.
- :code:`hurdyc ast` generates a JSON file containing the abstract syntax tree of a Hurdy file.

  .. warning::
    :code:`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 :code:`-h` flag, e.g.,

.. code-block:: shell

  hurdyc folder -h

Lua library
^^^^^^^^^^^

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

.. code-block:: lua

  local hurdy = require("hurdy")

The :code:`hurdy` tables includes the following fields

- :code:`hurdy.searcher` is a searcher function that can be added to :code:`package.searchers` (or :code:`package.loaders` in Lua 5.1)
  to allow :code:`require` to load Hurdy file (by compiling them as they are loaded)
- :code:`hurdy.path` has the same format as :code:`package.path` and is used by :code:`hurdy.searcher` to decide if a file should be
  loaded as Hurdy. Modify it as necessary.
- :code:`hurdy.compile` is a function that takes a string containing Hurdy code and returns a string with the compiled Lua code
- :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
- :code:`hurdy.loadfile` is a function that the filename of a Hurdy file, loads its content, and returns a compiled chuck that can be called to run it
- :code:`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)
- :code:`hurdy.tracebackErrHandler(msg, level)` provides a traceback like :code:`debug.traceback`, but remaps the line numbers for Hurdy chunks