Scripting.Lua

hslua-0.4.1: A Lua language interpreter embedding in Haskell

Safe Haskell | None
Language | Haskell98

Scripting.Lua

Contents

- Error handling in hslua
- A note about integer functions

Synopsis

- data LuaState
- type LuaCFunction = LuaState -> IO CInt
- type LuaInteger = Int32
- type LuaNumber = Double
- data LTYPE
  - = TNONE
  - | TNIL
  - | TBOOLEAN
  - | TLIGHTUSERDATA
  - | TNUMBER
  - | TSTRING
  - | TTABLE
  - | TFUNCTION
  - | TUSERDATA
  - | TTHREAD
- data GCCONTROL
  - = GCSTOP
  - | GCRESTART
  - | GCCOLLECT
  - | GCCOUNT
  - | GCCOUNTB
  - | GCSTEP
  - | GCSETPAUSE
  - | GCSETSTEPMUL
- multret :: Int
- settop :: LuaState -> Int -> IO ()
- createtable :: LuaState -> Int -> Int -> IO ()
- objlen :: LuaState -> Int -> IO Int
- pop :: LuaState -> Int -> IO ()
- newtable :: LuaState -> IO ()
- pushcclosure :: LuaState -> FunPtr LuaCFunction -> Int -> IO ()
- pushcfunction :: LuaState -> FunPtr LuaCFunction -> IO ()
- strlen :: LuaState -> Int -> IO Int
- ltype :: LuaState -> Int -> IO LTYPE
- isfunction :: LuaState -> Int -> IO Bool
- istable :: LuaState -> Int -> IO Bool
- tolist :: StackValue a => LuaState -> Int -> IO (Maybe [a])
- islightuserdata :: LuaState -> Int -> IO Bool
- isnil :: LuaState -> Int -> IO Bool
- isboolean :: LuaState -> Int -> IO Bool
- isthread :: LuaState -> Int -> IO Bool
- isnone :: LuaState -> Int -> IO Bool
- isnoneornil :: LuaState -> Int -> IO Bool
- registryindex :: Int
- environindex :: Int
- globalsindex :: Int
- upvalueindex :: Int -> Int
- atpanic :: LuaState -> FunPtr LuaCFunction -> IO (FunPtr LuaCFunction)
- tostring :: LuaState -> Int -> IO ByteString
- tothread :: LuaState -> Int -> IO LuaState
- touserdata :: LuaState -> Int -> IO (Ptr a)
- typename :: LuaState -> LTYPE -> IO String
- xmove :: LuaState -> LuaState -> Int -> IO ()
- yield :: LuaState -> Int -> IO Int
- checkstack :: LuaState -> Int -> IO Bool
- newstate :: IO LuaState
- close :: LuaState -> IO ()
- concat :: LuaState -> Int -> IO ()
- call :: LuaState -> Int -> Int -> IO ()
- pcall :: LuaState -> Int -> Int -> Int -> IO Int
- cpcall :: LuaState -> FunPtr LuaCFunction -> Ptr a -> IO Int
- getfield :: LuaState -> Int -> String -> IO ()
- setfield :: LuaState -> Int -> String -> IO ()
- getglobal :: LuaState -> String -> IO ()
- setglobal :: LuaState -> String -> IO ()
- openlibs :: LuaState -> IO ()
- mkStringWriter :: LuaWriter -> IO (FunPtr LuaWriter)
- dump :: LuaState -> IO String
- equal :: LuaState -> Int -> Int -> IO Bool
- lerror :: LuaState -> IO Int
- gc :: LuaState -> GCCONTROL -> Int -> IO Int
- getfenv :: LuaState -> Int -> IO ()
- getmetatable :: LuaState -> Int -> IO Bool
- gettable :: LuaState -> Int -> IO ()
- gettop :: LuaState -> IO Int
- insert :: LuaState -> Int -> IO ()
- iscfunction :: LuaState -> Int -> IO Bool
- isnumber :: LuaState -> Int -> IO Bool
- isstring :: LuaState -> Int -> IO Bool
- isuserdata :: LuaState -> Int -> IO Bool
- lessthan :: LuaState -> Int -> Int -> IO Bool
- loadfile :: LuaState -> String -> IO Int
- mkStringReader :: LuaReader -> IO (FunPtr LuaReader)
- loadstring :: LuaState -> String -> String -> IO Int
- newthread :: LuaState -> IO LuaState
- newuserdata :: LuaState -> Int -> IO (Ptr ())
- next :: LuaState -> Int -> IO Bool
- pushboolean :: LuaState -> Bool -> IO ()
- pushinteger :: LuaState -> LuaInteger -> IO ()
- pushlightuserdata :: LuaState -> Ptr a -> IO ()
- pushnil :: LuaState -> IO ()
- pushnumber :: LuaState -> LuaNumber -> IO ()
- pushstring :: LuaState -> ByteString -> IO ()
- pushlist :: StackValue a => LuaState -> [a] -> 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 ()
- remove :: LuaState -> Int -> IO ()
- replace :: LuaState -> Int -> IO ()
- resume :: LuaState -> Int -> IO Int
- setfenv :: LuaState -> Int -> IO Int
- setmetatable :: LuaState -> Int -> IO ()
- settable :: LuaState -> Int -> IO ()
- status :: LuaState -> IO Int
- toboolean :: LuaState -> Int -> IO Bool
- tocfunction :: LuaState -> Int -> IO (FunPtr LuaCFunction)
- tointeger :: LuaState -> Int -> IO LuaInteger
- tonumber :: LuaState -> Int -> IO LuaNumber
- topointer :: LuaState -> Int -> IO (Ptr ())
- register :: LuaState -> String -> FunPtr LuaCFunction -> IO ()
- newmetatable :: LuaState -> String -> IO Int
- argerror :: LuaState -> Int -> String -> IO CInt
- ref :: LuaState -> Int -> IO Int
- unref :: LuaState -> Int -> Int -> IO ()
- class StackValue a where
- maybepeek :: l -> n -> (l -> n -> IO Bool) -> (l -> n -> IO r) -> IO (Maybe r)
- getglobal2 :: LuaState -> String -> IO ()
- typenameindex :: LuaState -> Int -> IO String
- class LuaImport a where
- mkWrapper :: LuaCFunction -> IO (FunPtr LuaCFunction)
- newcfunction :: LuaImport a => a -> IO (FunPtr LuaCFunction)
- luaimport :: LuaImport a => a -> LuaCFunction
- freecfunction :: FunPtr LuaCFunction -> IO ()
- class LuaCallProc a where
- callproc :: LuaCallProc a => LuaState -> String -> a
- class LuaCallFunc a where
- callfunc :: LuaCallFunc a => LuaState -> String -> a
- hsmethod__gc_addr :: FunPtr LuaCFunction
- hsmethod__call_addr :: FunPtr LuaCFunction
- hsmethod__gc :: LuaState -> IO CInt
- hsmethod__call :: LuaState -> IO CInt
- pushhsfunction :: LuaImport a => LuaState -> a -> IO ()
- pushrawhsfunction :: LuaState -> LuaCFunction -> IO ()
- registerhsfunction :: LuaImport a => LuaState -> String -> a -> IO ()
- registerrawhsfunction :: LuaState -> String -> (LuaState -> IO CInt) -> IO ()

