hslua-packaging
Utilities to build Lua modules.
LTS Haskell 22.33: | 2.3.1 |
Stackage Nightly 2024-09-07: | 2.3.1 |
Latest on Hackage: | 2.3.1 |
hslua-packaging-2.3.1@sha256:f04713ca14c973fdd329ad26d4ffadc1d4df3512ef0e238a094d8c6caa3865e6,3797
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)
Changes
Changelog
hslua-packaging
uses PVP Versioning.
hslua-packaging-2.3.1
Released 2024-01-18.
- Relaxed upper bound for text and containers, allowing text-2.1, and containers-0.7.
hslua-packaging-2.3.0
Released 2023-03-13.
-
Type initializers as part of Module records. This allows to associate types with a module. For performance reasons, the types are not initialized when the module is pushed, but only on first use. However, the documentation Lua object for each module now has an additional field
types
. The new field contains a function that returns the names of all associated types. Calling the function will also initialize these types, thereby making the respective metatables available in the registry. -
Field records now have an additional
fieldType
entry. [API change] -
The
pushUD
function is now specialized to documented types. -
Export
initType
. The function ensures that the metatable of a type has been fully initialized. This can be helpful when the default method of lazy initialization is not desired, e.g. when the type object is to be inspected or extended. -
Re-export
udDocs
,udTypeSpec
, allowing to generate typing info for userdata classes.
hslua-packaging-2.2.1
Release 2022-06-19.
-
Require hslua-core-2.2.1.
-
Require hslua-marshalling-2.2.1.
-
Require hslua-objectorientation-2.2.1.
hslua-packaging-2.2.0.1
Released 2022-05-20.
- Relax upper bound for mtl, allow mtl-2.3.
hslua-packaging-2.2.0
Released 2022-02-19.
- Require versions 2.2 for hslua-core, hslua-marshalling, hslua-objectorientation.
hslua-packaging-2.1.0
Released 2022-01-29.
-
Added function
documentation
: The documented functiondocumentation
is added and exported from moduleHsLua.Packaging.Documentation
. It allows to retrieve the documentation of a given Lua object.This replaces
pushDocumentationFunction
, which was removed. -
Cleanup of Function module:
docsField
was moved to module Documentation.pushDocumentation
is renamed togetdocumentation
and moved to the Documentation module. It now returns the Lua type of the retrieved documentation value.
-
Function
registerDocumentation
was changed: the documentation is no longer passed in but must be at the top of the stack. -
New functions
pushModuleDoc
, andpushFunctionDoc
, pushing structured documentation objects for models and functions, respectively. -
Provide function
opt
to make a parameter optional. The functionoptionalParameter
is deprecated, useopt (parameter ...)
instead. -
Added function
udresult
; it defines a function result and is analogous to the existingudparam
function. -
Added module
Convenience
, which defines many functions to make the definition of parameters and results easier for the most common types. -
Pushing a documented module now also registers the module’s documentation.
-
The module HsLua.Packaging.Rendering has been deprecated. It is no longer exported as part of HsLua.Packaging and must be imported explicitly if needed. It may be removed in the future. Use Lua objects retrievable with
getdocumentation
together with a custom renderer instead. -
Update to hslua-objectorientation-2.1.0. Lists are now writable. This entails a change to
deftype'
. See the changelog of hslua-objectorientation for details. -
Update to hslua-core 2.1.0 and hslua-marshalling 2.1.0.
hslua-packaging-2.0.0
Released 2021-10-21.
-
Initially created. Contains modules previously found in the modules
Foreign.Lua.Call
andForeign.Lua.Module
fromhslua-1.3
. -
Moved module hierarchy from Foreign.Lua to HsLua.
-
Added support for a “since” tag on documented functions; allows to mark the library version when a function was introduced in its present form.
-
Improved syntax for the creation of documented functions.
-
Documentation for functions is now stored in Lua; a method to access it is available as a HaskellFunction.