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


-- | 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 GHC.Base.Functor (HsLua.Marshalling.Peek.Peek e)
instance GHC.Base.Functor 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.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 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


-- | 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]

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

-- | 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 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)

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