Copyright	© 2020-2022 Albert Krewinkel
License	MIT
Maintainer	Albert Krewinkel <tarleb+hslua@zeitkraut.de>
Stability	beta
Portability	Portable
Safe Haskell	None
Language	Haskell2010

HsLua.Marshalling.Peekers

Contents

Peeking values from the stack

Description

Functions which unmarshal and retrieve Haskell values from Lua's stack.

Synopsis

peekNil :: Peeker e ()
peekNoneOrNil :: Peeker e ()
peekBool :: Peeker e Bool
peekIntegral :: forall a e. (Integral a, Read a) => Peeker e a
peekRealFloat :: forall a e. (RealFloat a, Read a) => Peeker e a
peekByteString :: Peeker e ByteString
peekLazyByteString :: Peeker e ByteString
peekString :: Peeker e String
peekText :: Peeker e Text
peekStringy :: forall a e. IsString a => Peeker e a
peekName :: Peeker e Name
peekRead :: forall a e. Read a => Peeker e a
peekKeyValuePairs :: LuaError e => Peeker e a -> Peeker e b -> Peeker e [(a, b)]
peekList :: forall a e. LuaError e => Peeker e a -> Peeker e [a]
peekMap :: (LuaError e, Ord a) => Peeker e a -> Peeker e b -> Peeker e (Map a b)
peekSet :: (LuaError e, Ord a) => Peeker e a -> Peeker e (Set a)
choice :: LuaError e => [Peeker e a] -> Peeker e a
peekFieldRaw :: LuaError e => Peeker e a -> Name -> Peeker e a
peekIndexRaw :: LuaError e => Integer -> Peeker e a -> Peeker e a
peekPair :: LuaError e => Peeker e a -> Peeker e b -> Peeker e (a, b)
peekTriple :: LuaError e => Peeker e a -> Peeker e b -> Peeker e c -> Peeker e (a, b, c)
typeChecked :: Name -> (StackIndex -> LuaE e Bool) -> Peeker e a -> Peeker e a
reportValueOnFailure :: Name -> (StackIndex -> LuaE e (Maybe a)) -> Peeker e a
typeMismatchMessage :: Name -> StackIndex -> Peek e ByteString

Peeking values from the stack

Primitives

peekNil :: Peeker e () Source #

Succeeds if the value at the given index is nil.

peekNoneOrNil :: Peeker e () Source #

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

peekBool :: Peeker e Bool Source #

Retrieves a Bool as a Lua boolean.

peekIntegral :: forall a e. (Integral a, Read a) => Peeker e a Source #

Retrieves an Integral value from the Lua stack.

peekRealFloat :: forall a e. (RealFloat a, Read a) => Peeker e a Source #

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

Strings

peekByteString :: Peeker e ByteString Source #

Retrieves a ByteString as a raw string.

peekLazyByteString :: Peeker e ByteString Source #

Retrieves a lazy ByteString as a raw string.

peekString :: Peeker e String Source #

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

peekText :: Peeker e Text Source #

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

peekStringy :: forall a e. IsString a => Peeker e a Source #

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.

peekName :: Peeker e Name Source #

Retrieves a Lua string as Name.

Readable types

peekRead :: forall a e. Read a => Peeker e a Source #

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

Collections

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

Read a table into a list of pairs.

peekList :: forall a e. LuaError e => Peeker e a -> Peeker e [a] Source #

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.

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

Retrieves a key-value Lua table as Map.

peekSet :: (LuaError e, Ord a) => Peeker e a -> Peeker e (Set a) Source #

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

choice :: LuaError e => [Peeker e a] -> Peeker e a Source #

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

peekFieldRaw :: LuaError e => Peeker e a -> Name -> Peeker e a Source #

Get value at key from a table.

peekIndexRaw :: LuaError e => Integer -> Peeker e a -> Peeker e a Source #

Get value at integer index key from a table.

peekPair :: LuaError e => Peeker e a -> Peeker e b -> Peeker e (a, b) Source #

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

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

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

Building peek functions

typeChecked Source #

Arguments

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

reportValueOnFailure Source #

Arguments

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

typeMismatchMessage Source #

Arguments

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

Generate a type mismatch error.