# Documentation

data LuaState #

Synonym for `lua_State *`. See `lua_State` in Lua Reference Manual.

Instances

StackValue LuaState # |
Methods push :: LuaState -> LuaState -> IO () # peek :: LuaState -> Int -> IO (Maybe LuaState) # valuetype :: LuaState -> LTYPE #
StackValue (FunPtr LuaCFunction) # |
Methods push :: LuaState -> FunPtr LuaCFunction -> IO () # peek :: LuaState -> Int -> IO (Maybe (FunPtr LuaCFunction)) # valuetype :: FunPtr LuaCFunction -> LTYPE #

type LuaCFunction = LuaState -> IO CInt #

Synonym for `lua_CFunction`. See `lua_CFunction` in Lua Reference Manual.

type LuaInteger = Int32 #

Synonym for `lua_Integer`. See `lua_Integer` in Lua Reference Manual.

type LuaNumber = Double #

Synonym for `lua_Number`. See `lua_Number` in Lua Reference Manual.

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 |

Instances

Enum LTYPE # |
Methods succ :: LTYPE -> LTYPE # pred :: LTYPE -> LTYPE # toEnum :: Int -> LTYPE # fromEnum :: LTYPE -> Int # enumFrom :: LTYPE -> [LTYPE] # enumFromThen :: LTYPE -> LTYPE -> [LTYPE] # enumFromTo :: LTYPE -> LTYPE -> [LTYPE] # enumFromThenTo :: LTYPE -> LTYPE -> LTYPE -> [LTYPE] #
Eq LTYPE # |
Methods (==) :: LTYPE -> LTYPE -> Bool # (/=) :: LTYPE -> LTYPE -> Bool #
Ord LTYPE # |
Methods compare :: LTYPE -> LTYPE -> Ordering # (<) :: LTYPE -> LTYPE -> Bool # (<=) :: LTYPE -> LTYPE -> Bool # (>) :: LTYPE -> LTYPE -> Bool # (>=) :: LTYPE -> LTYPE -> Bool # max :: LTYPE -> LTYPE -> LTYPE # min :: LTYPE -> LTYPE -> LTYPE #
Show LTYPE # |
Methods showsPrec :: Int -> LTYPE -> ShowS # show :: LTYPE -> String # showList :: [LTYPE] -> ShowS #

