hslua-core
Bindings to Lua, an embeddable scripting language
Version on this page: | 2.3.1 |
LTS Haskell 22.33: | 2.3.2 |
Stackage Nightly 2024-09-07: | 2.3.2 |
Latest on Hackage: | 2.3.2 |
hslua-core-2.3.1@sha256:07098032df954b0f437ca2ff79ce486b186f75bc910f2e838006d99169ddc0b8,4431
Module documentation for 2.3.1
hslua-core
Basic building blocks to interface Haskell and Lua in a Haskell-idiomatic style.
Overview
Lua is a small, well-designed, embeddable scripting language. It has become the de-facto default to make programs extensible and is widely used everywhere from servers over games and desktop applications up to security software and embedded devices. This package provides the basic building blocks for coders to embed Lua into their programs.
This package is part of HsLua, a Haskell framework built around the embeddable scripting language Lua.
Interacting with Lua
HsLua core provides the Lua
type to define Lua operations. The
operations are executed by calling run
. A simple “Hello, World”
program, using the Lua print
function, is given below:
import HsLua.Core.Lua as Lua
main :: IO ()
main = Lua.run prog
where
prog :: Lua ()
prog = do
Lua.openlibs -- load Lua libraries so we can use 'print'
Lua.getglobal "print" -- push print function
Lua.pushstring "Hello, World!" -- push string argument
Lua.call
(NumArgs 1) -- number of arguments passed to the function
(NumResults 0) -- number of results expected
-- as return values
The Lua stack
Lua’s API is stack-centered: most operations involve pushing
values to the stack or receiving items from the stack. E.g.,
calling a function is performed by pushing the function onto the
stack, followed by the function arguments in the order they should
be passed to the function. The API function call
then invokes
the function with given numbers of arguments, pops the function
and parameters off the stack, and pushes the results.
,----------.
| arg 3 |
+----------+
| arg 2 |
+----------+
| arg 1 |
+----------+ ,----------.
| function | call 3 1 | result 1 |
+----------+ ===========> +----------+
| | | |
| stack | | stack |
| | | |
This package provides all basic building blocks to interact with
the Lua stack. If you’d like more comfort, please consider using
the hslua-packaging
and hslua-classes
packages.
Error handling
Errors and exceptions must always be caught and converted when
passing language boundaries. The exception type which can be
handled is encoded as the type e
in the monad LuaE e
. Only
exceptions of this type may be thrown; throwing different
exceptions across language boundaries will lead to a program
crash.
Exceptions must support certain operations as defined by the
LuaError
typeclass. The class ensures that errors can be
converted from and to Lua values, and that a new exception can be
created from a String message.
Changes
Changelog
hslua-core
uses PVP Versioning.
hslua-core-2.3.1
Released 2023-03-17.
- New module HsLua.Core.Debug: the module provides bindings to
a subset of functions of the Lua debug interface. Currently
the module only exports
getupvalue
andsetupvalue
, both of which are also re-exported from HsLua.Core.
hslua-core-2.3.0
Released 2023-03-13.
-
The functions
loadfile
,dofile
, anddofileTrace
now expect the argument to be of typeMaybe FilePath
. The functions load from stdin when the argument isNothing
. -
Added
setwarnf'
for simple warning messgae handling: The built-in method of setting a warn function is flexible but not straight-forward to use. The newsetwarnf'
function allows to set a Haskell action as a warning hook: the default warning behavior is kept in place, but, in addition to the default action, the hook is called on the concatenated warning messages. This can be used to plug Lua warnings into an application specific Haskell reporting system. -
Export
GCManagedState
,newGCManagedState
,closeGCManagedState
, andwithGCManagedState
fromHsLua.Core
.
hslua-core-2.2.1
Released 2022-06-19.
-
Ensure that loadfile works with umlauts in filepath: The OS does not necessarily expect filenames to be UTF-8 encoded, especially Windows. On non-Windows systems, the current file system encoding is now used to convert filenames to C strings. On Windows, the
CP_ACP
codepage is used, as required by the Windows API. -
GC managed Lua state: Add new type
GCManagedState
and functionsnewGCManagedState
,closeGCManagedState
, andwithGCManagedState
. These allow to create and use a Lua state in flexible ways in that it does not require the state to be closed explicitly. The state will be closed when the respective variable is collected. -
Require lua-2.2.1.
-
Relax upper bound for mtl, allow mtl-2.3.
hslua-core-2.2.0
Released 2022-02-19.
-
Use lua-2.2.0, which requires Lua 5.4.
-
Rename
newuserdata
tonewuserdatauv
and let it take the number of associated uservalues as an additional argument.Similarly,
newhsuserdata
is nownewhsuserdatauv
. -
Rename
getuservalue
andsetuservalue
togetiuservalue
andsetiuservalue
, respectively. Like both functions now take an extra argument specifying the number of the uservalue that should be retrieved or set.It is now possible for
setiuservalue
to fail, so it returns a boolean to indicate whether the action was successful. -
The
GCControl
type has been updated to match the new gc control:- The GCStep constructor takes an argument “stepsize”;
- constructors GCGen and GCInc have been added;
- constructors GCSetPause and GCSetStepMul have been removed.
hslua-core-2.1.0
Released 29-01-2022.
-
The functions
rawget
,rawgeti
, andgetref
now return the type of the value that was pushed to the stack. -
A new function
checkstack'
is added to HsLua.Core.Auxiliary and exported from the main HsLua.Core module. The function throws an exception if the stack cannot be grown to accommodate a given number of elements; it is similar toluaL_checkstack
. -
Added function
requiref
, which safely wraps the unsafeluaL_requiref
function. -
New functions
pcallTrace
,callTrace
,dostringTrace
, anddofileTrace
: behaves like the respective unsuffixed functions, but use a message handler that creates a stack traceback on error. -
Added function
rotate
, wrappinglua_rotate
. -
Package helper
requirehs
signature changed torequirehs :: LuaError e => Name -- ^ modname -> (Name -> LuaE e ()) -- ^ openf -> LuaE e ()
The function creating and pushing the module value now takes the module name as an argument. It also behaves more like
luaL_requiref
in that it reloads the module if the value in the LOADED table is falsy.
hslua-core-2.0.0.2
Released 2021-11-03.
- Fixed output of
pushTypeMismatchError
when there is no value at the given index. Previously the function would report the value as typestring
and now reports it asno value
.
hslua-core-2.0.0.1
Released 2021-10-29.
- Fixed bug in pushTypeMismatchError. The function did not use an absolute stack index in one place, which sometimes lead to incorrect actual types being reported.
hslua-core-2.0.0
Released 2021-10-21.
-
Error handling has been reworked completely. The type of exceptions used and handled by HsLua is now exposed to the type system. The type
Lua
makes use of a default error type. Custom error handling can be implemented by using theLuaE
type with an exception type that is an instance of classLuaError
. -
Added new module HsLua.Core.Userdata. It contains thin wrappers around the functions available for creating Haskell-value-wrapping userdata objects.
-
Added new module HsLua.Core.Closures, containing functions to expose Haskell functions to Lua.
-
Reverted to using the auxlib
luaL_loadfile
function to load a Lua file. Previously files were opened and read in Haskell, but some functionality of the auxlib function was missing.
hslua-core-1.0.0
Released 2021-02-27.
Extracted from hslua-1.3.0.