-- 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 <i>vice
--   versa</i>.
--   
--   This package is part of HsLua, a Haskell framework built around the
--   embeddable scripting language <a>Lua</a>.
@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 <a>True</a> 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 <tt>Left</tt> holds the
--   reportable string in case of an failure.
resultToEither :: Result a -> Either String a

-- | Converts an old peek funtion to a <a>Peeker</a>.
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 Data.Traversable.Traversable HsLua.Marshalling.Peek.Result
instance GHC.Base.Functor HsLua.Marshalling.Peek.Result
instance Data.Foldable.Foldable HsLua.Marshalling.Peek.Result
instance GHC.Classes.Eq a => GHC.Classes.Eq (HsLua.Marshalling.Peek.Result a)
instance GHC.Show.Show a => GHC.Show.Show (HsLua.Marshalling.Peek.Result a)
instance GHC.Base.Functor (HsLua.Marshalling.Peek.Peek e)
instance GHC.Base.Applicative (HsLua.Marshalling.Peek.Peek e)
instance GHC.Base.Monad (HsLua.Marshalling.Peek.Peek e)
instance GHC.Base.Alternative (HsLua.Marshalling.Peek.Peek e)
instance GHC.Base.MonadPlus (HsLua.Marshalling.Peek.Peek e)
instance Control.Monad.Fail.MonadFail (HsLua.Marshalling.Peek.Peek e)
instance GHC.Base.Applicative HsLua.Marshalling.Peek.Result
instance GHC.Base.Monad HsLua.Marshalling.Peek.Result
instance GHC.Base.Alternative HsLua.Marshalling.Peek.Result
instance GHC.Base.MonadPlus HsLua.Marshalling.Peek.Result
instance Control.Monad.Fail.MonadFail 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 <tt>nil</tt>.
peekNil :: Peeker e ()

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

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

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

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

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

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

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

-- | Retrieves a <a>Text</a> 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 <a>ByteString</a> values or other
--   values for which construction via <a>fromString</a> can result in loss
--   of information.
peekStringy :: forall a e. IsString a => Peeker e a

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

-- | Retrieves a value by getting a String from Lua, then using
--   <a>readMaybe</a> to convert the String into a Haskell value.
peekRead :: forall a e. 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 <tt>t</tt> into a list, where the
--   <a>length</a> of the list is equal to <tt>rawlen(t)</tt>. The
--   operation will fail unless all numerical fields between <tt>1</tt> and
--   <tt>rawlen(t)</tt> can be retrieved.
peekList :: forall a e. LuaError e => Peeker e a -> Peeker e [a]

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

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

-- | Retrieves a <a>Set</a> 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 <a>empty</a> if the value at the given index is <tt>nil</tt>;
--   otherwise returns the result of peeker <tt>p</tt>.
peekNilOr :: Alternative m => Peeker e a -> Peeker e (m a)

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

-- | Returns <a>empty</a> if the value at the given index is <tt>none</tt>
--   or <tt>nil</tt>; otherwise returns the result of peeker <tt>p</tt>.
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 <tt>test</tt> to check whether the value at stack index <tt>n</tt>
--   has the correct type and use <tt>peekfn</tt> to convert it to a
--   Haskell value if possible. A successfully received value is wrapped
--   using the <a>Right</a> constructor, while a type mismatch results in
--   <tt>Left PeekError</tt> 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 <a>Bool</a> as a Lua boolean.
pushBool :: Pusher e Bool

-- | Pushes an <tt>Integer</tt> 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 <a>Number</a> type.
pushRealFloat :: RealFloat a => a -> LuaE e ()

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

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

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

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

-- | Pushes a <a>Name</a> 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 <a>Map</a> as default key-value Lua table.
pushMap :: LuaError e => Pusher e a -> Pusher e b -> Pusher e (Map a b)

-- | Push a <a>Set</a> as idiomatic Lua set, i.e., as a table with the set
--   elements as keys and <tt>true</tt> 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 <tt><a>NumResults</a> 0</tt> 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 <tt>Left</tt> holds the
--   reportable string in case of an failure.
resultToEither :: Result a -> Either String a

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

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

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

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

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

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

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

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

-- | Retrieves a <a>Text</a> 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 <a>ByteString</a> values or other
--   values for which construction via <a>fromString</a> can result in loss
--   of information.
peekStringy :: forall a e. IsString a => Peeker e a

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

-- | Retrieves a value by getting a String from Lua, then using
--   <a>readMaybe</a> to convert the String into a Haskell value.
peekRead :: forall a e. 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 <tt>t</tt> into a list, where the
--   <a>length</a> of the list is equal to <tt>rawlen(t)</tt>. The
--   operation will fail unless all numerical fields between <tt>1</tt> and
--   <tt>rawlen(t)</tt> can be retrieved.
peekList :: forall a e. LuaError e => Peeker e a -> Peeker e [a]

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

-- | Retrieves a <a>Set</a> 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 <a>empty</a> if the value at the given index is <tt>nil</tt>;
--   otherwise returns the result of peeker <tt>p</tt>.
peekNilOr :: Alternative m => Peeker e a -> Peeker e (m a)

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

-- | Returns <a>empty</a> if the value at the given index is <tt>none</tt>
--   or <tt>nil</tt>; otherwise returns the result of peeker <tt>p</tt>.
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 <tt>test</tt> to check whether the value at stack index <tt>n</tt>
--   has the correct type and use <tt>peekfn</tt> to convert it to a
--   Haskell value if possible. A successfully received value is wrapped
--   using the <a>Right</a> constructor, while a type mismatch results in
--   <tt>Left PeekError</tt> 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 <tt><a>NumResults</a> 0</tt> 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