hslua-0.3: A Lua language interpreter embedding in HaskellContentsIndex
Scripting.Lua
Portabilityportable, ffi
Stabilityalpha
Maintainergracjanpolak@gmail.com
Contents
High-level interface
Basic Lua types
Constants and enumerations
Extended functions
lua_* functions
luaL_* functions
Description

A Haskell wrapper library for a scripting language Lua. See http://www.lua.org/ for more details.

This module is intended to be imported qualified, eg.

 import qualified Scripting.Lua as Lua

This way we use Haskell module hierarchy to make Lua names shorter. Haskell functions are named after Lua functions, but the lua_ or luaL_ prefix.

Lua types are mapped to Haskell types as in the following table:

 int (stack index)        Int
 lua_Integer              LuaInteger
 lua_Number               LuaNumber
 int (bool result)        Bool
 const char * (string)    String
 void *                   Ptr ()
 lua_State *              LuaState

Most functions are one-to-one mappings. Rare special cases are clearly marked in this document.

Minimal sample embedding:

 import qualified Scripting.Lua as Lua
 main = do
     l <- Lua.newstate
     Lua.openlibs l
     Lua.callproc l "print" "Hello from Lua"
     Lua.close l
Synopsis
callproc :: LuaCallProc a => LuaState -> String -> a
callfunc :: LuaCallFunc a => LuaState -> String -> a
dofile :: LuaState -> FilePath -> IO Int
dostring :: LuaState -> String -> IO Int
luaimport :: LuaImport a => a -> LuaCFunction
register :: LuaImport a => LuaState -> String -> a -> IO ()
class StackValue a where
push :: LuaState -> a -> IO ()
peek :: LuaState -> Int -> IO (Maybe a)
valuetype :: a -> LTYPE
newtype LuaState = LuaState (Ptr ())
type LuaCFunction = LuaState -> IO CInt
type LuaInteger = CPtrdiff
type LuaNumber = CDouble
data GCCONTROL
= GCSTOP
| GCRESTART
| GCCOLLECT
| GCCOUNT
| GCCOUNTB
| GCSTEP
| GCSETPAUSE
| GCSETSTEPMUL
data LTYPE
= TNONE
| TNIL
| TBOOLEAN
| TLIGHTUSERDATA
| TNUMBER
| TSTRING
| TTABLE
| TFUNCTION
| TUSERDATA
| TTHREAD
multret :: Int
registryindex :: Int
environindex :: Int
globalsindex :: Int
getglobal2 :: LuaState -> String -> IO ()
newcfunction :: LuaImport a => a -> IO (FunPtr LuaCFunction)
freecfunction :: FunPtr LuaCFunction -> IO ()
pushfunction :: LuaImport a => LuaState -> a -> IO ()
atpanic :: LuaState -> FunPtr LuaCFunction -> IO (FunPtr LuaCFunction)
call :: LuaState -> Int -> Int -> IO Int
checkstack :: LuaState -> Int -> IO Bool
close :: LuaState -> IO ()
concat :: LuaState -> Int -> IO ()
cpcall :: LuaState -> FunPtr LuaCFunction -> Ptr a -> IO Int
createtable :: LuaState -> Int -> Int -> IO ()
dump :: LuaState -> IO String
equal :: LuaState -> Int -> Int -> IO Bool
gc :: LuaState -> GCCONTROL -> Int -> IO Int
getfenv :: LuaState -> Int -> IO ()
getfield :: LuaState -> Int -> String -> IO ()
getglobal :: LuaState -> String -> IO ()
getmetatable :: LuaState -> Int -> IO Bool
gettable :: LuaState -> Int -> IO ()
gettop :: LuaState -> IO Int
getupvalue :: LuaState -> Int -> Int -> IO String
insert :: LuaState -> Int -> IO ()
isboolean :: LuaState -> Int -> IO Bool
iscfunction :: LuaState -> Int -> IO Bool
isfunction :: LuaState -> Int -> IO Bool
islightuserdata :: LuaState -> Int -> IO Bool
isnil :: LuaState -> Int -> IO Bool
isnumber :: LuaState -> Int -> IO Bool
isstring :: LuaState -> Int -> IO Bool
istable :: LuaState -> Int -> IO Bool
isthread :: LuaState -> Int -> IO Bool
isuserdata :: LuaState -> Int -> IO Bool
lessthan :: LuaState -> Int -> Int -> IO Bool
newstate :: IO LuaState
newtable :: LuaState -> IO ()
newthread :: LuaState -> IO LuaState
newuserdata :: LuaState -> Int -> IO (Ptr ())
next :: LuaState -> Int -> IO Bool
objlen :: LuaState -> Int -> IO Int
pcall :: LuaState -> Int -> Int -> Int -> IO Int
pop :: LuaState -> Int -> IO ()
pushboolean :: LuaState -> Bool -> IO ()
pushcclosure :: LuaState -> FunPtr LuaCFunction -> Int -> IO ()
pushcfunction :: LuaState -> FunPtr LuaCFunction -> IO ()
pushinteger :: LuaState -> LuaInteger -> IO ()
pushlightuserdata :: LuaState -> Ptr a -> IO ()
pushnil :: LuaState -> IO ()
pushnumber :: LuaState -> LuaNumber -> IO ()
pushstring :: LuaState -> String -> IO ()
pushthread :: LuaState -> IO Bool
pushvalue :: LuaState -> Int -> IO ()
rawequal :: LuaState -> Int -> Int -> IO Bool
rawget :: LuaState -> Int -> IO ()
rawgeti :: LuaState -> Int -> Int -> IO ()
rawset :: LuaState -> Int -> IO ()
rawseti :: LuaState -> Int -> Int -> IO ()
registercfunction :: LuaState -> String -> FunPtr LuaCFunction -> IO ()
remove :: LuaState -> Int -> IO ()
replace :: LuaState -> Int -> IO ()
resume :: LuaState -> Int -> IO Int
setfenv :: LuaState -> Int -> IO Int
setfield :: LuaState -> Int -> String -> IO ()
setglobal :: LuaState -> String -> IO ()
setmetatable :: LuaState -> Int -> IO ()
settable :: LuaState -> Int -> IO ()
settop :: LuaState -> Int -> IO ()
setupvalue :: LuaState -> Int -> Int -> IO String
status :: LuaState -> IO Int
toboolean :: LuaState -> Int -> IO Bool
tocfunction :: LuaState -> Int -> IO (FunPtr LuaCFunction)
tointeger :: LuaState -> Int -> IO LuaInteger
tonumber :: LuaState -> Int -> IO CDouble
topointer :: LuaState -> Int -> IO (Ptr ())
tostring :: LuaState -> Int -> IO String
tothread :: LuaState -> Int -> IO LuaState
touserdata :: LuaState -> Int -> IO (Ptr a)
ltype :: LuaState -> Int -> IO LTYPE
typename :: LuaState -> LTYPE -> IO String
upvalueindex :: Int -> Int
xmove :: LuaState -> LuaState -> Int -> IO ()
yield :: LuaState -> Int -> IO Int
openlibs :: LuaState -> IO ()
loadfile :: LuaState -> String -> IO Int
loadstring :: LuaState -> String -> String -> IO Int
newmetatable :: LuaState -> String -> IO Int
argerror :: LuaState -> Int -> String -> IO CInt
High-level interface
callproc :: LuaCallProc a => LuaState -> String -> a