data GCCONTROL #

Enumeration used by `gc` function.

Constructors

GCSTOP |
GCRESTART |
GCCOLLECT |
GCCOUNT |
GCCOUNTB |
GCSTEP |
GCSETPAUSE |
GCSETSTEPMUL |

Instances

Enum GCCONTROL # |
Methods succ :: GCCONTROL -> GCCONTROL # pred :: GCCONTROL -> GCCONTROL # toEnum :: Int -> GCCONTROL # fromEnum :: GCCONTROL -> Int # enumFrom :: GCCONTROL -> [GCCONTROL] # enumFromThen :: GCCONTROL -> GCCONTROL -> [GCCONTROL] # enumFromTo :: GCCONTROL -> GCCONTROL -> [GCCONTROL] # enumFromThenTo :: GCCONTROL -> GCCONTROL -> GCCONTROL -> [GCCONTROL] #
Eq GCCONTROL # |
Methods (==) :: GCCONTROL -> GCCONTROL -> Bool # (/=) :: GCCONTROL -> GCCONTROL -> Bool #
Ord GCCONTROL # |
Methods compare :: GCCONTROL -> GCCONTROL -> Ordering # (<) :: GCCONTROL -> GCCONTROL -> Bool # (<=) :: GCCONTROL -> GCCONTROL -> Bool # (>) :: GCCONTROL -> GCCONTROL -> Bool # (>=) :: GCCONTROL -> GCCONTROL -> Bool # max :: GCCONTROL -> GCCONTROL -> GCCONTROL # min :: GCCONTROL -> GCCONTROL -> GCCONTROL #
Show GCCONTROL # |
Methods showsPrec :: Int -> GCCONTROL -> ShowS # show :: GCCONTROL -> String # showList :: [GCCONTROL] -> ShowS #

multret :: Int #

See `LUA_MULTRET` in Lua Reference Manual.

settop :: LuaState -> Int -> IO () #

See `lua_settop` in Lua Reference Manual.

createtable :: LuaState -> Int -> Int -> IO () #

See `lua_createtable` in Lua Reference Manual.

objlen :: LuaState -> Int -> IO Int #

See `lua_objlen` in Lua Reference Manual.

pop :: LuaState -> Int -> IO () #

See `lua_pop` in Lua Reference Manual.

newtable :: LuaState -> IO () #

See `lua_newtable` 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.

strlen :: LuaState -> Int -> IO Int #

See `lua_strlen` in Lua Reference Manual.

ltype :: LuaState -> Int -> IO LTYPE #

See `lua_type` in Lua Reference Manual.

isfunction :: LuaState -> Int -> IO Bool #

See `lua_isfunction` in Lua Reference Manual.

istable :: LuaState -> Int -> IO Bool #

See `lua_istable` in Lua Reference Manual.

tolist :: StackValue a => LuaState -> Int -> IO (Maybe [a]) #

Try to convert Lua array at given index to Haskell list.

islightuserdata :: LuaState -> Int -> IO Bool #

See `lua_islightuserdata` in Lua Reference Manual.

isnil :: LuaState -> Int -> IO Bool #

See `lua_isnil` in Lua Reference Manual.

isboolean :: LuaState -> Int -> IO Bool #

See `lua_isboolean` in Lua Reference Manual.

isthread :: LuaState -> Int -> IO Bool #

