HsLua.Marshalling · hslua-marshalling-2.3.1

Receiving values from Lua stack (Lua → Haskell)

7 declarations

typetype Peeker e a = StackIndex -> Peek e a

#

Function to retrieve a value from Lua's stack.

valuerunPeeker :: Peeker e a -> StackIndex -> LuaE e (Result a)

#

Runs the peeker function.

datadata Result a

#

Record to keep track of failure contexts while retrieving objects from the Lua stack.

Constructors

Success !a
Failure ByteString [Name]
Error message and stack of contexts

Instances10Monad, Functor, MonadFail, Applicative, Foldable, Traversable, …

Monad ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Functor ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
MonadFail ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Applicative ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Foldable ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Traversable ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Alternative ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
MonadPlus ResultDefined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Eq a => Eq (Result a)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Show a => Show (Result a)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek

valueforce :: LuaError e => Result a -> LuaE e a

#

Force creation of an unwrapped result, throwing an exception if that's not possible.

valueretrieving :: Name -> Peek e a -> Peek e a

#

Add context information to the peek traceback stack.

valuefailure :: ByteString -> Result a

#

Create a peek failure record from an error message.

valueresultToEither :: Result a -> Either String a

#

Converts a Result into an Either, where Left holds the reportable string in case of an failure.

Primitive types

valuepeekNil :: Peeker e ()

#

Succeeds if the value at the given index is nil.

valuepeekNoneOrNil :: Peeker e ()

#

Succeeds if the given index is not valid or if the value at this index is nil.

valuepeekBool :: Peeker e Bool

#

Retrieves a Bool as a Lua boolean.

valuepeekIntegral :: (Integral a, Read a) => Peeker e a

#

Retrieves an Integral value from the Lua stack.

valuepeekRealFloat :: (RealFloat a, Read a) => Peeker e a

#

Retrieve a RealFloat (e.g., Float or Double) from the stack.

Strings

valuepeekByteString :: Peeker e ByteString

#

Retrieves a ByteString as a raw string.

valuepeekLazyByteString :: Peeker e ByteString

#

Retrieves a lazy ByteString as a raw string.

valuepeekString :: Peeker e String

#

Retrieves a String from an UTF-8 encoded Lua string.

valuepeekText :: Peeker e Text

#

Retrieves a Text value as an UTF-8 encoded string.

valuepeekStringy :: IsString a => Peeker e a

#

Retrieves a String-like value from an UTF-8 encoded Lua string.

This should not be used to peek ByteString values or other values for which construction via fromString can result in loss of information.

valuepeekName :: Peeker e Name

#

Retrieves a Lua string as Name.

Readable types

valuepeekRead :: Read a => Peeker e a

#

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

Collections

valuepeekKeyValuePairs

:: LuaError e
=> Peeker e a
-> Peeker e b
-> Peeker e [(a, b)]

#

Read a table into a list of pairs.

valuepeekList :: LuaError e => Peeker e a -> Peeker e [a]

#

Reads a numerically indexed table t into a list, where the length of the list is equal to rawlen(t). The operation will fail unless all numerical fields between 1 and rawlen(t) can be retrieved.

valuepeekMap

:: (LuaError e, Ord a)
=> Peeker e a
-> Peeker e b
-> Peeker e (Map a b)

#

Retrieves a key-value Lua table as Map.

valuepeekSet :: (LuaError e, Ord a) => Peeker e a -> Peeker e (Set a)

#

Retrieves a Set from an idiomatic Lua representation. A set in Lua is idiomatically represented as a table with the elements as keys. Elements with falsy values are omitted.

Combinators

valuechoice :: LuaError e => [Peeker e a] -> Peeker e a

#

Try all peekers and return the result of the first to succeed.

valuepeekFieldRaw :: LuaError e => Peeker e a -> Name -> Peeker e a

#

Get value at key from a table.

valuepeekPair :: LuaError e => Peeker e a -> Peeker e b -> Peeker e (a, b)

#

Retrieves a value pair from a table. Expects the values to be stored in a numerically indexed table; does not access metamethods.

valuepeekTriple

:: LuaError e
=> Peeker e a
-> Peeker e b
-> Peeker e c
-> Peeker e (a, b, c)

#

Retrieves a value triple from a table. Expects the values to be stored in a numerically indexed table, with no metamethods.

valuepeekNilOr

:: Alternative m
=> Peeker e a
p
-> Peeker e (m a)

#

Returns empty if the value at the given index is nil; otherwise returns the result of peeker p.

valuepeekNoneOr

:: Alternative m
=> Peeker e a
p
-> Peeker e (m a)

#

Returns empty if the value at the given index is none; otherwise returns the result of peeker p.

valuepeekNoneOrNilOr

:: Alternative m
=> Peeker e a
p
-> Peeker e (m a)

#

Returns empty if the value at the given index is none or nil; otherwise returns the result of peeker p.

Lua peek monad

newtypenewtype Peek e a

#

Lua operation with an additional failure mode that can stack errors from different contexts; errors are not based on exceptions).

Constructors

Peek
- runPeek :: LuaE e (Result a)

Instances6Monad, Functor, MonadFail, Applicative, Alternative, MonadPlus

Monad (Peek e)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Functor (Peek e)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
MonadFail (Peek e)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Applicative (Peek e)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
Alternative (Peek e)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek
MonadPlus (Peek e)Defined in hslua-marshalling-2.3.1 · HsLua.Marshalling.Peek

valueforcePeek :: LuaError e => Peek e a -> LuaE e a

#

Converts a Peek action into a LuaE action, throwing an exception in case of a peek failure.

valueliftLua :: LuaE e a -> Peek e a

#

Lifts a Lua operation into the Peek monad.

valuewithContext :: Name -> Peek e a -> Peek e a

#

Transform the result using the given function.

valuefailPeek :: ByteString -> Peek e a

#

Fails the peek operation.

valuelastly :: Peek e a -> LuaE e b -> Peek e a

#

Runs the peek action and Lua action in sequence, even if the peek action fails.

valuecleanup :: Peek e a -> Peek e a

#

Runs the peek action, resetting the stack top afterwards. This can be used with peek actions that might otherwise leave elements on the stack in case of a failure.

Building Peek functions

valuetypeChecked

:: Name
expected type
-> (StackIndex -> LuaE e Bool)
pre-condition checker
-> Peeker e a
-> Peeker e a

#

Use test to check whether the value at stack index n has the correct type and use peekfn to convert it to a Haskell value if possible. A successfully received value is wrapped using the Right constructor, while a type mismatch results in Left PeekError with the given error message.

valuetypeMismatchMessage

:: Name
expected type
-> StackIndex
index of offending value
-> Peek e ByteString

#

Generate a type mismatch error.

valuereportValueOnFailure

:: Name
expected type
-> (StackIndex -> LuaE e (Maybe a))
-> Peeker e a

#

Report the expected and actual type of the value under the given index if conversion failed.

Pushing values to Lua stack (Haskell → Lua)

0 declarations

module HsLua.Marshalling.Push

Utilities

1 declaration

valuepushIterator

:: LuaError e
=> (a -> LuaE e NumResults)
pusher for the values
-> [a]
list to iterate over lazily
-> LuaE e NumResults

#

Pushes three values to the stack that can be used in a generic for loop to lazily iterate over all values in the list. Keeps the remaining list in a userdata state.

If the values pusher function returns NumResults 0 for a list item, then this item will be skipped and the values for the next item will be pushed.