hslua-1.0.0: Bindings to Lua, an embeddable scripting language

Copyright© 2007–2012 Gracjan Polak
2012–2016 Ömer Sinan Ağacan
2017-2018 Albert Krewinkel
LicenseMIT
MaintainerAlbert Krewinkel <tarleb+hslua@zeitkraut.de>
Stabilitybeta
Portabilitynon-portable (depends on GHC)
Safe HaskellNone
LanguageHaskell2010

Foreign.Lua

Contents

Description

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@'.

Synopsis

Core

Receiving values from Lua stack (Lua → Haskell)

class Peekable a where Source #

A value that can be read from the Lua stack.

Minimal complete definition

peek

Methods

peek :: StackIndex -> Lua a Source #

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

Instances
Peekable Bool Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable Double Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable Float Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable Int Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua Int Source #

Peekable Integer Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable () Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua () Source #

Peekable ByteString Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable ByteString Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable Text Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable Number Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable Integer Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable CFunction Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable State Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Peekable [Char] Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua [Char] Source #

Peekable a => Peekable [a] Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua [a] Source #

Peekable (Ptr a) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (Ptr a) Source #

(Ord a, Peekable a) => Peekable (Set a) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

peek :: StackIndex -> Lua (Set a) Source #

Peekable a => Peekable (Optional a) Source # 
Instance details

Defined in Foreign.Lua.Util

Methods

peek :: StackIndex -> Lua (Optional a) Source #

(Peekable a, Peekable b) => Peekable (a, b) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

(Ord a, Peekable a, Peekable b) => Peekable (Map a b) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

(Peekable a, Peekable b, Peekable c) => Peekable (a, b, c) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

(Peekable a, Peekable b, Peekable c, Peekable d) => Peekable (a, b, c, d) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

(Peekable a, Peekable b, Peekable c, Peekable d, Peekable e) => Peekable (a, b, c, d, e) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

(Peekable a, Peekable b, Peekable c, Peekable d, Peekable e, Peekable f) => Peekable (a, b, c, d, e, f) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

(Peekable a, Peekable b, Peekable c, Peekable d, Peekable e, Peekable f, Peekable g) => Peekable (a, b, c, d, e, f, g) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

(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) Source # 
Instance details

Defined in Foreign.Lua.Types.Peekable

Methods

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

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

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

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

Read a table into a list

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

Read a table into a list of pairs.

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

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 Source #

Retrieve Haskell data which was pushed to Lua as userdata.

Pushing values to Lua stack (Haskell → Lua)

class Pushable a where Source #

A value that can be pushed to the Lua stack.

Minimal complete definition

push

Methods

push :: a -> Lua () Source #

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

Instances
Pushable Bool Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Bool -> Lua () Source #

Pushable Double Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Double -> Lua () Source #

Pushable Float Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Float -> Lua () Source #

Pushable Int Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Int -> Lua () Source #

Pushable Integer Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Integer -> Lua () Source #

Pushable () Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: () -> Lua () Source #

Pushable ByteString Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: ByteString -> Lua () Source #

Pushable ByteString Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: ByteString -> Lua () Source #

Pushable Text Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Text -> Lua () Source #

Pushable Number Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Number -> Lua () Source #

Pushable Integer Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Integer -> Lua () Source #

Pushable CFunction Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: CFunction -> Lua () Source #

Pushable [Char] Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: [Char] -> Lua () Source #

Pushable a => Pushable [a] Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: [a] -> Lua () Source #

Pushable (Ptr a) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Ptr a -> Lua () Source #

Pushable a => Pushable (Set a) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Set a -> Lua () Source #

Pushable a => Pushable (Optional a) Source # 
Instance details

Defined in Foreign.Lua.Util

Methods

push :: Optional a -> Lua () Source #

(Pushable a, Pushable b) => Pushable (a, b) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

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

(Pushable a, Pushable b) => Pushable (Map a b) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

push :: Map a b -> Lua () Source #

(Pushable a, Pushable b, Pushable c) => Pushable (a, b, c) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

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

(Pushable a, Pushable b, Pushable c, Pushable d) => Pushable (a, b, c, d) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

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

(Pushable a, Pushable b, Pushable c, Pushable d, Pushable e) => Pushable (a, b, c, d, e) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

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

(Pushable a, Pushable b, Pushable c, Pushable d, Pushable e, Pushable f) => Pushable (a, b, c, d, e, f) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

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

(Pushable a, Pushable b, Pushable c, Pushable d, Pushable e, Pushable f, Pushable g) => Pushable (a, b, c, d, e, f, g) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

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

(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) Source # 
Instance details

Defined in Foreign.Lua.Types.Pushable

Methods

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

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

Push list as numerically indexed table.

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

Push data by wrapping it into a userdata object.

Calling Functions

type PreCFunction = State -> IO NumResults Source #

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

type HaskellFunction = Lua NumResults Source #

Haskell function that can be called from Lua.

class ToHaskellFunction a where Source #

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.

Minimal complete definition

toHsFun

Methods

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

Helper function, called by toHaskellFunction

toHaskellFunction :: ToHaskellFunction a => a -> HaskellFunction Source #

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 Haskell exception will be converted to a string and returned as Lua error.

callFunc :: LuaCallFunc a => String -> a Source #

Call a Lua function. Use as:

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

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

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

freeCFunction :: CFunction -> Lua () Source #

Free function pointer created with newcfunction.

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

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

Imports a Haskell function and registers it at global name.

Utility functions and types

run :: Lua a -> IO a Source #

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.

runEither :: Lua a -> IO (Either Exception a) Source #

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.

getglobal' :: String -> Lua () Source #

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

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 Source #

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

newtype Optional a Source #

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

Instances
Pushable a => Pushable (Optional a) Source # 
Instance details

Defined in Foreign.Lua.Util

Methods

push :: Optional a -> Lua () Source #

Peekable a => Peekable (Optional a) Source # 
Instance details

Defined in Foreign.Lua.Util

Methods

peek :: StackIndex -> Lua (Optional a) Source #

retrieving values

popValue :: Peekable a => Lua a Source #

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