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

Copyright | © 2007–2012 Gracjan Polak; © 2012–2016 Ömer Sinan Ağacan; © 2017-2024 Albert Krewinkel
License | MIT
Maintainer | Albert Krewinkel <tarleb@hslua.org>
Safe Haskell | None
Language | Haskell2010

HsLua.Marshalling

Contents

- Receiving values from Lua stack (Lua → Haskell)
  - Primitive types
  - Strings
  - Readable types
  - Collections
  - Combinators
  - Lua peek monad
  - Building Peek functions
- Pushing values to Lua stack (Haskell → Lua)
- Utilities

Description

Functions to push and retrieve data to and from Lua.

Synopsis

- type Peeker e a = StackIndex -> Peek e a
- runPeeker :: Peeker e a -> StackIndex -> LuaE e (Result a)
- data Result a
  - = Success !a
  - | Failure ByteString [Name]
- force :: LuaError e => Result a -> LuaE e a
- retrieving :: Name -> Peek e a -> Peek e a
- failure :: ByteString -> Result a
- resultToEither :: Result a -> Either String a
- 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]
- 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
- 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)
- 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)
- newtype Peek e a = Peek {
  - runPeek :: LuaE e (Result a)
  }
- forcePeek :: LuaError e => Peek e a -> LuaE e a
- liftLua :: LuaE e a -> Peek e a
- withContext :: Name -> Peek e a -> Peek e a
- failPeek :: forall a e. ByteString -> Peek e a
- lastly :: Peek e a -> LuaE e b -> Peek e a
- cleanup :: Peek e a -> Peek e a
- typeChecked :: Name -> (StackIndex -> LuaE e Bool) -> Peeker e a -> Peeker e a
- typeMismatchMessage :: Name -> StackIndex -> Peek e ByteString
- reportValueOnFailure :: Name -> (StackIndex -> LuaE e (Maybe a)) -> Peeker e a
- module HsLua.Marshalling.Push
- pushIterator :: forall a e. LuaError e => (a -> LuaE e NumResults) -> [a] -> LuaE e NumResults

# Receiving values from Lua stack (Lua → Haskell)

type Peeker e a = StackIndex -> Peek e a Source #

Function to retrieve a value from Lua's stack.

runPeeker :: Peeker e a -> StackIndex -> LuaE e (Result a) Source #

Runs the peeker function.

data Result a Source #

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

#### Instances

Instances details

Alternative Result Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods empty :: Result a Source # (<|>) :: Result a -> Result a -> Result a Source # some :: Result a -> Result [a] Source # many :: Result a -> Result [a] Source #
Applicative Result Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods pure :: a -> Result a Source # (<*>) :: Result (a -> b) -> Result a -> Result b Source # liftA2 :: (a -> b -> c) -> Result a -> Result b -> Result c Source # (*>) :: Result a -> Result b -> Result b Source # (<*) :: Result a -> Result b -> Result a Source #
Functor Result Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods fmap :: (a -> b) -> Result a -> Result b Source # (<$) :: a -> Result b -> Result a Source #
Monad Result Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods (>>=) :: Result a -> (a -> Result b) -> Result b Source # (>>) :: Result a -> Result b -> Result b Source # return :: a -> Result a Source #
MonadPlus Result Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods mzero :: Result a Source # mplus :: Result a -> Result a -> Result a Source #
MonadFail Result Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods fail :: String -> Result a Source #
Foldable Result Source # |

Instance details

Defined in HsLua.Marshalling.Peek

Methods

fold :: Monoid m => Result m -> m Source #

foldMap :: Monoid m => (a -> m) -> Result a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Result a -> m Source #

foldr :: (a -> b -> b) -> b -> Result a -> b Source #

foldr' :: (a -> b -> b) -> b -> Result a -> b Source #

foldl :: (b -> a -> b) -> b -> Result a -> b Source #

foldl' :: (b -> a -> b) -> b -> Result a -> b Source #

