hslua-0.3: A Lua language interpreter embedding in Haskell

Portabilityportable, ffi
Stabilityalpha
Maintainergracjanpolak@gmail.com

Scripting.Lua

Contents

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 Source

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

Constructors

LuaState (Ptr ()) 

Instances

type LuaCFunction = LuaState -> IO CIntSource

Wrapper for lua_CFunction. See lua_CFunction in Lua Reference Manual.

type LuaInteger = CPtrdiffSource

Wrapper for lua_Integer. See lua_Integer in Lua Reference Manual. HsLua uses C ptrdiff_t as lua_Integer.

type LuaNumber = CDoubleSource

Wrapper for lua_Number. See lua_Number in Lua Reference Manual. HsLua uses C double as lua_Integer.

Constants and enumerations

data GCCONTROL Source

Enumeration used by gc function.

data LTYPE Source

Enumeration used as type tag. See lua_type in Lua Reference Manual.

multret :: IntSource

See LUA_MULTRET in Lua Reference Manual.

registryindex :: IntSource

See LUA_REGISTRYINDEX in Lua Reference Manual.

environindex :: IntSource

See LUA_ENVIRONINDEX in Lua Reference Manual.

globalsindex :: IntSource

See LUA_GLOBALSINDEX in Lua Reference Manual.

lua_* functions

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

See lua_atpanic in Lua Reference Manual.

call :: LuaState -> Int -> Int -> IO IntSource

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 BoolSource

See lua_checkstack in Lua Reference Manual.

close :: LuaState -> IO ()Source

See lua_close in Lua Reference Manual.

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

See lua_concat in Lua Reference Manual.

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

See lua_cpcall in Lua Reference Manual.

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

See lua_createtable in Lua Reference Manual.

equal :: LuaState -> Int -> Int -> IO BoolSource

See lua_equal in Lua Reference Manual.

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

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

See lua_getfenv in Lua Reference Manual.

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

See lua_getfield in Lua Reference Manual.

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

See lua_getglobal in Lua Reference Manual.

getmetatable :: LuaState -> Int -> IO BoolSource

See lua_getmetatable in Lua Reference Manual.

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

See lua_gettable in Lua Reference Manual.

gettop :: LuaState -> IO IntSource

See lua_gettop in Lua Reference Manual.

getupvalue :: LuaState -> Int -> Int -> IO StringSource

See lua_getupvalue in Lua Reference Manual.

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

See lua_insert in Lua Reference Manual.

isboolean :: LuaState -> Int -> IO BoolSource

See lua_isboolean in Lua Reference Manual.

iscfunction :: LuaState -> Int -> IO BoolSource

See lua_iscfunction in Lua Reference Manual.

isfunction :: LuaState -> Int -> IO BoolSource

See lua_isfunction in Lua Reference Manual.

islightuserdata :: LuaState -> Int -> IO BoolSource

See lua_islightuserdata in Lua Reference Manual.

isnil :: LuaState -> Int -> IO BoolSource

See lua_isnil in Lua Reference Manual.

isnumber :: LuaState -> Int -> IO BoolSource

See lua_isnumber in Lua Reference Manual.

isstring :: LuaState -> Int -> IO BoolSource

See lua_isstring in Lua Reference Manual.

istable :: LuaState -> Int -> IO BoolSource

See lua_istable in Lua Reference Manual.

isthread :: LuaState -> Int -> IO BoolSource

See lua_isthread in Lua Reference Manual.

isuserdata :: LuaState -> Int -> IO BoolSource

See lua_isuserdata in Lua Reference Manual.

lessthan :: LuaState -> Int -> Int -> IO BoolSource

See lua_lessthan in Lua Reference Manual.

newstate :: IO LuaStateSource

See lua_newstate and luaL_newstate in Lua Reference Manual.

newtable :: LuaState -> IO ()Source

See lua_newtable in Lua Reference Manual.

newthread :: LuaState -> IO LuaStateSource

See lua_newthread in Lua Reference Manual.

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

See lua_newuserdata in Lua Reference Manual.

next :: LuaState -> Int -> IO BoolSource

See lua_next in Lua Reference Manual.

objlen :: LuaState -> Int -> IO IntSource

See lua_objlen in Lua Reference Manual.

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

See lua_pcall in Lua Reference Manual.

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

See lua_pop in Lua Reference Manual.

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

See lua_pushboolean in Lua Reference Manual.

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

See lua_pushcclosure in Lua Reference Manual.

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

See lua_pushcfunction 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 -> String -> IO ()Source

See lua_pushstring in Lua Reference Manual.

pushthread :: LuaState -> IO BoolSource

See lua_pushthread in Lua Reference Manual.

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

See lua_pushvalue in Lua Reference Manual.

rawequal :: LuaState -> Int -> Int -> IO BoolSource

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.

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

See lua_register 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 IntSource

See lua_resume in Lua Reference Manual.

setfenv :: LuaState -> Int -> IO IntSource

See lua_setfenv in Lua Reference Manual.

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

See lua_setfield in Lua Reference Manual.

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

See lua_setglobal 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.

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

See lua_settop in Lua Reference Manual.

setupvalue :: LuaState -> Int -> Int -> IO StringSource

See lua_setupvalue in Lua Reference Manual.

status :: LuaState -> IO IntSource

See lua_status in Lua Reference Manual.

toboolean :: LuaState -> Int -> IO BoolSource

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 LuaIntegerSource

See lua_tointeger in Lua Reference Manual.

tonumber :: LuaState -> Int -> IO CDoubleSource

See lua_tonumber in Lua Reference Manual.

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

See lua_topointer in Lua Reference Manual.

tostring :: LuaState -> Int -> IO StringSource

See lua_tostring in Lua Reference Manual.

tothread :: LuaState -> Int -> IO LuaStateSource

See lua_tothread in Lua Reference Manual.

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

See lua_touserdata in Lua Reference Manual.

ltype :: LuaState -> Int -> IO LTYPESource

See lua_type in Lua Reference Manual.

typename :: LuaState -> LTYPE -> IO StringSource

See lua_typename in Lua Reference Manual.

upvalueindex :: Int -> IntSource

See lua_upvalueindex in Lua Reference Manual.

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

See lua_xmove in Lua Reference Manual.

yield :: LuaState -> Int -> IO IntSource

See lua_yield in Lua Reference Manual.

luaL_* functions

openlibs :: LuaState -> IO ()Source

See luaL_openlibs in Lua Reference Manual.

loadfile :: LuaState -> String -> IO IntSource

See luaL_loadfile in Lua Reference Manual.

loadstring :: LuaState -> String -> String -> IO IntSource

See luaL_loadstring in Lua Reference Manual.

newmetatable :: LuaState -> String -> IO IntSource

See luaL_newmetatable in Lua Reference Manual.

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

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 whereSource

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

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

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

Call a Lua procedure. Use as:

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

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

Call a Lua function. Use as:

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

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

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

 getglobal l "math.sin"

returns correct result

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.

freecfunction :: FunPtr LuaCFunction -> IO ()Source

Free function pointer created with newcfunction.

luaimport :: LuaImport a => a -> LuaCFunctionSource

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

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

Imports a Haskell function and registers it at global name.