See `lua_isthread` in Lua Reference Manual.

isnone :: LuaState -> Int -> IO Bool #

See `lua_none` in Lua Reference Manual.

isnoneornil :: LuaState -> Int -> IO Bool #

See `lua_noneornil` 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.

upvalueindex :: Int -> Int #

See `lua_upvalueindex` in Lua Reference Manual.

atpanic :: LuaState -> FunPtr LuaCFunction -> IO (FunPtr LuaCFunction) #

See `lua_atpanic` in Lua Reference Manual.

tostring :: LuaState -> Int -> IO ByteString #

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.

typename :: LuaState -> LTYPE -> IO String #

See `lua_typename` 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.

checkstack :: LuaState -> Int -> IO Bool #

See `lua_checkstack` in Lua Reference Manual.

newstate :: IO LuaState #

See `lua_newstate` and `luaL_newstate` 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.

call :: LuaState -> Int -> Int -> IO () #

See `lua_call` and `lua_call` in Lua Reference Manual.

pcall :: LuaState -> Int -> Int -> Int -> IO Int #

See `lua_pcall` in Lua Reference Manual.

cpcall :: LuaState -> FunPtr LuaCFunction -> Ptr a -> IO Int #

See `lua_cpcall` in Lua Reference Manual.

getfield :: LuaState -> Int -> String -> IO () #

See `lua_getfield` in Lua Reference Manual.

setfield :: LuaState -> Int -> String -> IO () #

See `lua_setfield` in Lua Reference Manual.

getglobal :: LuaState -> String -> IO () #

See `lua_getglobal` in Lua Reference Manual.

setglobal :: LuaState -> String -> IO () #

See `lua_setglobal` in Lua Reference Manual.

openlibs :: LuaState -> IO () #

See `luaL_openlibs` in Lua Reference Manual.

mkStringWriter :: LuaWriter -> IO (FunPtr LuaWriter) #

dump :: LuaState -> IO String #

See `lua_dump` in Lua Reference Manual.

equal :: LuaState -> Int -> Int -> IO Bool #

See `lua_equal` in Lua Reference Manual.

lerror :: LuaState -> IO Int #

This is a convenience function to implement error propagation convention described in Error handling in hslua. hslua doesn't implement `lua_error` function from Lua C API because it's never safe to use. (see Error handling in hslua for details)

gc :: LuaState -> GCCONTROL -> Int -> IO Int #

See `lua_gc` in Lua Reference Manual.

getfenv :: LuaState -> Int -> IO () #

See `lua_getfenv` 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.

insert :: LuaState -> Int -> IO () #

See `lua_insert` in Lua Reference Manual.

iscfunction :: LuaState -> Int -> IO Bool #

See `lua_iscfunction` 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.

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.

loadfile :: LuaState -> String -> IO Int #

See `luaL_loadfile` in Lua Reference Manual.

mkStringReader :: LuaReader -> IO (FunPtr LuaReader) #

loadstring :: LuaState -> String -> String -> IO Int #

See `luaL_loadstring` 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.

pushboolean :: LuaState -> Bool -> IO () #

See `lua_pushboolean` 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 -> ByteString -> IO () #

See `lua_pushstring` in Lua Reference Manual.

pushlist :: StackValue a => LuaState -> [a] -> IO () #

Push a list to Lua stack as a Lua array.

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.

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.

setmetatable :: LuaState -> Int -> IO () #

See `lua_setmetatable` in Lua Reference Manual.

settable :: LuaState -> Int -> IO () #

See `lua_settable` 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 LuaNumber #

See `lua_tonumber` in Lua Reference Manual.

topointer :: LuaState -> Int -> IO (Ptr ()) #

See `lua_topointer` in Lua Reference Manual.

register :: LuaState -> String -> FunPtr LuaCFunction -> IO () #

See `lua_register` 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.

ref :: LuaState -> Int -> IO Int #

See `luaL_ref` in Lua Reference Manual.

unref :: LuaState -> Int -> Int -> IO () #

See `luaL_unref` in Lua Reference Manual.

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
- See "A note about integer functions" for integer functions.

Minimal complete definition

push, peek, valuetype

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.

Instances