Call a Lua procedure. Use as:

 callproc l "proc" "abc" (1::Int) (5.0::Double)
callfunc :: LuaCallFunc a => LuaState -> String -> a

Call a Lua function. Use as:

 Just v <- callfunc l "proc" "abc" (1::Int) (5.0::Double)
dofile :: LuaState -> FilePath -> IO Int

Loads a Lua script file and executes it immediatelly. Use as:

 Lua.dofile l "myscript.lua"
 Just result <- Lua.peek l (-1)
dostring :: LuaState -> String -> IO Int

Loads a Lua script given as string parameter and executes it immediatelly | Loads a Lua script file and executes it immediatelly. Use as:

 Lua.dostring l "return 42"
 Just result <- Lua.peek l (-1)
luaimport :: LuaImport a => a -> LuaCFunction

Convert a Haskell function to Lua function. Any Haskell function can be converted provided that:

  • all arguments are instances of StackValue * return type is IO t, where t is an instance of StackValue

Any Haskell exception will be converted to a string and returned as Lua error.

register :: LuaImport a => LuaState -> String -> a -> IO ()
Imports a Haskell function and registers it at global name.
class StackValue a where

A value that can be pushed and poped from the Lua stack. All instances are natural, except following:

  • LuaState push ignores its argument, pushes current state
  • () push ignores its argument, just pushes nil
  • Ptr () pushes light user data, peek checks for lightuserdata or userdata
