Scripting.Lua

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 = Int64

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.

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

Alias for C constant LUA_MULTRET. See lua_call.

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

See lua_settop.

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

See lua_createtable.

objlen :: LuaState -> Int -> IO Int

See lua_objlen.

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

See lua_pop.

newtable :: LuaState -> IO ()

See lua_newtable.

pushcclosure :: LuaState -> FunPtr LuaCFunction -> Int -> IO ()

See lua_pushcclosure.

pushcfunction :: LuaState -> FunPtr LuaCFunction -> IO ()

See lua_pushcfunction.

strlen :: LuaState -> Int -> IO Int

Deprecated: Use objlen instead.

Compatibility alias for objlen

ltype :: LuaState -> Int -> IO LTYPE

See lua_type.

isfunction :: LuaState -> Int -> IO Bool

See lua_isfunction.

istable :: LuaState -> Int -> IO Bool

See lua_istable.

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.

isnil :: LuaState -> Int -> IO Bool

See lua_isnil.

isboolean :: LuaState -> Int -> IO Bool

See lua_isboolean.

isthread :: LuaState -> Int -> IO Bool

See lua_isthread.

isnone :: LuaState -> Int -> IO Bool

See lua_isnone.

isnoneornil :: LuaState -> Int -> IO Bool

See lua_isnoneornil.

registryindex :: Int

Alias for C constant LUA_REGISTRYINDEX. See Lua registry.

environindex :: Int

Alias for C constant LUA_ENVIRONINDEX. See pseudo-indices.

globalsindex :: Int

Alias for C constant LUA_GLOBALSINDEX. See pseudo-indices.

upvalueindex :: Int -> Int

See lua_upvalueindex.

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

See lua_atpanic.

tostring :: LuaState -> Int -> IO ByteString

See lua_tostring.

tothread :: LuaState -> Int -> IO LuaState

See lua_tothread.

touserdata :: LuaState -> Int -> IO (Ptr a)

See lua_touserdata.

typename :: LuaState -> LTYPE -> IO String

See lua_typename.

xmove :: LuaState -> LuaState -> Int -> IO ()

See lua_xmove.

yield :: LuaState -> Int -> IO Int

See lua_yield.

checkstack :: LuaState -> Int -> IO Bool

See lua_checkstack.

newstate :: IO LuaState

See lua_newstate and luaL_newstate.

close :: LuaState -> IO ()

See lua_close.

concat :: LuaState -> Int -> IO ()

See lua_concat.

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

See lua_call and lua_call.

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

See lua_pcall.

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

See lua_cpcall.

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

See lua_getfield.

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

See lua_setfield.

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

See lua_getglobal.

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

See lua_setglobal.

openlibs :: LuaState -> IO ()

See luaL_openlibs.

openbase :: LuaState -> IO ()

See luaopen_base.

opentable :: LuaState -> IO ()

See luaopen_table.

openio :: LuaState -> IO ()

See luaopen_io.

openos :: LuaState -> IO ()

See luaopen_os.

openstring :: LuaState -> IO ()

See luaopen_string.

openmath :: LuaState -> IO ()

See luaopen_math.

opendebug :: LuaState -> IO ()

See luaopen_debug.

openpackage :: LuaState -> IO ()

See luaopen_package.

mkStringWriter :: LuaWriter -> IO (FunPtr LuaWriter)

dump :: LuaState -> IO String

See lua_dump.

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

See lua_equal.

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.

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

See lua_getfenv.

getmetatable :: LuaState -> Int -> IO Bool

See lua_getmetatable.

gettable :: LuaState -> Int -> IO ()

See lua_gettable.

gettop :: LuaState -> IO Int

See lua_gettop.

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

See lua_insert.

iscfunction :: LuaState -> Int -> IO Bool

See lua_iscfunction.

isnumber :: LuaState -> Int -> IO Bool

See lua_isnumber.

isstring :: LuaState -> Int -> IO Bool

See lua_isstring.

isuserdata :: LuaState -> Int -> IO Bool

See lua_isuserdata.

lessthan :: LuaState -> Int -> Int -> IO Bool

See lua_lessthan.

loadfile :: LuaState -> String -> IO Int

See luaL_loadfile.

loadstring :: LuaState -> String -> IO Int

See luaL_loadstring.

newthread :: LuaState -> IO LuaState

See lua_newthread.

newuserdata :: LuaState -> Int -> IO (Ptr ())

See lua_newuserdata.

next :: LuaState -> Int -> IO Bool

See lua_next.

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

See lua_pushboolean.

pushinteger :: LuaState -> LuaInteger -> IO ()

See lua_pushinteger.

pushlightuserdata :: LuaState -> Ptr a -> IO ()

See lua_pushlightuserdata.

pushnil :: LuaState -> IO ()

See lua_pushnil.

pushnumber :: LuaState -> LuaNumber -> IO ()

See lua_pushnumber.

pushstring :: LuaState -> ByteString -> IO ()

See lua_pushstring.

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

Push a list to Lua stack as a Lua array.

pushthread :: LuaState -> IO Bool

See lua_pushthread.

pushvalue :: LuaState -> Int -> IO ()

See lua_pushvalue.

rawequal :: LuaState -> Int -> Int -> IO Bool

See lua_rawequal.

rawget :: LuaState -> Int -> IO ()

See lua_rawget.

rawgeti :: LuaState -> Int -> Int -> IO ()

See lua_rawgeti.

rawset :: LuaState -> Int -> IO ()

See lua_rawset.

rawseti :: LuaState -> Int -> Int -> IO ()

See lua_rawseti.

remove :: LuaState -> Int -> IO ()

See lua_remove.

replace :: LuaState -> Int -> IO ()

See lua_replace.

resume :: LuaState -> Int -> IO Int

See lua_resume.

setfenv :: LuaState -> Int -> IO Int

See lua_setfenv.

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

See lua_setmetatable.

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

See lua_settable.

status :: LuaState -> IO Int

See lua_status.

toboolean :: LuaState -> Int -> IO Bool

See lua_toboolean.

tocfunction :: LuaState -> Int -> IO (FunPtr LuaCFunction)

See lua_tocfunction.

tointeger :: LuaState -> Int -> IO LuaInteger

See lua_tointeger.

tonumber :: LuaState -> Int -> IO LuaNumber

See lua_tonumber.

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

See lua_topointer.

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

See lua_register.

newmetatable :: LuaState -> String -> IO Int

See luaL_newmetatable.

argerror :: LuaState -> Int -> String -> IO CInt

See luaL_argerror. Contrary to the manual, Haskell function does return with value less than zero.

ref :: LuaState -> Int -> IO Int

See luaL_ref.

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

See luaL_unref.

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 longjmps 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 LuaNumbers before storing them in Lua stack/heap, and getter functions like tointeger convert them back to LuaIntegers.

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.