Foreign.Lua

Bindings, functions, and utilities enabling the integration of a Lua interpreter into a haskell project.

Basic access to the Lua API is provided by '@Foreign.Lua.Core@'.

Core

module Foreign.Lua.Core

Receiving values from Lua stack (Lua → Haskell)

class Peekable a where

A value that can be read from the Lua stack.

Methods

peek :: StackIndex -> Lua a

Check if at index n there is a convertible Lua value and if so return it. Throws a Exception otherwise.

Instances

Peekable Bool

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Bool

Peekable Double

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Double

Peekable Float

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Float

Peekable Int

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Int

Peekable Integer

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Integer

Peekable ()

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua ()

Peekable ByteString

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua ByteString

Peekable ByteString

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua ByteString

Peekable Text

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Text

Peekable Number

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Number

Peekable Integer

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Integer

Peekable CFunction

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua CFunction

Peekable State

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua State

Peekable [Char]

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua [Char]

Peekable a => Peekable [a]

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua [a]

Peekable (Ptr a)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (Ptr a)

(Ord a, Peekable a) => Peekable (Set a)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (Set a)

Peekable a => Peekable (Optional a)

Defined in Foreign.Lua.Util

Methods

peek :: StackIndex -> Lua (Optional a)

(Peekable a, Peekable b) => Peekable (a, b)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (a, b)

(Ord a, Peekable a, Peekable b) => Peekable (Map a b)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (Map a b)

(Peekable a, Peekable b, Peekable c) => Peekable (a, b, c)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (a, b, c)

(Peekable a, Peekable b, Peekable c, Peekable d) => Peekable (a, b, c, d)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (a, b, c, d)

(Peekable a, Peekable b, Peekable c, Peekable d, Peekable e) => Peekable (a, b, c, d, e)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (a, b, c, d, e)

(Peekable a, Peekable b, Peekable c, Peekable d, Peekable e, Peekable f) => Peekable (a, b, c, d, e, f)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (a, b, c, d, e, f)

(Peekable a, Peekable b, Peekable c, Peekable d, Peekable e, Peekable f, Peekable g) => Peekable (a, b, c, d, e, f, g)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (a, b, c, d, e, f, g)

(Peekable a, Peekable b, Peekable c, Peekable d, Peekable e, Peekable f, Peekable g, Peekable h) => Peekable (a, b, c, d, e, f, g, h)

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (a, b, c, d, e, f, g, h)

peekEither :: Peekable a => StackIndex -> Lua (Either String a)

Try to convert the value at the given stack index to a Haskell value. Returns Left with an error message on failure.

WARNING: this is not save to use with custom error handling!

peekList :: Peekable a => StackIndex -> Lua [a]

Read a table into a list

peekKeyValuePairs :: (Peekable a, Peekable b) => StackIndex -> Lua [(a, b)]

Read a table into a list of pairs.

peekRead :: Read a => StackIndex -> Lua a

Get a value by retrieving a String from Lua, then using readMaybe to convert the String into a Haskell value.

peekAny :: Data a => StackIndex -> Lua a

Retrieve Haskell data which was pushed to Lua as userdata.

Pushing values to Lua stack (Haskell → Lua)

class Pushable a where

A value that can be pushed to the Lua stack.

Methods

push :: a -> Lua ()

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

Instances

Pushable Bool

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Bool -> Lua ()

Pushable Double

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Double -> Lua ()

Pushable Float

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Float -> Lua ()

Pushable Int

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Int -> Lua ()

Pushable Integer

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Integer -> Lua ()

Pushable ()

Defined in Foreign.Lua.Types.Pushable

Methods

push :: () -> Lua ()

Pushable ByteString

Defined in Foreign.Lua.Types.Pushable

Methods

push :: ByteString -> Lua ()

Pushable ByteString

Defined in Foreign.Lua.Types.Pushable

Methods

push :: ByteString -> Lua ()

Pushable Text

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Text -> Lua ()

Pushable Number

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Number -> Lua ()

Pushable Integer

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Integer -> Lua ()

Pushable CFunction

Defined in Foreign.Lua.Types.Pushable

Methods

push :: CFunction -> Lua ()

Pushable [Char]

Defined in Foreign.Lua.Types.Pushable

Methods

push :: [Char] -> Lua ()

Pushable a => Pushable [a]

Defined in Foreign.Lua.Types.Pushable

Methods

push :: [a] -> Lua ()

Pushable (Ptr a)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Ptr a -> Lua ()

Pushable a => Pushable (Set a)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Set a -> Lua ()

Pushable a => Pushable (Optional a)

Defined in Foreign.Lua.Util

Methods

push :: Optional a -> Lua ()

(Pushable a, Pushable b) => Pushable (a, b)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: (a, b) -> Lua ()

(Pushable a, Pushable b) => Pushable (Map a b)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Map a b -> Lua ()

(Pushable a, Pushable b, Pushable c) => Pushable (a, b, c)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: (a, b, c) -> Lua ()

(Pushable a, Pushable b, Pushable c, Pushable d) => Pushable (a, b, c, d)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: (a, b, c, d) -> Lua ()

(Pushable a, Pushable b, Pushable c, Pushable d, Pushable e) => Pushable (a, b, c, d, e)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: (a, b, c, d, e) -> Lua ()

(Pushable a, Pushable b, Pushable c, Pushable d, Pushable e, Pushable f) => Pushable (a, b, c, d, e, f)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: (a, b, c, d, e, f) -> Lua ()

(Pushable a, Pushable b, Pushable c, Pushable d, Pushable e, Pushable f, Pushable g) => Pushable (a, b, c, d, e, f, g)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: (a, b, c, d, e, f, g) -> Lua ()