Methods
push :: LuaState -> a -> IO ()
Pushes a value onto Lua stack, casting it into meaningfully nearest Lua type.
peek :: LuaState -> Int -> IO (Maybe a)
Check if at index n there is a convertible Lua value and if so return it wrapped in Just. Return Nothing otherwise.
valuetype :: a -> LTYPE
Lua type id code of the vaule expected. Parameter is unused.
show/hide Instances
Basic Lua types
newtype LuaState
Wrapper for lua_State *. See lua_State in Lua Reference Manual.
Constructors
LuaState (Ptr ())
show/hide Instances
type LuaCFunction = LuaState -> IO CInt
Wrapper for lua_CFunction. See lua_CFunction in Lua Reference Manual.
type LuaInteger = CPtrdiff
Wrapper for lua_Integer. See lua_Integer in Lua Reference Manual. HsLua uses C ptrdiff_t as lua_Integer.
type LuaNumber = CDouble
Wrapper for lua_Number. See lua_Number in Lua Reference Manual. HsLua uses C double as lua_Integer.
Constants and enumerations
data GCCONTROL
Enumeration used by gc function.
Constructors
GCSTOP
GCRESTART
GCCOLLECT
GCCOUNT
GCCOUNTB
GCSTEP
GCSETPAUSE
GCSETSTEPMUL
show/hide Instances
data LTYPE
Enumeration used as type tag. See lua_type in Lua Reference Manual.
Constructors
TNONE
TNIL
TBOOLEAN
TLIGHTUSERDATA
TNUMBER
TSTRING
TTABLE
TFUNCTION
TUSERDATA
TTHREAD
show/hide Instances
multret :: Int
See LUA_MULTRET in Lua Reference Manual.
registryindex :: Int
See LUA_REGISTRYINDEX in Lua Reference Manual.
environindex :: Int
See LUA_ENVIRONINDEX in Lua Reference Manual.
globalsindex :: Int
See LUA_GLOBALSINDEX in Lua Reference Manual.
Extended functions
getglobal2 :: LuaState -> String -> IO ()

Like getglobal, but knows about packages. e. g.

 getglobal l "math.sin"

returns correct result

newcfunction :: LuaImport a => a -> IO (FunPtr LuaCFunction)
Create new foreign Lua function. Function created can be called by Lua engine. Remeber to free the pointer with freecfunction.
freecfunction :: FunPtr LuaCFunction -> IO ()
Free function pointer created with newcfunction.
pushfunction :: LuaImport a => LuaState -> a -> IO ()

Pushes Haskell function converted to a Lua function. All values created will be garbage collected. Use as:

 Lua.pushfunction l myfun
 Lua.setglobal l "myfun"

You are not allowed to use lua_error anywhere, but use an error code of (-1) to the same effect. Push error message as the sole return value.

lua_* functions
atpanic :: LuaState -> FunPtr LuaCFunction -> IO (FunPtr LuaCFunction)
See lua_atpanic in Lua Reference Manual.
call :: LuaState -> Int -> Int -> IO Int
See lua_call and lua_call in Lua Reference Manual. This is a wrapper over lua_pcall, as lua_call is unsafe in controlled environment like Haskell VM.
checkstack :: LuaState -> Int -> IO Bool
See lua_checkstack in Lua Reference Manual.
close :: LuaState -> IO ()
See lua_close in Lua Reference Manual.
concat :: LuaState -> Int -> IO ()
See lua_concat in Lua Reference Manual.
cpcall :: LuaState -> FunPtr LuaCFunction -> Ptr a -> IO Int
See lua_cpcall in Lua Reference Manual.
createtable :: LuaState -> Int -> Int -> IO ()
See lua_createtable in Lua Reference Manual.
dump :: LuaState -> IO String
equal :: LuaState -> Int -> Int -> IO Bool
See lua_equal in Lua Reference Manual.
gc :: LuaState -> GCCONTROL -> Int -> IO Int

