Portability	portable, ffi
Stability	alpha
Maintainer	gracjanpolak@gmail.com
Safe Haskell	Safe-Inferred

Scripting.Lua

Contents

Basic Lua types
Constants and enumerations
lua_* functions
luaL_* functions
Haskell extensions

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.

Minmal 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

Basic Lua types

newtype LuaState

Wrapper for lua_State *. See lua_State in Lua Reference Manual.

Constructors

LuaState (Ptr ())

Instances

StackValue LuaState
StackValue (FunPtr LuaCFunction)

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.

class LuaImport a where

Methods

luaimport' :: Int -> a -> LuaCFunction

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

Instances

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

Constants and enumerations

data GCCONTROL

Enumeration used by gc function.

Constructors

GCSTOP
GCRESTART
GCCOLLECT
GCCOUNT
GCCOUNTB
GCSTEP
GCSETPAUSE
GCSETSTEPMUL

Instances

Enum GCCONTROL
Eq GCCONTROL
Ord GCCONTROL
Show GCCONTROL

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
Eq LTYPE
Ord LTYPE
Show LTYPE

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.

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.

register :: 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.

Haskell extensions

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.

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)

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.

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.

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.

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

Imports a Haskell function and registers it at global name.

StackValue Bool
StackValue Double
StackValue Int
StackValue String
StackValue ()
StackValue LuaNumber
StackValue LuaInteger
StackValue LuaState
StackValue (Ptr a)
StackValue (FunPtr LuaCFunction)