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)