-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Marshalling of values between Haskell and Lua.
--   
--   Provides functions to marshal values from Haskell to Lua, and vice
--   versa.
--   
--   This package is part of HsLua, a Haskell framework built around the
--   embeddable scripting language Lua.
@package hslua-marshalling
@version 2.3.1

-- | Types for unmarshalling of values from Lua.
module HsLua.Marshalling.Peek

-- | Function to retrieve a value from Lua's stack.
type Peeker e a = StackIndex -> Peek e a

-- | Runs the peeker function.
runPeeker :: Peeker e a -> StackIndex -> LuaE e (Result a)

-- | Record to keep track of failure contexts while retrieving objects from
--   the Lua stack.
data Result a
Success :: !a -> Result a

-- | Error message and stack of contexts
Failure :: ByteString -> [Name] -> Result a

-- | Returns True iff the peek result is a Failure.
isFailure :: Result a -> Bool

-- | Create a peek failure record from an error message.
failure :: ByteString -> Result a

-- | Force creation of an unwrapped result, throwing an exception if that's
--   not possible.
force :: LuaError e => Result a -> LuaE e a

-- | Add context information to the peek traceback stack.
retrieving :: Name -> Peek e a -> Peek e a

-- | Converts a Result into an Either, where Left holds the
--   reportable string in case of an failure.
resultToEither :: Result a -> Either String a

-- | Converts an old peek funtion to a Peeker.
toPeeker :: LuaError e => (StackIndex -> LuaE e a) -> Peeker e a

-- | Lua operation with an additional failure mode that can stack errors
--   from different contexts; errors are not based on exceptions).
newtype Peek e a
Peek :: LuaE e (Result a) -> Peek e a
[runPeek] :: Peek e a -> LuaE e (Result a)

-- | Converts a Peek action into a LuaE action, throwing an exception in
--   case of a peek failure.
forcePeek :: LuaError e => Peek e a -> LuaE e a

-- | Fails the peek operation.
failPeek :: forall a e. ByteString -> Peek e a

-- | Lifts a Lua operation into the Peek monad.
liftLua :: LuaE e a -> Peek e a

-- | Transform the result using the given function.
withContext :: Name -> Peek e a -> Peek e a

-- | Runs the peek action and Lua action in sequence, even if the peek
--   action fails.
lastly :: Peek e a -> LuaE e b -> 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.
cleanup :: Peek e a -> Peek e a
instance GHC.Internal.Base.Alternative (HsLua.Marshalling.Peek.Peek e)
instance GHC.Internal.Base.Alternative HsLua.Marshalling.Peek.Result
instance GHC.Internal.Base.Applicative (HsLua.Marshalling.Peek.Peek e)
instance GHC.Internal.Base.Applicative HsLua.Marshalling.Peek.Result
instance GHC.Classes.Eq a => GHC.Classes.Eq (HsLua.Marshalling.Peek.Result a)
instance GHC.Internal.Data.Foldable.Foldable HsLua.Marshalling.Peek.Result
instance GHC.Internal.Base.Functor (HsLua.Marshalling.Peek.Peek e)
instance GHC.Internal.Base.Functor HsLua.Marshalling.Peek.Result
instance GHC.Internal.Control.Monad.Fail.MonadFail (HsLua.Marshalling.Peek.Peek e)
instance GHC.Internal.Control.Monad.Fail.MonadFail HsLua.Marshalling.Peek.Result
instance GHC.Internal.Base.MonadPlus (HsLua.Marshalling.Peek.Peek e)
instance GHC.Internal.Base.MonadPlus HsLua.Marshalling.Peek.Result
instance GHC.Internal.Base.Monad (HsLua.Marshalling.Peek.Peek e)
instance GHC.Internal.Base.Monad HsLua.Marshalling.Peek.Result
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (HsLua.Marshalling.Peek.Result a)
instance GHC.Internal.Data.Traversable.Traversable HsLua.Marshalling.Peek.Result

-- | Functions which unmarshal and retrieve Haskell values from Lua's
--   stack.
module HsLua.Marshalling.Peekers

