HsLua.Marshalling.Peekers

hslua-marshalling-2.3.1: Marshalling of values between Haskell and Lua.

Copyright | © 2020-2024 Albert Krewinkel
License | MIT
Maintainer | Albert Krewinkel <tarleb@hslua.org>
Stability | beta
Portability | Portable
Safe Haskell | None
Language | Haskell2010

HsLua.Marshalling.Peekers

Contents

- Peeking values from the stack
  - Primitives
  - Strings
  - Readable types
  - Collections
  - Combinators
  - Building peek functions

Description

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

Synopsis

- peekNil :: Peeker e ()
- peekNoneOrNil :: Peeker e ()
- peekBool :: Peeker e Bool
- peekIntegral :: (Integral a, Read a) => Peeker e a
- peekRealFloat :: (RealFloat a, Read a) => Peeker e a
- peekByteString :: Peeker e ByteString
- peekLazyByteString :: Peeker e ByteString
- peekString :: Peeker e String
- peekText :: Peeker e Text
- peekStringy :: IsString a => Peeker e a
- peekName :: Peeker e Name
- peekRead :: 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]
- peekNonEmpty :: LuaError e => Peeker e a -> Peeker e (NonEmpty 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
- peekNilOr :: Alternative m => Peeker e a -> Peeker e (m a)
- peekNoneOr :: Alternative m => Peeker e a -> Peeker e (m a)
- peekNoneOrNilOr :: Alternative m => Peeker e a -> Peeker e (m 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 () #

Succeeds if the value at the given index is `nil`.

peekNoneOrNil :: Peeker e () #

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

peekBool :: Peeker e Bool #

Retrieves a `Bool` as a Lua boolean.

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

Retrieves an `Integral` value from the Lua stack.

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

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

## Strings

peekByteString :: Peeker e ByteString #

Retrieves a `ByteString` as a raw string.

peekLazyByteString :: Peeker e ByteString #

Retrieves a lazy `ByteString` as a raw string.

peekString :: Peeker e String #

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

peekText :: Peeker e Text #

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

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

peekName :: Peeker e Name #

Retrieves a Lua string as `Name`.

## Readable types

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

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

Read a table into a list of pairs.

peekList :: forall a e. 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.

peekNonEmpty :: LuaError e => Peeker e a -> Peeker e (NonEmpty a) #

Like `peekList`, but fails if the list is empty.

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

Retrieves a key-value Lua table as `Map`.

peekSet :: (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

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

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

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

Get value at key from a table.

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

Get value at integer index key from a table.

peekNilOr #

Arguments

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

peekNoneOr #

Arguments

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

peekNoneOrNilOr #

Arguments

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

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

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

## Building peek functions

typeChecked #

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 #

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 #

Arguments

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

Generate a type mismatch error.