lua
Lua, an embeddable scripting language
Version on this page: | 2.3.1 |
LTS Haskell 22.37: | 2.3.3 |
Stackage Nightly 2024-10-07: | 2.3.3 |
Latest on Hackage: | 2.3.3 |
lua-2.3.1@sha256:df1a55be3b7bb3ec1dd2e994e9b90b0f738e90721b29466b0d034c0ab85568a7,7914
Module documentation for 2.3.1
lua
The lua package provides a Lua interpreter as well as bindings, wrappers and types to combine Haskell and Lua.
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 Haskell bindings to Lua, enable coders to embed the language into their programs, making them scriptable.
This package ships with the official Lua interpreter, version 5.4.4. Cabal flags allow to compile against a system-wide Lua installation instead, if desired.
Build flags
The following cabal build flags are supported:
-
system-lua
: Use the locally installed Lua version instead of the version shipped as part of this package. -
pkg-config
: Use pkg-config to discover library and include paths. Setting this flag impliessystem-lua
. -
allow-unsafe-gc
: Allow optimizations which make Lua’s garbage collection potentially unsafe; enabling this should be safe if there are no callbacks into Haskell during Lua garbage collection cycles. The flag should be disabled if Lua objects can have Haskell finalizers, i.e.,__gc
metamethods that call Haskell function.The flag is enabled per default, as Haskell functions are rarely used in finalizers. It can help to disable the flag if there are issues related to Lua’s garbage collection.
-
apicheck
: Compile Lua with its API checks enabled. -
lua_32bits
: Compile Lua for a 32-bits system (e.g., i386, PowerPC G4). -
export-dynamic
: Add all symbols to dynamic symbol table; disabling this will make it possible to create fully static binaries, but renders loading of dynamic C libraries impossible.
Example: using a different Lua version
To use a system-wide installed Lua when linking lua as a
dependency, build/install your package using
--constraint="lua +system-lua"
. For example, you can
install Pandoc with hslua that uses system-wide Lua like this:
cabal install pandoc --constraint="lua +system-lua"
or with stack:
stack install pandoc --flag=lua:system-lua
Changes
Changelog
lua
uses PVP Versioning.
lua-2.3.1
Released 2023-03-17.
- New module Lua.Debug: the module provides bindings to a
subset of functions of the Lua debug interface. Currently the
module only binds
lua_getupvalue
andlua_setupvalue
.
lua-2.3.0
Released 2023-03-13.
-
New function
hslua_setwarnf
: The function allows to set a C function as a hook that is called on all complete warning messages. It is intended as a simple way to set a custom warning function. -
Export version and copyright info from Lua.Constants: the following patterns are made available, with content identical to that of the respective C functions:
LUA_VERSION
,LUA_RELEASE
, andLUA_COPYRIGHT
. -
Added a new flag
cross-compile
. When enabled, the code is setup in a way that allows cross-compilation of the package, but some of the string constants will be hard-coded and may not match the Lua version against which the library is compiled. -
Type
is now an instance ofRead
.
lua-2.2.1
Released 2022-06-19.
- Make string-peeking independent of the current foreign
encoding: always use char8 encoding to retrieve values of
LUA_PRELOAD_TABLE
andLUA_LOADED_TABLE
.
lua-2.2.0
Released 2022-02-19.
-
Update to Lua 5.4, include Lua 5.4.4 by default.
-
Removed
hardcode-reg-keys
flag: this is no longer required for Lua 5.4. -
Support arbitrary number of uservalues: Lua 5.4 allows an arbitrary number of uservalues to be associated with userdata objects. The functions
lua_newuserdata
,lua_getuservalue
, andlua_setuservalue
are replaced with the new functionslua_newuserdatauv
,lua_getiuservalue
, andlua_setiuservalue
, respectively.The function
hslua_newhsuserdata
is renamed tohslua_newhsuserdatauv
and takes the number of associated uservalues as an additional argument. -
Support for the new warnings system: export binding to
lua_warning
. -
The function
lua_gc
now takes three data arguments of type CInt. This is a workaround for the fact that the C function has become variadic. -
The new patterns
LUA_GCGEN
andLUA_GCINC
are usable withlua_gc
to switch to generational and incremental garbage collection, respectively.
lua-2.1.0
Released 29-01-2022.
-
The functions
lua_rawget
andlua_rawgeti
now return the type of the value that was pushed to the stack. -
Added bindings to unsafe function
lua_arith
. A new typeArithOPCode
for arithmetic operations is added, as are pattern synonyms for the supported operations. These are:- LUA_OPADD
- LUA_OPSUB
- LUA_OPMUL
- LUA_OPDIV
- LUA_OPIDIV
- LUA_OPMOD
- LUA_OPPOW
- LUA_OPUNM
- LUA_OPBNOT
- LUA_OPBAND
- LUA_OPBOR
- LUA_OPBXOR
- LUA_OPSHL
- LUA_OPSHR
-
Added ersatz functions
hslua_arith
andhsluaL_requiref
, wrappinglua_artih
andluaL_requiref
, respectively. Both functions catch any error resulting from the call. -
Made types
OPCode
,StatusCode
, andGCCode
instances of type classShow
. -
The
Show
instances of Integer and Number now behave like those of the wrapped types. Both types are now also instance ofRead
. -
Removed
hslua_userdata_gc
fromhslua.h
.
lua-2.0.2
Released 2021-11-26.
- Make sure lualib.h is available through this package. The header file contains info on how and under which name the standard library is loaded.
lua-2.0.1
Released 2021-11-03.
- Added bindings to
lua_rotate
andlua_version
.
lua-2.0.0.1
Released 2021-10-30.
- Only install includes when using the Lua code shipped with the package (Ellie Hermaszewska). Cabal no longer tries to install the header files if a system-wide installation is used.
lua-2.0.0
Released 2021-10-21.
-
Module hierarchy moved from
Foreign.Lua.Raw
toLua
. -
Documentation has been improved.
-
Added new function
withNewState
to run Lua operations. -
New modules
Lua.Ersatz
containing all bindings to safe ersatz functions. -
Higher level and enum types have been removed, only the low-level “code” types are kept in this package.
-
Constants are now represented as pattern synonyms like
LUA_OK
. -
Provide bindings to more functions:
lua_is...
type-checking functions;lua_pushstring
to push plain CStrings;- auxiliary functions
luaL_loadfile
, andluaL_loadfilex
;
- unsafe functions
lua_gettable
,lua_settable
,lua_getglobal
, andlua_setglobal
.
-
The function
lua_pop
now expects aCInt
instead of aStackIndex
. -
New StackIndex constructor functions
nthTop
,nthBottom
,nth
, andtop
. -
Avoid unnecessary modification of HSFUN metatable.
-
Various cleanups and test improvements.
lua-1.0.0
Released 2021-02-18.
- Initially created. Contains all modules in the
Foreign.Lua.Raw
hierarchy fromhslua-1.3
. Documentation has been improved.