-- | Succeeds if the value at the given index is nil.
peekNil :: Peeker e ()

-- | Succeeds if the given index is not valid or if the value at this index
--   is nil.
peekNoneOrNil :: Peeker e ()

-- | Retrieves a Bool as a Lua boolean.
peekBool :: Peeker e Bool

-- | Retrieves an Integral value from the Lua stack.
peekIntegral :: (Integral a, Read a) => Peeker e a

-- | Retrieve a RealFloat (e.g., Float or Double) from
--   the stack.
peekRealFloat :: (RealFloat a, Read a) => Peeker e a

-- | Retrieves a ByteString as a raw string.
peekByteString :: Peeker e ByteString

-- | Retrieves a lazy ByteString as a raw string.
peekLazyByteString :: Peeker e ByteString

-- | Retrieves a String from an UTF-8 encoded Lua string.
peekString :: Peeker e String

-- | Retrieves a Text value as an UTF-8 encoded string.
peekText :: Peeker e Text

-- | 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.
peekStringy :: IsString a => Peeker e a

-- | Retrieves a Lua string as Name.
peekName :: Peeker e Name

-- | Retrieves a value by getting a String from Lua, then using
--   readMaybe to convert the String into a Haskell value.
peekRead :: Read a => Peeker e a

-- | Read a table into a list of pairs.
peekKeyValuePairs :: LuaError e => Peeker e a -> Peeker e b -> Peeker e [(a, b)]

-- | 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.
peekList :: forall a e. LuaError e => Peeker e a -> Peeker e [a]

-- | Like peekList, but fails if the list is empty.
peekNonEmpty :: LuaError e => Peeker e a -> Peeker e (NonEmpty a)

-- | Retrieves a key-value Lua table as Map.
peekMap :: (LuaError e, Ord a) => Peeker e a -> Peeker e b -> Peeker e (Map a b)

-- | 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.
peekSet :: (LuaError e, Ord a) => Peeker e a -> Peeker e (Set a)

-- | Try all peekers and return the result of the first to succeed.
choice :: LuaError e => [Peeker e a] -> Peeker e a

-- | Get value at key from a table.
peekFieldRaw :: LuaError e => Peeker e a -> Name -> Peeker e a

-- | Get value at integer index key from a table.
peekIndexRaw :: LuaError e => Integer -> Peeker e a -> Peeker e a

-- | Returns empty if the value at the given index is nil;
--   otherwise returns the result of peeker p.
peekNilOr :: Alternative m => Peeker e a -> Peeker e (m a)

-- | Returns empty if the value at the given index is none;
--   otherwise returns the result of peeker p.
peekNoneOr :: Alternative m => Peeker e a -> Peeker e (m a)

-- | Returns empty if the value at the given index is none
--   or nil; otherwise returns the result of peeker p.
peekNoneOrNilOr :: Alternative m => Peeker e a -> Peeker e (m a)

-- | Retrieves a value pair from a table. Expects the values to be stored
--   in a numerically indexed table; does not access metamethods.
peekPair :: LuaError e => Peeker e a -> Peeker e b -> Peeker e (a, b)

-- | Retrieves a value triple from a table. Expects the values to be stored
--   in a numerically indexed table, with no metamethods.
peekTriple :: LuaError e => Peeker e a -> Peeker e b -> Peeker e c -> Peeker e (a, b, c)

-- | 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.
typeChecked :: Name -> (StackIndex -> LuaE e Bool) -> Peeker e a -> Peeker e a

-- | Report the expected and actual type of the value under the given index
--   if conversion failed.
reportValueOnFailure :: Name -> (StackIndex -> LuaE e (Maybe a)) -> Peeker e a

-- | Generate a type mismatch error.
typeMismatchMessage :: Name -> StackIndex -> Peek e ByteString

-- | Functions which marshal and push Haskell values onto Lua's stack.
module HsLua.Marshalling.Push

-- | Function to push a value to Lua's stack.
type Pusher e a = a -> LuaE e ()