See lua_error in Lua Reference Manual. error :: LuaState -> IO Int error l = liftM fromIntegral (c_lua_error l)

See lua_gc in Lua Reference Manual.

getfenv :: LuaState -> Int -> IO ()
See lua_getfenv in Lua Reference Manual.
getfield :: LuaState -> Int -> String -> IO ()
See lua_getfield in Lua Reference Manual.
getglobal :: LuaState -> String -> IO ()
See lua_getglobal in Lua Reference Manual.
getmetatable :: LuaState -> Int -> IO Bool
See lua_getmetatable in Lua Reference Manual.
gettable :: LuaState -> Int -> IO ()
See lua_gettable in Lua Reference Manual.
gettop :: LuaState -> IO Int
See lua_gettop in Lua Reference Manual.
getupvalue :: LuaState -> Int -> Int -> IO String
See lua_getupvalue in Lua Reference Manual.
insert :: LuaState -> Int -> IO ()
See lua_insert in Lua Reference Manual.
isboolean :: LuaState -> Int -> IO Bool
See lua_isboolean in Lua Reference Manual.
iscfunction :: LuaState -> Int -> IO Bool
See lua_iscfunction in Lua Reference Manual.
isfunction :: LuaState -> Int -> IO Bool
See lua_isfunction in Lua Reference Manual.
islightuserdata :: LuaState -> Int -> IO Bool
See lua_islightuserdata in Lua Reference Manual.
isnil :: LuaState -> Int -> IO Bool
See lua_isnil in Lua Reference Manual.
isnumber :: LuaState -> Int -> IO Bool
See lua_isnumber in Lua Reference Manual.
isstring :: LuaState -> Int -> IO Bool
See lua_isstring in Lua Reference Manual.
istable :: LuaState -> Int -> IO Bool
See lua_istable in Lua Reference Manual.
isthread :: LuaState -> Int -> IO Bool
See lua_isthread in Lua Reference Manual.
isuserdata :: LuaState -> Int -> IO Bool
See lua_isuserdata in Lua Reference Manual.
lessthan :: LuaState -> Int -> Int -> IO Bool
See lua_lessthan in Lua Reference Manual.
newstate :: IO LuaState
See lua_newstate and luaL_newstate in Lua Reference Manual.
newtable :: LuaState -> IO ()
See lua_newtable in Lua Reference Manual.
newthread :: LuaState -> IO LuaState
See lua_newthread in Lua Reference Manual.
newuserdata :: LuaState -> Int -> IO (Ptr ())
See lua_newuserdata in Lua Reference Manual.
next :: LuaState -> Int -> IO Bool
See lua_next in Lua Reference Manual.
objlen :: LuaState -> Int -> IO Int
See lua_objlen in Lua Reference Manual.
pcall :: LuaState -> Int -> Int -> Int -> IO Int
See lua_pcall in Lua Reference Manual.
pop :: LuaState -> Int -> IO ()
See lua_pop in Lua Reference Manual.
pushboolean :: LuaState -> Bool -> IO ()
See lua_pushboolean in Lua Reference Manual.
pushcclosure :: LuaState -> FunPtr LuaCFunction -> Int -> IO ()
See lua_pushcclosure in Lua Reference Manual.
pushcfunction :: LuaState -> FunPtr LuaCFunction -> IO ()
See lua_pushcfunction in Lua Reference Manual.
pushinteger :: LuaState -> LuaInteger -> IO ()
See lua_pushinteger in Lua Reference Manual.
pushlightuserdata :: LuaState -> Ptr a -> IO ()
See lua_pushlightuserdata in Lua Reference Manual.
pushnil :: LuaState -> IO ()
See lua_pushnil in Lua Reference Manual.
pushnumber :: LuaState -> LuaNumber -> IO ()
See lua_pushnumber in Lua Reference Manual.
pushstring :: LuaState -> String -> IO ()
See lua_pushstring in Lua Reference Manual.
pushthread :: LuaState -> IO Bool
See lua_pushthread in Lua Reference Manual.
pushvalue :: LuaState -> Int -> IO ()
See lua_pushvalue in Lua Reference Manual.
rawequal :: LuaState -> Int -> Int -> IO Bool
See lua_rawequal in Lua Reference Manual.
rawget :: LuaState -> Int -> IO ()
See lua_rawget in Lua Reference Manual.
rawgeti :: LuaState -> Int -> Int -> IO ()
See lua_rawgeti in Lua Reference Manual.
rawset :: LuaState -> Int -> IO ()
See lua_rawset in Lua Reference Manual.
rawseti :: LuaState -> Int -> Int -> IO ()
See lua_rawseti in Lua Reference Manual.
registercfunction :: LuaState -> String -> FunPtr LuaCFunction -> IO ()
See lua_register in Lua Reference Manual.
remove :: LuaState -> Int -> IO ()
See lua_remove in Lua Reference Manual.
replace :: LuaState -> Int -> IO ()
See lua_replace in Lua Reference Manual.
resume :: LuaState -> Int -> IO Int
See lua_resume in Lua Reference Manual.
setfenv :: LuaState -> Int -> IO Int
See lua_setfenv in Lua Reference Manual.
setfield :: LuaState -> Int -> String -> IO ()
See lua_setfield in Lua Reference Manual.
setglobal :: LuaState -> String -> IO ()
See lua_setglobal in Lua Reference Manual.
setmetatable :: LuaState -> Int -> IO ()
See lua_setmetatable in Lua Reference Manual.
settable :: LuaState -> Int -> IO ()
See lua_settable in Lua Reference Manual.
settop :: LuaState -> Int -> IO ()
See lua_settop in Lua Reference Manual.
setupvalue :: LuaState -> Int -> Int -> IO String
See lua_setupvalue in Lua Reference Manual.
status :: LuaState -> IO Int
See lua_status in Lua Reference Manual.
toboolean :: LuaState -> Int -> IO Bool
See lua_toboolean in Lua Reference Manual.
tocfunction :: LuaState -> Int -> IO (FunPtr LuaCFunction)
See lua_tocfunction in Lua Reference Manual.
tointeger :: LuaState -> Int -> IO LuaInteger
See lua_tointeger in Lua Reference Manual.
tonumber :: LuaState -> Int -> IO CDouble
See lua_tonumber in Lua Reference Manual.
topointer :: LuaState -> Int -> IO (Ptr ())
See lua_topointer in Lua Reference Manual.
tostring :: LuaState -> Int -> IO String
See lua_tostring in Lua Reference Manual.
tothread :: LuaState -> Int -> IO LuaState
See lua_tothread in Lua Reference Manual.
touserdata :: LuaState -> Int -> IO (Ptr a)
See lua_touserdata in Lua Reference Manual.
ltype :: LuaState -> Int -> IO LTYPE
See lua_type in Lua Reference Manual.
typename :: LuaState -> LTYPE -> IO String
See lua_typename in Lua Reference Manual.
upvalueindex :: Int -> Int
See lua_upvalueindex in Lua Reference Manual.
xmove :: LuaState -> LuaState -> Int -> IO ()
See lua_xmove in Lua Reference Manual.
yield :: LuaState -> Int -> IO Int
See lua_yield in Lua Reference Manual.
luaL_* functions
openlibs :: LuaState -> IO ()
See luaL_openlibs in Lua Reference Manual.
loadfile :: LuaState -> String -> IO Int
See luaL_loadfile in Lua Reference Manual.
loadstring :: LuaState -> String -> String -> IO Int
See luaL_loadstring in Lua Reference Manual.
newmetatable :: LuaState -> String -> IO Int
See luaL_newmetatable in Lua Reference Manual.
argerror :: LuaState -> Int -> String -> IO CInt
See luaL_argerror in Lua Reference Manual. Contrary to the manual, Haskell function does return with value less than zero.
Produced by Haddock version 2.5.0