(Pushable a, Pushable b, Pushable c, Pushable d, Pushable e, Pushable f, Pushable g, Pushable h) => Pushable (a, b, c, d, e, f, g, h)

Defined in Foreign.Lua.Types.Pushable

Methods

push :: (a, b, c, d, e, f, g, h) -> Lua ()

pushList :: Pushable a => [a] -> Lua ()

Push list as numerically indexed table.

pushAny :: Data a => a -> Lua ()

Push data by wrapping it into a userdata object.

Calling Functions

type PreCFunction = State -> IO NumResults

Type of raw Haskell functions that can be made into CFunctions.

type HaskellFunction = Lua NumResults

Haskell function that can be called from Lua.

class ToHaskellFunction a where

Operations and functions that can be pushed to the Lua stack. This is a helper function not intended to be used directly. Use the toHaskellFunction wrapper instead.

Methods

toHsFun :: StackIndex -> a -> Lua NumResults

Helper function, called by toHaskellFunction

Instances

ToHaskellFunction HaskellFunction

Defined in Foreign.Lua.FunctionCalling

Methods

toHsFun :: StackIndex -> HaskellFunction -> Lua NumResults

Pushable a => ToHaskellFunction (Lua a)

Defined in Foreign.Lua.FunctionCalling

Methods

toHsFun :: StackIndex -> Lua a -> Lua NumResults

(Peekable a, ToHaskellFunction b) => ToHaskellFunction (a -> b)

Defined in Foreign.Lua.FunctionCalling

Methods

toHsFun :: StackIndex -> (a -> b) -> Lua NumResults

toHaskellFunction :: ToHaskellFunction a => a -> HaskellFunction

Convert a Haskell function to Lua function. Any Haskell function can be converted provided that:

• all arguments are instances of Peekable
• return type is Lua a, where a is an instance of Pushable

Any Exception will be converted to a string and returned as Lua error.

Important: this does not catch exceptions other than Exception; exception handling must be done by the converted Haskell function. Failure to do so will cause the program to crash.

E.g., the following code could be used to handle an Exception of type FooException, if that type is an instance of MonadCatch and Pushable:

toHaskellFunction (myFun `catchM` (\e -> raiseError (e :: FooException)))

callFunc :: LuaCallFunc a => String -> a

Call a Lua function. Use as:

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

newCFunction :: ToHaskellFunction a => a -> Lua CFunction

Create new foreign Lua function. Function created can be called by the Lua engine. Remeber to free the pointer with freecfunction.

freeCFunction :: CFunction -> Lua ()

Free function pointer created with newcfunction.

pushHaskellFunction :: ToHaskellFunction a => a -> Lua ()

Pushes Haskell function as a callable userdata. All values created will be garbage collected. Use as:

pushHaskellFunction myfun
setglobal "myfun"

Error conditions should be indicated by raising a Lua Exception or by returning the result of error.

registerHaskellFunction :: ToHaskellFunction a => String -> a -> Lua ()

Imports a Haskell function and registers it at global name.

Utility functions and types

run :: Lua a -> IO a

Run Lua computation using the default HsLua state as starting point. Exceptions are masked, thus avoiding some issues when using multiple threads. All exceptions are passed through; error handling is the responsibility of the caller.

run' :: ErrorConversion -> Lua a -> IO a

Run Lua computation using the default HsLua state as starting point. Conversion from Lua errors to Haskell exceptions can be controlled through ErrorConversion.

runEither :: Exception e => Lua a -> IO (Either e a)

Run the given Lua computation; exceptions raised in haskell code are caught, but other exceptions (user exceptions raised in haskell, unchecked type errors, etc.) are passed through.

runWith :: State -> Lua a -> IO a

Run Lua computation with the given Lua state and the default error-to-exception converter (throwTopStringAsException). Exception handling is left to the caller.

getglobal' :: String -> Lua ()

Like getglobal, but knows about packages and nested tables. E.g.

getglobal' "math.sin"

will return the function sin in package math.

setglobal' :: String -> Lua ()

Like setglobal, but knows about packages and nested tables. E.g.

pushstring "0.9.4"
setglobal' "mypackage.version"

All tables and fields, except for the last field, must exist.

raiseError :: Pushable a => a -> Lua NumResults

Raise a Lua error, using the given value as the error object.

newtype Optional a

Newtype wrapper intended to be used for optional Lua values. Nesting this type is strongly discouraged as missing values on inner levels are indistinguishable from missing values on an outer level; wrong values would be the likely result.

Constructors

Optional

Fields

• fromOptional :: Maybe a

Instances

Pushable a => Pushable (Optional a)

Defined in Foreign.Lua.Util

Methods

push :: Optional a -> Lua ()

Peekable a => Peekable (Optional a)

Defined in Foreign.Lua.Util

Methods

peek :: StackIndex -> Lua (Optional a)

Retrieving values

popValue :: Peekable a => Lua a

Get, then pop the value at the top of the stack. The pop operation is executed even if the retrieval operation failed.

Modules

requirehs :: String -> Lua () -> Lua ()

Load a module, defined by a Haskell action, under the given name.

Similar to luaL_required: After checking "loaded" table, calls pushMod to push a module to the stack, and registers the result in package.loaded table.

The pushMod function must push exactly one element to the top of the stack. This is not checked, but failure to do so will lead to problems. Lua's package module must have been loaded by the time this function is invoked.

Leaves a copy of the module on the stack.

preloadhs :: String -> Lua NumResults -> Lua ()

Registers a preloading function. Takes an module name and the Lua operation which produces the package.

create :: Lua ()

Create a new module (i.e., a Lua table).

addfield :: Pushable a => String -> a -> Lua ()

Add a string-indexed field to the table at the top of the stack.

addfunction :: ToHaskellFunction a => String -> a -> Lua ()

Attach a function to the table at the top of the stack, using the given name.