-- | Pushes a Bool as a Lua boolean.
pushBool :: Pusher e Bool

-- | Pushes an Integer to the Lua stack. Values representable as
--   Lua integers are pushed as such; bigger integers are represented using
--   their string representation.
pushIntegral :: (Integral a, Show a) => a -> LuaE e ()

-- | Push a floating point number to the Lua stack. Uses a string
--   representation for all types which do not match the float properties
--   of the Number type.
pushRealFloat :: RealFloat a => a -> LuaE e ()

-- | Pushes a ByteString as a raw string.
pushByteString :: Pusher e ByteString

-- | Pushes a lazy ByteString as a raw string.
pushLazyByteString :: Pusher e ByteString

-- | Pushes a String as a UTF-8 encoded Lua string.
pushString :: String -> LuaE e ()

-- | Pushes a Text value as a UTF-8 encoded string.
pushText :: Pusher e Text

-- | Pushes a Name as a UTF-8 encoded Lua string.
pushName :: Name -> LuaE e ()

-- | Push list as numerically indexed table.
pushList :: LuaError e => Pusher e a -> [a] -> LuaE e ()

-- | Push non-empty list as numerically indexed table.
pushNonEmpty :: LuaError e => Pusher e a -> NonEmpty a -> LuaE e ()

-- | Push list of pairs as default key-value Lua table.
pushKeyValuePairs :: LuaError e => Pusher e a -> Pusher e b -> Pusher e [(a, b)]

-- | Push Map as default key-value Lua table.
pushMap :: LuaError e => Pusher e a -> Pusher e b -> Pusher e (Map a b)

-- | Push a Set as idiomatic Lua set, i.e., as a table with the set
--   elements as keys and true as values.
pushSet :: LuaError e => Pusher e a -> Pusher e (Set a)

-- | Pushes a pair of values as a two element list.
pushPair :: LuaError e => Pusher e a -> Pusher e b -> (a, b) -> LuaE e ()

-- | Pushes a value triple as a three element list.
pushTriple :: LuaError e => Pusher e a -> Pusher e b -> Pusher e c -> (a, b, c) -> LuaE e ()

-- | Pushes an object as a table, defined by a list of
--   field-names/push-function pairs.
pushAsTable :: LuaError e => [(Name, a -> LuaE e ())] -> a -> LuaE e ()

-- | Convenience functions to use Haskell values as Lua userdata.
module HsLua.Marshalling.Userdata

-- | 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.
pushIterator :: forall a e. LuaError e => (a -> LuaE e NumResults) -> [a] -> LuaE e NumResults

-- | Functions to push and retrieve data to and from Lua.
module HsLua.Marshalling

-- | Function to retrieve a value from Lua's stack.
type Peeker e a = StackIndex -> Peek e a

-- | Runs the peeker function.
runPeeker :: Peeker e a -> StackIndex -> LuaE e (Result a)

-- | Record to keep track of failure contexts while retrieving objects from
--   the Lua stack.
data Result a
Success :: !a -> Result a

-- | Error message and stack of contexts
Failure :: ByteString -> [Name] -> Result a

-- | Force creation of an unwrapped result, throwing an exception if that's
--   not possible.
force :: LuaError e => Result a -> LuaE e a

-- | Add context information to the peek traceback stack.
retrieving :: Name -> Peek e a -> Peek e a

-- | Create a peek failure record from an error message.
failure :: ByteString -> Result a

-- | Converts a Result into an Either, where Left holds the
--   reportable string in case of an failure.
resultToEither :: Result a -> Either String a

-- | Succeeds if the value at the given index is nil.
peekNil :: Peeker e ()

-- | Succeeds if the given index is not valid or if the value at this index
--   is nil.
peekNoneOrNil :: Peeker e ()

-- | Retrieves a Bool as a Lua boolean.
peekBool :: Peeker e Bool

-- | Retrieves an Integral value from the Lua stack.
peekIntegral :: (Integral a, Read a) => Peeker e a