StackValue Bool # |
Methods push :: LuaState -> Bool -> IO () # peek :: LuaState -> Int -> IO (Maybe Bool) # valuetype :: Bool -> LTYPE #
StackValue Int # |
Methods push :: LuaState -> Int -> IO () # peek :: LuaState -> Int -> IO (Maybe Int) # valuetype :: Int -> LTYPE #
StackValue () # |
Methods push :: LuaState -> () -> IO () # peek :: LuaState -> Int -> IO (Maybe ()) # valuetype :: () -> LTYPE #
StackValue ByteString # |
Methods push :: LuaState -> ByteString -> IO () # peek :: LuaState -> Int -> IO (Maybe ByteString) # valuetype :: ByteString -> LTYPE #
StackValue LuaNumber # |
Methods push :: LuaState -> LuaNumber -> IO () # peek :: LuaState -> Int -> IO (Maybe LuaNumber) # valuetype :: LuaNumber -> LTYPE #
StackValue LuaInteger # |
Methods push :: LuaState -> LuaInteger -> IO () # peek :: LuaState -> Int -> IO (Maybe LuaInteger) # valuetype :: LuaInteger -> LTYPE #
StackValue LuaState # |
Methods push :: LuaState -> LuaState -> IO () # peek :: LuaState -> Int -> IO (Maybe LuaState) # valuetype :: LuaState -> LTYPE #
StackValue a => StackValue [a] # |
Methods push :: LuaState -> [a] -> IO () # peek :: LuaState -> Int -> IO (Maybe [a]) # valuetype :: [a] -> LTYPE #
StackValue (Ptr a) # |
Methods push :: LuaState -> Ptr a -> IO () # peek :: LuaState -> Int -> IO (Maybe (Ptr a)) # valuetype :: Ptr a -> LTYPE #
StackValue (FunPtr LuaCFunction) # |
Methods push :: LuaState -> FunPtr LuaCFunction -> IO () # peek :: LuaState -> Int -> IO (Maybe (FunPtr LuaCFunction)) # valuetype :: FunPtr LuaCFunction -> LTYPE #

maybepeek :: l -> n -> (l -> n -> IO Bool) -> (l -> n -> IO r) -> IO (Maybe r) #

getglobal2 :: LuaState -> String -> IO () #

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

    getglobal l "math.sin"

returns correct result

typenameindex :: LuaState -> Int -> IO String #

class LuaImport a where #

Minimal complete definition

luaimport', luaimportargerror

Methods

luaimport' :: Int -> a -> LuaCFunction #

luaimportargerror :: Int -> String -> a -> LuaCFunction #

Instances

StackValue a => LuaImport (IO a) # |
Methods luaimport' :: Int -> IO a -> LuaCFunction # luaimportargerror :: Int -> String -> IO a -> LuaCFunction #
(StackValue a, LuaImport b) => LuaImport (a -> b) # |
Methods luaimport' :: Int -> (a -> b) -> LuaCFunction # luaimportargerror :: Int -> String -> (a -> b) -> LuaCFunction #

