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

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

See lua_gc in Lua Reference Manual.

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

See lua_getfenv in Lua Reference Manual.

getmetatable :: LuaState -> Int -> IO Bool Source

See lua_getmetatable in Lua Reference Manual.

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

See lua_gettable in Lua Reference Manual.

gettop :: LuaState -> IO Int Source

See lua_gettop in Lua Reference Manual.

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

See lua_insert in Lua Reference Manual.

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

See lua_iscfunction in Lua Reference Manual.

isnumber :: LuaState -> Int -> IO Bool Source

See lua_isnumber in Lua Reference Manual.

isstring :: LuaState -> Int -> IO Bool Source

See lua_isstring in Lua Reference Manual.

isuserdata :: LuaState -> Int -> IO Bool Source

See lua_isuserdata in Lua Reference Manual.

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

See lua_lessthan in Lua Reference Manual.

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

See luaL_loadfile in Lua Reference Manual.

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

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

See luaL_loadstring in Lua Reference Manual.

newthread :: LuaState -> IO LuaState Source

See lua_newthread in Lua Reference Manual.

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

See lua_newuserdata in Lua Reference Manual.

next :: LuaState -> Int -> IO Bool Source

See lua_next in Lua Reference Manual.

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

See lua_pushboolean in Lua Reference Manual.

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

See lua_pushinteger in Lua Reference Manual.

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

See lua_pushlightuserdata in Lua Reference Manual.

pushnil :: LuaState -> IO () Source

See lua_pushnil in Lua Reference Manual.

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

See lua_pushnumber in Lua Reference Manual.

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

See lua_pushstring in Lua Reference Manual.

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

Push a list to Lua stack as a Lua array.

pushthread :: LuaState -> IO Bool Source

See lua_pushthread in Lua Reference Manual.

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

See lua_pushvalue in Lua Reference Manual.

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

See lua_rawequal in Lua Reference Manual.

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

See lua_rawget in Lua Reference Manual.

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

See lua_rawgeti in Lua Reference Manual.

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

See lua_rawset in Lua Reference Manual.

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

See lua_rawseti in Lua Reference Manual.

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

See lua_remove in Lua Reference Manual.

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

See lua_replace in Lua Reference Manual.

resume :: LuaState -> Int -> IO Int Source

See lua_resume in Lua Reference Manual.

setfenv :: LuaState -> Int -> IO Int Source

See lua_setfenv in Lua Reference Manual.

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

See lua_setmetatable in Lua Reference Manual.

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

See lua_settable in Lua Reference Manual.

status :: LuaState -> IO Int Source

See lua_status in Lua Reference Manual.

toboolean :: LuaState -> Int -> IO Bool Source

See lua_toboolean in Lua Reference Manual.

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

See lua_tocfunction in Lua Reference Manual.

tointeger :: LuaState -> Int -> IO LuaInteger Source

See lua_tointeger in Lua Reference Manual.

tonumber :: LuaState -> Int -> IO LuaNumber Source

See lua_tonumber in Lua Reference Manual.

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

See lua_topointer in Lua Reference Manual.

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

See lua_register in Lua Reference Manual.

newmetatable :: LuaState -> String -> IO Int Source

See luaL_newmetatable in Lua Reference Manual.

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

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 Source

See luaL_ref in Lua Reference Manual.

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

See luaL_unref in Lua Reference Manual.

class StackValue a where Source

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.

Methods

push :: LuaState -> a -> IO () Source

Pushes a value onto Lua stack, casting it into meaningfully nearest Lua type.

peek :: LuaState -> Int -> IO (Maybe a) Source

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 Source

Lua type id code of the vaule expected. Parameter is unused.

Instances

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

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

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

getglobal l "math.sin"

returns correct result

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

class LuaImport a where Source

Methods

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

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

Instances

StackValue a => LuaImport (IO a)
(StackValue a, LuaImport b) => LuaImport (a -> b)

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

newcfunction :: LuaImport a => a -> IO (FunPtr LuaCFunction) Source

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 Source

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 () Source

Free function pointer created with newcfunction.

class LuaCallProc a where Source

Methods

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

Instances

LuaCallProc (IO t)
(StackValue t, LuaCallProc b) => LuaCallProc (t -> b)

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

Call a Lua procedure. Use as:

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

class LuaCallFunc a where Source

Methods

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

Instances

StackValue t => LuaCallFunc (IO t)
(StackValue t, LuaCallFunc b) => LuaCallFunc (t -> b)

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

Call a Lua function. Use as:

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

hsmethod__gc_addr :: FunPtr LuaCFunction Source

hsmethod__call_addr :: FunPtr LuaCFunction Source

hsmethod__gc :: LuaState -> IO CInt Source

hsmethod__call :: LuaState -> IO CInt Source

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

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 () Source

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 () Source

Imports a Haskell function and registers it at global name.

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

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](http:/osa1.netposts/2015-01-16-haskell-so-lua.html) 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](https:/github.comosa1hsluatreemasterexamples/err_prop) 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.

StackValue Bool
StackValue Int
StackValue ()
StackValue ByteString
StackValue LuaNumber
StackValue LuaInteger
StackValue LuaState
StackValue a => StackValue [a]
StackValue (Ptr a)
StackValue (FunPtr LuaCFunction)