foldr1 :: (a -> a -> a) -> Result a -> a Source #

foldl1 :: (a -> a -> a) -> Result a -> a Source #

toList :: Result a -> [a] Source #

null :: Result a -> Bool Source #

length :: Result a -> Int Source #

elem :: Eq a => a -> Result a -> Bool Source #

maximum :: Ord a => Result a -> a Source #

minimum :: Ord a => Result a -> a Source #

sum :: Num a => Result a -> a Source #

product :: Num a => Result a -> a Source #

Traversable Result Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods traverse :: Applicative f => (a -> f b) -> Result a -> f (Result b) Source # sequenceA :: Applicative f => Result (f a) -> f (Result a) Source # mapM :: Monad m => (a -> m b) -> Result a -> m (Result b) Source # sequence :: Monad m => Result (m a) -> m (Result a) Source #
Show a => Show (Result a) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods showsPrec :: Int -> Result a -> ShowS Source # show :: Result a -> String Source # showList :: [Result a] -> ShowS Source #
Eq a => Eq (Result a) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods (==) :: Result a -> Result a -> Bool Source # (/=) :: Result a -> Result a -> Bool Source #

force :: LuaError e => Result a -> LuaE e a Source #

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

retrieving :: Name -> Peek e a -> Peek e a Source #

Add context information to the peek traceback stack.

failure :: ByteString -> Result a Source #

Create a peek failure record from an error message.

resultToEither :: Result a -> Either String a Source #

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

## Primitive types

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 :: (Integral a, Read a) => Peeker e a Source #

Retrieves an `Integral` value from the Lua stack.

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

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.

peekNilOr Source #

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

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

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

## Lua peek monad

newtype Peek e a Source #

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

Constructors

Peek |

Fields

- runPeek :: LuaE e (Result a)

#### Instances

Instances details

Alternative (Peek e) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods empty :: Peek e a Source # (<|>) :: Peek e a -> Peek e a -> Peek e a Source # some :: Peek e a -> Peek e [a] Source # many :: Peek e a -> Peek e [a] Source #
Applicative (Peek e) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods pure :: a -> Peek e a Source # (<*>) :: Peek e (a -> b) -> Peek e a -> Peek e b Source # liftA2 :: (a -> b -> c) -> Peek e a -> Peek e b -> Peek e c Source # (*>) :: Peek e a -> Peek e b -> Peek e b Source # (<*) :: Peek e a -> Peek e b -> Peek e a Source #
Functor (Peek e) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods fmap :: (a -> b) -> Peek e a -> Peek e b Source # (<$) :: a -> Peek e b -> Peek e a Source #
Monad (Peek e) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods (>>=) :: Peek e a -> (a -> Peek e b) -> Peek e b Source # (>>) :: Peek e a -> Peek e b -> Peek e b Source # return :: a -> Peek e a Source #
MonadPlus (Peek e) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods mzero :: Peek e a Source # mplus :: Peek e a -> Peek e a -> Peek e a Source #
MonadFail (Peek e) Source # |
Instance details Defined in HsLua.Marshalling.Peek Methods fail :: String -> Peek e a Source #

forcePeek :: LuaError e => Peek e a -> LuaE e a Source #

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

liftLua :: LuaE e a -> Peek e a Source #

Lifts a Lua operation into the Peek monad.

withContext :: Name -> Peek e a -> Peek e a Source #

Transform the result using the given function.

failPeek :: forall a e. ByteString -> Peek e a Source #

Fails the peek operation.

lastly :: Peek e a -> LuaE e b -> Peek e a Source #

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

cleanup :: Peek e a -> Peek e a Source #

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

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.

typeMismatchMessage Source #

Arguments

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

Generate a type mismatch error.

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.

# Pushing values to Lua stack (Haskell → Lua)

module HsLua.Marshalling.Push

# Utilities

pushIterator Source #

Arguments

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