# hslua-packaging

Utilities to package up Haskell functions and values into a Lua
module.

This package is part of HsLua, a Haskell framework built around
the embeddable scripting language Lua.

## Functions

It is rarely enough to just expose Haskell functions to Lua, they
must also be documented. This library allows to combine both into
one step, as one would do in source files.

Functions can be exposed to Lua if they follow the type

```
a_0 -> a_1 -> ... -> a_n -> LuaE e b
```

where each a~i~, 0 ≤ i ≤ n can be retrieved from the Lua stack.

Let’s look at an example: we want to expose the *factorial*
function, making use of Haskell’s arbitrary size integers. Below
is how we would document and expose it to Lua.

```
-- | Calculate the factorial of a number.
factorial :: DocumentedFunction Lua.Exception
factorial = defun "factorial"
### liftPure (\n -> product [1..n])
<#> n
=#> productOfNumbers
#? "Calculates the factorial of a positive integer."
`since` makeVersion [1,0,0]
where
n :: Parameter Lua.Exception Integer
n = parameter peekIntegral "integer"
"n"
"number for which the factorial is computed"
productOfNumbers :: FunctionResults Lua.Exception Integer
productOfNumbers =
functionResult pushIntegral "integer"
"produce of all numbers from 1 upto n"
```

This produces a value which can be pushed to Lua as a function

```
pushDocumentedFunction factorial
setglobal "factorial"
```

and can then be called from Lua

```
> factorial(4)
24
> factorial(23)
"25852016738884976640000"
```

The documentation can be rendered as Markdown with `renderFunction`

:

```
factorial (n)
Calculates the factorial of a positive integer.
*Since: 1.0.0*
Parameters:
n
: number for which the factorial is computed (integer)
Returns:
- product of all integers from 1 upto n (integer)
```