-- | Retrieve a RealFloat (e.g., Float or Double) from
--   the stack.
peekRealFloat :: (RealFloat a, Read a) => Peeker e a

-- | Retrieves a ByteString as a raw string.
peekByteString :: Peeker e ByteString

-- | Retrieves a lazy ByteString as a raw string.
peekLazyByteString :: Peeker e ByteString

-- | Retrieves a String from an UTF-8 encoded Lua string.
peekString :: Peeker e String

-- | Retrieves a Text value as an UTF-8 encoded string.
peekText :: Peeker e Text

-- | 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.
peekStringy :: IsString a => Peeker e a

-- | Retrieves a Lua string as Name.
peekName :: Peeker e Name

-- | Retrieves a value by getting a String from Lua, then using
--   readMaybe to convert the String into a Haskell value.
peekRead :: Read a => Peeker e a

-- | Read a table into a list of pairs.
peekKeyValuePairs :: LuaError e => Peeker e a -> Peeker e b -> Peeker e [(a, b)]

-- | 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.
peekList :: forall a e. LuaError e => Peeker e a -> Peeker e [a]

-- | Retrieves a key-value Lua table as Map.
peekMap :: (LuaError e, Ord a) => Peeker e a -> Peeker e b -> Peeker e (Map a b)

-- | 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.
peekSet :: (LuaError e, Ord a) => Peeker e a -> Peeker e (Set a)

-- | Try all peekers and return the result of the first to succeed.
choice :: LuaError e => [Peeker e a] -> Peeker e a

-- | Get value at key from a table.
peekFieldRaw :: LuaError e => Peeker e a -> Name -> Peeker e a

-- | Retrieves a value pair from a table. Expects the values to be stored
--   in a numerically indexed table; does not access metamethods.
peekPair :: LuaError e => Peeker e a -> Peeker e b -> Peeker e (a, b)

-- | Retrieves a value triple from a table. Expects the values to be stored
--   in a numerically indexed table, with no metamethods.
peekTriple :: LuaError e => Peeker e a -> Peeker e b -> Peeker e c -> Peeker e (a, b, c)

-- | Returns empty if the value at the given index is nil;
--   otherwise returns the result of peeker p.
peekNilOr :: Alternative m => Peeker e a -> Peeker e (m a)

-- | Returns empty if the value at the given index is none;
--   otherwise returns the result of peeker p.
peekNoneOr :: Alternative m => Peeker e a -> Peeker e (m a)

-- | Returns empty if the value at the given index is none
--   or nil; otherwise returns the result of peeker p.
peekNoneOrNilOr :: Alternative m => Peeker e a -> Peeker e (m a)

-- | Lua operation with an additional failure mode that can stack errors
--   from different contexts; errors are not based on exceptions).
newtype Peek e a
Peek :: LuaE e (Result a) -> Peek e a
[runPeek] :: Peek e a -> LuaE e (Result a)

-- | Converts a Peek action into a LuaE action, throwing an exception in
--   case of a peek failure.
forcePeek :: LuaError e => Peek e a -> LuaE e a

-- | Lifts a Lua operation into the Peek monad.
liftLua :: LuaE e a -> Peek e a

-- | Transform the result using the given function.
withContext :: Name -> Peek e a -> Peek e a

-- | Fails the peek operation.
failPeek :: forall a e. ByteString -> Peek e a

-- | Runs the peek action and Lua action in sequence, even if the peek
--   action fails.
lastly :: Peek e a -> LuaE e b -> 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.
cleanup :: Peek e a -> Peek 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.
typeChecked :: Name -> (StackIndex -> LuaE e Bool) -> Peeker e a -> Peeker e a

-- | Generate a type mismatch error.
typeMismatchMessage :: Name -> StackIndex -> Peek e ByteString

-- | Report the expected and actual type of the value under the given index
--   if conversion failed.
reportValueOnFailure :: Name -> (StackIndex -> LuaE e (Maybe a)) -> Peeker e a

-- | 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.
pushIterator :: forall a e. LuaError e => (a -> LuaE e NumResults) -> [a] -> LuaE e NumResults