mkWrapper :: LuaCFunction -> IO (FunPtr LuaCFunction) #

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`.

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.

freecfunction :: FunPtr LuaCFunction -> IO () #

Free function pointer created with `newcfunction`.

class LuaCallProc a where #

Minimal complete definition

callproc'

Methods

callproc' :: LuaState -> String -> IO () -> Int -> a #

Instances

LuaCallProc (IO t) # |
Methods callproc' :: LuaState -> String -> IO () -> Int -> IO t #
(StackValue t, LuaCallProc b) => LuaCallProc (t -> b) # |
Methods callproc' :: LuaState -> String -> IO () -> Int -> t -> b #

callproc :: LuaCallProc a => LuaState -> String -> a #

Call a Lua procedure. Use as:

    callproc l "proc" "abc" (1::Int) (5.0::Double)

class LuaCallFunc a where #

Minimal complete definition

callfunc'

Methods

callfunc' :: LuaState -> String -> IO () -> Int -> a #

Instances

StackValue t => LuaCallFunc (IO t) # |
Methods callfunc' :: LuaState -> String -> IO () -> Int -> IO t #
(StackValue t, LuaCallFunc b) => LuaCallFunc (t -> b) # |
Methods callfunc' :: LuaState -> String -> IO () -> Int -> t -> b #

callfunc :: LuaCallFunc a => LuaState -> String -> a #

Call a Lua function. Use as:

    Just v <- callfunc l "proc" "abc" (1::Int) (5.0::Double)

hsmethod__gc_addr :: FunPtr LuaCFunction #

hsmethod__call_addr :: FunPtr LuaCFunction #

hsmethod__gc :: LuaState -> IO CInt #

hsmethod__call :: LuaState -> IO CInt #

pushhsfunction :: LuaImport a => LuaState -> a -> IO () #

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

    Lua.pushhsfunction 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.

pushrawhsfunction :: LuaState -> LuaCFunction -> IO () #

Pushes _raw_ Haskell function converted to a Lua function. Raw Haskell functions collect parameters from the stack and return a `CInt` that represents number of return values left in the stack.

registerhsfunction :: LuaImport a => LuaState -> String -> a -> IO () #

Imports a Haskell function and registers it at global name.

registerrawhsfunction :: LuaState -> String -> (LuaState -> IO CInt) -> IO () #

Imports a raw Haskell function and registers it at global name.

# Error handling in hslua

Error handling in hslua is tricky, because we can call Haskell from Lua which calls Lua again etc. (or the other way around, e.g. Lua loads Haskell program compiled as a dynamic library, see this blog post as an example)

At each language boundary we should check for errors and propagate them properly to the next level in stack.

Let's say we have this call stack: (stack grows upwards)

    Haskell function
    Lua function
    Haskell program

and we want to report an error in top-most Haskell function. We can't use `lua_error` from Lua C API, because it uses `longjmp`, which means it skips layers of abstractions, including Haskell RTS. There's no way to prevent this `longjmp`. `lua_pcall` sets the jump target, but even with `lua_pcall` it's not safe. Consider this call stack:

    Haskell function which calls `lua_error`
    Lua function, uses pcall
    Haskell program

This program jumps to Lua function, skipping Haskell RTS code that would run before Haskell function returns. For this reason we can use `lua_pcall`(`pcall`) only for catching errors from Lua, and even in that case we need to make sure there are no Haskell calls between error-throwing Lua call and our `pcall` call.

To be able to catch errors from Haskell functions in Lua, we need to find a convention. Currently hslua does this: `lerror` has same type as Lua's `lua_error`, but instead of calling real `lua_error`, it's returning two values: A special value `_HASKELLERR` and error message as a string.

Using this, we can write a function to catch errors from Haskell like this:

    function catch_haskell(ret, err_msg)
        if ret == _HASKELLERR then
          print("Error caught from Haskell land: " .. err_msg)
          return
        end
        return ret
    end

(`_HASKELLERR` is created by `newstate`)

(Type errors in Haskell functions are also handled using this convention. E.g. if you pass a Lua value with wrong type to a Haskell function, error will be reported in this way)

At this point our call stack is like this:

    Lua function (Haskell function returned with error, which we caught)
    Haskell program

If we further want to propagate the error message to Haskell program, we we can just use standard `error` function and use `pcall` in Haskell side. Note that if we use `error` in Lua side and forget to use `pcall` in calling Haskell function, we start skipping layers of abstractions and we get a segfault in the best case.

This use of `error` in Lua side and `pcall` in Haskell side is safe, as long as there are no Haskell-Lua interactions going on between those two calls. (e.g. we can only remove one layer from our stack, otherwise it's unsafe)

The reason it's safe is because `lua_pcall` C function is calling the Lua function using Lua C API, and when called Lua function calls `error` it `longjmp`s to `lua_pcall` C function, without skipping any layers of abstraction. `lua_pcall` then returns to Haskell.

As an example program that does error propagations between Haskell and Lua(in both ways), see this example from hslua repository.

NOTE: If you're loading a hslua program compiled to a dynamic library from a Lua program, you need to define `_HASKELLERR = {}` manually, after creating the Lua state.

# A note about integer functions

Lua didn't have integers until Lua 5.3, and the version supported by hslua is Lua 5.1. In Lua 5.1 and 5.2, integer functions like `pushinteger` convert integers to `LuaNumber`s before storing them in Lua stack/heap, and getter functions like `tointeger` convert them back to `LuaInteger`s.

This means that you can lose some information during the conversion. For example:

    main = do
      l <- newstate
      let val = maxBound :: LuaInteger
      pushinteger l val
      i3 <- tointeger l 1
      putStrLn $ show val ++ " - " ++ show i3

Prints `9223372036854775807 - -9223372036854775808`.