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


-- | PHP session and values serialization
--   
--   A library for encoding and decoding serialized PHP sessions in the
--   format used by the "php" setting for session.serialize_handler as well
--   as encoding and decoding serialized values.
@package hs-php-session
@version 0.0.9.3


-- | Types used for representing PHP data types from encoding and decoding
--   a PHP session.
module Data.PHPSession.Types

-- | Holds the "top-level" session variables and their value contents.
type PHPSessionVariableList = [(ByteString, PHPSessionValue)]

-- | Represents the name of a PHP class.
data PHPSessionClassName
PHPSessionClassName :: ByteString -> PHPSessionClassName

-- | <a>PHPSessionValue</a> Represents a PHP value, which may be a number,
--   string, array, object, boolean, null, or references.
--   
--   <ul>
--   <li><a>PHPSessionValueArray</a> represents an array as a list of
--   key-value pairs of values of type <a>PHPSessionValue</a>.</li>
--   <li><a>PHPSessionValueObject</a> is similar to
--   <a>PHPSessionValueArray</a> but also includes a class name of type
--   <a>PHPSessionClassName</a>.</li>
--   <li><a>PHPSessionValueObjectSerializeable</a> represent objects of
--   which their classes implement Serializeable to handle their own
--   serialization and don't use the normal serialization format for its
--   contained objects.</li>
--   <li><a>PHPSessionValueBool</a>, <a>PHPSessionValueInt</a>,
--   <a>PHPSessionValueFloat</a>, <a>PHPSessionValueNull</a>, and
--   <a>PHPSessionValueString</a> represent basic types boolean, integer,
--   floats, null and string respectively.</li>
--   <li><a>PHPSessionValueFloat</a> stores the number representation as an
--   <a>Either</a> <a>Int</a> <a>Double</a> to preserve instances where the
--   number representation is actually an integer. It should be noted that
--   the re-encoded value is usually rounded unlike PHP's
--   representation.</li>
--   <li><a>PHPSessionValueMisc</a> stores a few other types such as
--   references and values which follow the general serialization format
--   but aren't recognized by the decoder. A list of <a>PHPSessionAttr</a>
--   provides the information for reconstructing the serialized
--   representation when re-encoding this type of value.</li>
--   </ul>
data PHPSessionValue
PHPSessionValueArray :: [(PHPSessionValue, PHPSessionValue)] -> PHPSessionValue
PHPSessionValueBool :: Bool -> PHPSessionValue
PHPSessionValueFloat :: Either Int Double -> PHPSessionValue
PHPSessionValueInt :: Int -> PHPSessionValue
PHPSessionValueNull :: PHPSessionValue
PHPSessionValueObject :: PHPSessionClassName -> [(PHPSessionValue, PHPSessionValue)] -> PHPSessionValue
PHPSessionValueObjectSerializeable :: PHPSessionClassName -> ByteString -> PHPSessionValue
PHPSessionValueString :: ByteString -> PHPSessionValue
PHPSessionValueMisc :: ByteString -> [PHPSessionAttr] -> PHPSessionValue

-- | <a>PHPSessionAttr</a> are values associated with
--   <a>PHPSessionValueMisc</a> to inspect and generally re-encode the
--   necessary information for that value.
data PHPSessionAttr
PHPSessionAttrInt :: Int -> PHPSessionAttr
PHPSessionAttrFloat :: Double -> PHPSessionAttr
PHPSessionAttrNested :: [PHPSessionValue] -> PHPSessionAttr

-- | <a>PHPSessionDecodingError</a> are error types that can be returned if
--   decoding did not succeed. They are returned by the <a>Either</a>
--   versions of the decoding functions.
--   
--   <ul>
--   <li><a>PHPSessionStringEmpty</a> is given if the decoder got an empty
--   byte sequence.</li>
--   <li><a>PHPSessionCouldntDecodeSerializablePast</a> is given if the
--   decoding does not succeed while in the particular byte sequence for a
--   class that implements Serializable.</li>
--   <li><a>PHPSessionCouldntDecodeObjectPast</a> is given if the decoding
--   does not succeed while in the particular byte sequence for a PHP
--   object value.</li>
--   <li><a>PHPSessionCouldntDecodeStringPast</a> is given if the decoding
--   does not succeed while in the particular byte sequence for a PHP
--   string.</li>
--   <li><a>PHPSessionCouldntDecodePast</a> is given if the decoding does
--   not succeed while decoding common byte sequences which are composed
--   mainly of <a>PHPSessionAttr</a> forms.</li>
--   <li><a>PHPSessionValueNotFullyDecoded</a> is given if the byte
--   sequence is not fully decoded to a <a>PHPSessionValue</a> when using
--   decodePHPSessionValue or decodePHPSessionValueEither.</li>
--   <li><a>PHPSessionNotFullyDecoded</a> is given.if the byte sequence is
--   not fully decoded to a <a>PHPSessionVariableList</a> when using
--   decodePHPSession or decodePHPSessionEither.</li>
--   </ul>
data PHPSessionDecodingError
PHPSessionStringEmpty :: PHPSessionDecodingError
PHPSessionCouldntDecodeSerializablePast :: ByteString -> PHPSessionDecodingError
PHPSessionCouldntDecodeObjectPast :: ByteString -> PHPSessionDecodingError
PHPSessionCouldntDecodeStringPast :: ByteString -> PHPSessionDecodingError
PHPSessionCouldntDecodePast :: ByteString -> PHPSessionDecodingError
PHPSessionValueNotFullyDecoded :: PHPSessionValue -> ByteString -> PHPSessionDecodingError
PHPSessionNotFullyDecoded :: PHPSessionVariableList -> ByteString -> PHPSessionDecodingError
instance GHC.Show.Show Data.PHPSession.Types.PHPSessionDecodingError
instance GHC.Classes.Eq Data.PHPSession.Types.PHPSessionDecodingError
instance GHC.Show.Show Data.PHPSession.Types.PHPSessionValue
instance GHC.Classes.Eq Data.PHPSession.Types.PHPSessionValue
instance GHC.Classes.Ord Data.PHPSession.Types.PHPSessionValue
instance GHC.Show.Show Data.PHPSession.Types.PHPSessionAttr
instance GHC.Classes.Eq Data.PHPSession.Types.PHPSessionAttr
instance GHC.Show.Show Data.PHPSession.Types.PHPSessionClassName
instance GHC.Classes.Eq Data.PHPSession.Types.PHPSessionClassName


-- | Non-coerced and coerced rule sets for converting
--   <a>PHPSessionValue</a> objects to <a>Bool</a>.
module Data.PHPSession.ImplicitConv.ConvBool

-- | Returns the value of a boolean value as a <a>Bool</a>, or returns
--   False as the default <a>Bool</a> value if the <a>PHPSessionValue</a>
--   is not a boolean type. This function is similar to the "strict
--   comparison" operator against the boolean <tt><i>TRUE</i></tt> value.
boolDefaultFalseFrom :: PHPSessionValue -> Bool

-- | Returns the value of a boolean value as a <a>Bool</a>, or returns True
--   as the default <a>Bool</a> value if the <a>PHPSessionValue</a> is not
--   a boolean type.
boolDefaultTrueFrom :: PHPSessionValue -> Bool

-- | Coerces a <a>PHPSessionValue</a> to a <a>Bool</a> based on PHP's
--   conversion rules to convert arbitrary values to boolean for
--   evaluation. This function's behaviour is also reminiscent of PHP's
--   "loose comparison" operator against boolean <tt><i>TRUE</i></tt>.
--   <a>http://php.net/manual/language.types.boolean.php</a>
--   
--   Values that result in <a>True</a> are <tt><i>TRUE</i></tt>, non-zero
--   numbers, non-empty strings other than "0", objects, and non-empty
--   arrays.
--   
--   A conversion documented in the PHP manual involving <tt>SimpleXML</tt>
--   objects that coerce to <tt><i>FALSE</i></tt> instead of
--   <tt><i>TRUE</i></tt> when created with empty tags is not implemented
--   by this function, as SimpleXML objects cannot be serialized directly
--   and so don't have a valid serializable form to convert from in any
--   case.
--   
--   Because of the range of valid values of the "loose comparison"
--   operator, this function and variations based on other dynamically
--   typed languages is provided mainly for circumstances where they may be
--   the best fit to map particular data values to a boolean truth value
--   system. <a>boolFromReducedLooseCoercionSafe</a> provides a
--   significantly reduced subset of valid values to coerce from for the
--   purpose of determining a "confirmation" value, as opposed to simply
--   determining if a value exists or not.
boolFromPHPLooseComparisonWithTrue :: PHPSessionValue -> Bool

-- | A version of <a>boolFromPHPLooseComparisonWithTrue</a> where
--   <tt><i>NULL</i></tt> returns <a>Nothing</a> and all other inputs
--   returns <a>Just</a> with the boolean result.
boolFromPHPLooseComparisonWithTrueNullable :: PHPSessionValue -> Maybe Bool

-- | Coerces a <a>PHPSessionValue</a> to a <a>Bool</a> through a reduced
--   subset of valid values. <a>boolFromReducedLooseCoercionSafe</a> and
--   <a>boolFromReducedLooseCoercion</a> are functions intended for testing
--   a variable for a boolean "confirmation" from a limited number of
--   probable representations.
--   
--   Values that result in <a>True</a> are <tt><i>TRUE</i></tt>, non-zero
--   numbers, "1" and "-1".
--   
--   Values that result in <a>False</a> are <tt><i>FALSE</i></tt>, zero
--   numbers, <tt><i>NULL</i></tt>, "0" and "".
--   
--   Values such as arrays, objects and arbitrary strings, are invalid with
--   this function and return an error. In the case of
--   <a>boolFromReducedLooseCoercionSafe</a> this returns a <a>Left</a>
--   with the error message.
boolFromReducedLooseCoercionSafe :: PHPSessionValue -> Either String Bool

-- | A version of <a>boolFromReducedLooseCoercionSafe</a> that may throw
--   exceptions.
boolFromReducedLooseCoercion :: PHPSessionValue -> Bool

-- | A version of <a>boolFromReducedLooseCoercionSafe</a> where
--   <tt><i>NULL</i></tt> returns <a>Right</a> <a>Nothing</a> and all other
--   inputs returns <a>Right</a> <a>Just</a> with the boolean result. May
--   return <a>Left</a> with an error message if given invalid values.
boolFromReducedLooseCoercionNullableSafe :: PHPSessionValue -> Either String (Maybe Bool)

-- | A version of <a>boolFromReducedLooseCoercion</a> where
--   <tt><i>NULL</i></tt> returns <a>Nothing</a> and all other inputs
--   returns <a>Just</a> with the boolean result. May throw an exception on
--   invalid values.
boolFromReducedLooseCoercionNullable :: PHPSessionValue -> Maybe Bool

-- | Alternative boolean coercion based on the JS/ES boolean conversion
--   rules. A particular distinction of the coercion behaviour of this
--   function compared to the behaviour of other functions is that floating
--   point NaN returns <a>False</a> instead of <a>True</a>. Values that
--   return <a>False</a> are <tt><i>NAN</i></tt>, 0, the empty string "",
--   <tt><i>NULL</i></tt> and <tt><i>FALSE</i></tt>
--   
--   PHP objects, arrays and objects implementing Serializable always
--   return <a>True</a>.
--   
--   JS/ES's boolean conversion is described in section 9.2 of the ECMA 262
--   standard.
boolFromESBooleanCoercionRules :: PHPSessionValue -> Bool

-- | Alternative boolean coercion based on non-overloaded Perl 5 rules.
--   Values that return <a>False</a> are the empty string "", the string
--   containing "0", 0, <tt><i>NULL</i></tt> and <tt><i>FALSE</i></tt>.
--   
--   PHP objects, arrays and objects implementing Serializable always
--   return <a>True</a>.
--   
--   Perl's boolean coercion rules are described in the section "Truth and
--   Falsehood" of "perlsyn".
--   <a>http://perldoc.perl.org/perlsyn.html#Truth-and-Falsehood</a>
boolFromPerlBooleanCoercionRules :: PHPSessionValue -> Bool

-- | Alternative boolean coercion based on non-overloaded Python rules.
--   Values that return <a>False</a> are the empty array
--   <tt><i>[]</i></tt>, the empty string "", 0, <tt><i>NULL</i></tt> and
--   <tt><i>FALSE</i></tt>.
--   
--   PHP objects and objects implementing Serializable always return
--   <a>True</a>.
--   
--   Python's boolean conversion rules are described in "Truth Value
--   Testing" in section 3.1 of Python 2.5's Library Reference.
--   <a>https://docs.python.org/release/2.5.2/lib/truth.html</a>
boolFromPythonBooleanCoercionRules :: PHPSessionValue -> Bool

-- | Alternative boolean coercion based on Lua rules, all values are
--   <a>True</a> except <tt><i>NULL</i></tt> and <tt><i>FALSE</i></tt>.
--   
--   For Lua's conversion rules, refer to the passage in section 2.4.4
--   "Control Structures" of Lua 5.1's Manual.
--   <a>http://www.lua.org/manual/5.1/manual.html</a>
boolFromLuaBooleanCoercionRules :: PHPSessionValue -> Bool


-- | Non-coerced translation between <a>PHPSessionValue</a> and various
--   Haskell types. <a>convTo</a> provide convenient translation from
--   native types to <a>PHPSessionValue</a>, while translation from
--   <a>PHPSessionValue</a> to native types is provided through
--   <a>convFrom</a> and <a>convFromSafe</a>.
module Data.PHPSession.Conv

-- | <a>convTo</a> is a convenience function that converts natively typed
--   values to <a>PHPSessionValue</a>, with the resulting PHP type
--   determined by the type cast or inferred.
--   
--   <pre>
--   arrayOfPHPStrings :: PHPSessionValue
--   arrayOfPHPStrings =
--     let str1 = "Hello" :: BS.ByteString
--         str2 = "World"
--      in convTo [(0 :: Int, str1), (1, str2)]
--   </pre>
--   
--   In the above example code, the <tt>OverloadedStrings</tt> language
--   extension is assumed.
convTo :: ConversionToPHPValue a => a -> PHPSessionValue

-- | <a>convFrom</a> and <a>convFromSafe</a> are convenience functions that
--   translate PHP values stored as <a>PHPSessionValue</a> into appropriate
--   Haskell types depending on the desired type cast or inferred.
--   Functions provided in this module provide non-coerced type
--   translations and so will either carry on the translation or signal the
--   fact that the attempted conversion will alter the type of the value.
--   For situations where altering value types is expected, alternative
--   conversion functions with similar type signatures are provided in
--   modules within <i>Data.PHPSession.ImplicitConv</i>.
--   
--   The example arrayOfPHPStrings definition given in <a>convTo</a> can be
--   reverted back to Haskell types, which evaluates to
--   <tt>[(0,"Hello"),(1,"World")]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; convFrom arrayOfPHPStrings :: [(Int,LBS.ByteString)]
--   [(0,"Hello"),(1,"World")]
--   </pre>
--   
--   However, if the desired type signature is changed to a completely
--   different type, then a runtime exception is thrown:
--   
--   <pre>
--   &gt;&gt;&gt; convFrom arrayOfPHPStrings :: [(Int,Int)]
--   *** Exception: Type mismatch converting from (PHPSessionValueString "Hello") to Int
--   </pre>
--   
--   Where there is the possibility that the value being sought may be
--   <tt><i>NULL</i></tt>, the type should be <tt>(<a>Maybe</a> a)</tt>.
convFrom :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> b

-- | A version of <a>convFrom</a> which returns a <a>Left</a> with an error
--   message instead of throwing an exception.
convFromSafe :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> Either String b
class ConversionToPHPValue a
convTo' :: ConversionToPHPValue a => a -> PHPSessionValue
class ConversionFromPHPValueOrMismatch b
convFromOM :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> Either String b
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch [(Data.PHPSession.Types.PHPSessionValue, Data.PHPSession.Types.PHPSessionValue)]
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch a => Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch [(a, Data.PHPSession.Types.PHPSessionValue)]
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch b => Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch [(Data.PHPSession.Types.PHPSessionValue, b)]
instance (Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch a, Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch b) => Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch [(a, b)]
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch GHC.Types.Bool
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch GHC.Types.Double
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch GHC.Types.Int
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch GHC.Int.Int32
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch GHC.Int.Int64
instance GHC.Real.Integral n => Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (Data.Either.Either n GHC.Types.Double)
instance GHC.Real.Integral n => Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (Data.Either.Either n Data.ByteString.Lazy.Internal.ByteString)
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (Data.Either.Either GHC.Types.Double Data.ByteString.Lazy.Internal.ByteString)
instance GHC.Real.Integral n => Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (Data.Either.Either n Data.ByteString.Internal.ByteString)
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (Data.Either.Either GHC.Types.Double Data.ByteString.Internal.ByteString)
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (Data.PHPSession.Types.PHPSessionClassName, [(Data.PHPSession.Types.PHPSessionValue, Data.PHPSession.Types.PHPSessionValue)])
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (Data.PHPSession.Types.PHPSessionClassName, Data.ByteString.Lazy.Internal.ByteString)
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch Data.ByteString.Lazy.Internal.ByteString
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch Data.ByteString.Internal.ByteString
instance Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch a => Data.PHPSession.Conv.ConversionFromPHPValueOrMismatch (GHC.Maybe.Maybe a)
instance Data.PHPSession.Conv.ConversionToPHPValue Data.PHPSession.Types.PHPSessionValue
instance Data.PHPSession.Conv.ConversionToPHPValue [(Data.PHPSession.Types.PHPSessionValue, Data.PHPSession.Types.PHPSessionValue)]
instance (Data.PHPSession.Conv.ConversionToPHPValue a, Data.PHPSession.Conv.ConversionToPHPValue b) => Data.PHPSession.Conv.ConversionToPHPValue [(a, b)]
instance Data.PHPSession.Conv.ConversionToPHPValue GHC.Types.Bool
instance Data.PHPSession.Conv.ConversionToPHPValue GHC.Types.Double
instance Data.PHPSession.Conv.ConversionToPHPValue GHC.Types.Int
instance Data.PHPSession.Conv.ConversionToPHPValue GHC.Int.Int32
instance Data.PHPSession.Conv.ConversionToPHPValue GHC.Int.Int64
instance Data.PHPSession.Conv.ConversionToPHPValue a => Data.PHPSession.Conv.ConversionToPHPValue (GHC.Maybe.Maybe a)
instance Data.PHPSession.Conv.ConversionToPHPValue (Data.PHPSession.Types.PHPSessionClassName, [(Data.PHPSession.Types.PHPSessionValue, Data.PHPSession.Types.PHPSessionValue)])
instance Data.PHPSession.Conv.ConversionToPHPValue (Data.PHPSession.Types.PHPSessionClassName, Data.ByteString.Lazy.Internal.ByteString)
instance Data.PHPSession.Conv.ConversionToPHPValue Data.ByteString.Lazy.Internal.ByteString
instance Data.PHPSession.Conv.ConversionToPHPValue Data.ByteString.Internal.ByteString


-- | Functions for performing conversion from <a>PHPSessionValue</a>
--   objects to Haskell types while using a subset of the implicit PHP type
--   coercion behaviour. Some of the differences from the implicit type
--   conversion found in PHP are noted:
--   
--   <ul>
--   <li>Conversions that are documented as undefined behaviour in the PHP
--   manual will throw definite exceptions with these functions.</li>
--   <li>A significant difference from PHP's conversion rules is that
--   <tt><i>NULL</i></tt> cannot be directly converted to any data type
--   except to <a>Bool</a>, otherwise <tt><i>NULL</i></tt> has to be
--   handled by using the type <tt><a>Maybe</a> a</tt> to capture nullable
--   values.</li>
--   <li>Objects that implement Serializable are not convertible to any
--   other type at all as their value systems are not directly
--   interpretable in a meaningful manner.</li>
--   <li>Numbers can be converted to strings, but only strings that satisfy
--   <tt>reads str = [(value, "")]</tt> can be converted back to
--   numbers.</li>
--   <li>Arrays and objects to string conversions which would normally be
--   coerced to the simple strings "Array" and "Object" in PHP, are simply
--   considered errors with these conversion functions.</li>
--   </ul>
module Data.PHPSession.ImplicitConv.PHPTypeCoercion

-- | <a>convFromPHPImplicit</a> and <a>convFromPHPImplicitSafe</a> are
--   functions that convert values stored as <a>PHPSessionValue</a> into
--   appropriate Haskell types depending on the desired type cast or
--   inferred. Unlike the <a>convFrom</a> and <a>convFromSafe</a> functions
--   provided in <a>Data.PHPSession.Conv</a>, functions provided in this
--   module perform type coercion based on a significant number of
--   conversion rules to satisfy the type cast or inferred.
--   
--   The example <tt>arrayOfPHPStrings</tt> definition given in the example
--   documented in <a>Data.PHPSession.Conv</a> can be evaluated to
--   <tt>[(0,"Hello"),(1,"World")]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; convFromPHPImplicit arrayOfPHPStrings :: [(Int,LBS.ByteString)]
--   [(0,"Hello"),(1,"World")]
--   </pre>
--   
--   However, if the desired type signature is changed:
--   
--   <pre>
--   &gt;&gt;&gt; convFromPHPImplicit arrayOfPHPStrings :: [(LBS.ByteString,LBS.ByteString)]
--   [("0","Hello"),("1","World")]
--   </pre>
--   
--   Where there is the possibility that the value being sought may be
--   <tt><i>NULL</i></tt>, the type should be <tt>(<a>Maybe</a> a)</tt>.
convFromPHPImplicit :: ConversionFromPHPImplicitValueOrMismatch b => PHPSessionValue -> b

-- | <a>convFromPHPImplicitSafe</a> is a version of
--   <a>convFromPHPImplicit</a> that returns a <a>Left</a> with an error
--   message instead of throwing a run time exception.
convFromPHPImplicitSafe :: ConversionFromPHPImplicitValueOrMismatch b => PHPSessionValue -> Either String b
class ConversionFromPHPImplicitValueOrMismatch b
convFromPHPImplicitOM :: ConversionFromPHPImplicitValueOrMismatch b => PHPSessionValue -> Either String b
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch [(Data.PHPSession.Types.PHPSessionValue, Data.PHPSession.Types.PHPSessionValue)]
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch b => Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch [(Data.PHPSession.Types.PHPSessionValue, b)]
instance (Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch a, Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch b) => Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch [(a, b)]
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch GHC.Types.Bool
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch GHC.Types.Double
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch GHC.Types.Int
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch GHC.Int.Int32
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch GHC.Int.Int64
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch (Data.PHPSession.Types.PHPSessionClassName, [(Data.PHPSession.Types.PHPSessionValue, Data.PHPSession.Types.PHPSessionValue)])
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch (Data.PHPSession.Types.PHPSessionClassName, Data.ByteString.Lazy.Internal.ByteString)
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch Data.ByteString.Lazy.Internal.ByteString
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch Data.ByteString.Internal.ByteString
instance Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch a => Data.PHPSession.ImplicitConv.PHPTypeCoercion.ConversionFromPHPImplicitValueOrMismatch (GHC.Maybe.Maybe a)


-- | Encodes and decodes serialized PHP sessions in the format used by the
--   "php" setting for session.serialize_handler, as well as encodes and
--   decodes PHP values in general in the format used by PHP's
--   serialize/unserialize.
--   
--   An example of using <a>decodePHPSessionValue</a> and <a>convFrom</a>
--   to decode and convert values from the serialized contents of a
--   <a>ByteString</a> to <tt>[(<a>Int</a>,<a>ByteString</a>)]</tt>:
--   
--   <pre>
--   import qualified Data.PHPSession as PHPSess
--   
--   getArrayValues :: LBS.ByteString -&gt; [(Int, LBS.ByteString)]
--   getArrayValues encoded =
--     case PHPSess.decodePHPSessionValue encoded of
--       Nothing -&gt; [] :: [(Int,LBS.ByteString)]
--       Just b -&gt; PHPSess.convFrom b
--   </pre>
--   
--   Starting from a value output from the following PHP code:
--   
--   <tt><i>&lt;?php</i> <i>echo</i> <i>serialize</i>(<i>array</i>(0 =&gt;
--   'Hello', 5 =&gt; 'World'));</tt> <tt>/* Outputs:
--   "a:2:{i:0;s:5:\"Hello\";i:5;s:5:\"World\";}" */</tt>
--   
--   The following can be computed:
--   
--   <pre>
--   &gt;&gt;&gt; getArrayValues $ LBS.pack "a:2:{i:0;s:5:\"Hello\";i:5;s:5:\"World\";}"
--   [(0,"Hello"),(5,"World")]
--   </pre>
module Data.PHPSession

-- | Decodes a <a>ByteString</a> containing a serialization of a list of
--   session variables using the "php" session serialization format into a
--   <a>PHPSessionVariableList</a>
decodePHPSession :: ByteString -> Maybe PHPSessionVariableList

-- | A version of <a>decodePHPSession</a> that returns a
--   <a>PHPSessionDecodingError</a> when decoding the <a>ByteString</a>
--   fails.
decodePHPSessionEither :: ByteString -> Either PHPSessionDecodingError PHPSessionVariableList

-- | Decodes a <a>ByteString</a> containing a session serialization of a
--   value into a <a>PHPSessionValue</a>. The format being decoded is
--   similar if not probably the same format used by PHP's
--   serialize/unserialize functions. <a>Nothing</a> is returned if the
--   input bytestring could not be parsed correctly.
decodePHPSessionValue :: ByteString -> Maybe PHPSessionValue

-- | A version of <a>decodePHPSessionValue</a> that returns
--   <a>PHPSessionDecodingError</a> when decoding the <a>ByteString</a>
--   fails.
decodePHPSessionValueEither :: ByteString -> Either PHPSessionDecodingError PHPSessionValue

-- | Encode a <a>PHPSessionVariableList</a> into a <a>ByteString</a>
--   containing the serialization of a list of session variables using the
--   "php" session serialization format.
encodePHPSession :: PHPSessionVariableList -> ByteString

-- | Encode a <a>PHPSessionValue</a> into a <a>ByteString</a> containing
--   the serialization of a PHP value. The format being encoded into is
--   similar if not probably the same format used by PHP's
--   serialize/unserialize functions.
encodePHPSessionValue :: PHPSessionValue -> ByteString

-- | <a>convTo</a> is a convenience function that converts natively typed
--   values to <a>PHPSessionValue</a>, with the resulting PHP type
--   determined by the type cast or inferred.
--   
--   <pre>
--   arrayOfPHPStrings :: PHPSessionValue
--   arrayOfPHPStrings =
--     let str1 = "Hello" :: BS.ByteString
--         str2 = "World"
--      in convTo [(0 :: Int, str1), (1, str2)]
--   </pre>
--   
--   In the above example code, the <tt>OverloadedStrings</tt> language
--   extension is assumed.
convTo :: ConversionToPHPValue a => a -> PHPSessionValue

-- | <a>convFrom</a> and <a>convFromSafe</a> are convenience functions that
--   translate PHP values stored as <a>PHPSessionValue</a> into appropriate
--   Haskell types depending on the desired type cast or inferred.
--   Functions provided in this module provide non-coerced type
--   translations and so will either carry on the translation or signal the
--   fact that the attempted conversion will alter the type of the value.
--   For situations where altering value types is expected, alternative
--   conversion functions with similar type signatures are provided in
--   modules within <i>Data.PHPSession.ImplicitConv</i>.
--   
--   The example arrayOfPHPStrings definition given in <a>convTo</a> can be
--   reverted back to Haskell types, which evaluates to
--   <tt>[(0,"Hello"),(1,"World")]</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; convFrom arrayOfPHPStrings :: [(Int,LBS.ByteString)]
--   [(0,"Hello"),(1,"World")]
--   </pre>
--   
--   However, if the desired type signature is changed to a completely
--   different type, then a runtime exception is thrown:
--   
--   <pre>
--   &gt;&gt;&gt; convFrom arrayOfPHPStrings :: [(Int,Int)]
--   *** Exception: Type mismatch converting from (PHPSessionValueString "Hello") to Int
--   </pre>
--   
--   Where there is the possibility that the value being sought may be
--   <tt><i>NULL</i></tt>, the type should be <tt>(<a>Maybe</a> a)</tt>.
convFrom :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> b

-- | A version of <a>convFrom</a> which returns a <a>Left</a> with an error
--   message instead of throwing an exception.
convFromSafe :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> Either String b

-- | Decodes as much of a <a>ByteString</a> as needed into a
--   <a>PHPSessionValue</a> and returns the rest of the string. Decoding
--   ends at either the end of the string or when the extent of the current
--   nested structure is met when an extra closing curly brace is
--   encountered. The format being decoded is similar if not probably the
--   same format used by PHP's serialize/unserialize functions.
--   <a>Nothing</a> is returned if the input bytestring could not be parsed
--   correctly.
decodePartialPHPSessionValue :: ByteString -> Maybe (PHPSessionValue, ByteString)

-- | A version of <a>decodePartialPHPSessionValue</a> that uses Either, on
--   decoding error a <a>PHPSessionDecodingError</a> is returned.
decodePartialPHPSessionValueEither :: ByteString -> Either PHPSessionDecodingError (PHPSessionValue, ByteString)

-- | Holds the "top-level" session variables and their value contents.
type PHPSessionVariableList = [(ByteString, PHPSessionValue)]

-- | Represents the name of a PHP class.
data PHPSessionClassName
PHPSessionClassName :: ByteString -> PHPSessionClassName

-- | <a>PHPSessionValue</a> Represents a PHP value, which may be a number,
--   string, array, object, boolean, null, or references.
--   
--   <ul>
--   <li><a>PHPSessionValueArray</a> represents an array as a list of
--   key-value pairs of values of type <a>PHPSessionValue</a>.</li>
--   <li><a>PHPSessionValueObject</a> is similar to
--   <a>PHPSessionValueArray</a> but also includes a class name of type
--   <a>PHPSessionClassName</a>.</li>
--   <li><a>PHPSessionValueObjectSerializeable</a> represent objects of
--   which their classes implement Serializeable to handle their own
--   serialization and don't use the normal serialization format for its
--   contained objects.</li>
--   <li><a>PHPSessionValueBool</a>, <a>PHPSessionValueInt</a>,
--   <a>PHPSessionValueFloat</a>, <a>PHPSessionValueNull</a>, and
--   <a>PHPSessionValueString</a> represent basic types boolean, integer,
--   floats, null and string respectively.</li>
--   <li><a>PHPSessionValueFloat</a> stores the number representation as an
--   <a>Either</a> <a>Int</a> <a>Double</a> to preserve instances where the
--   number representation is actually an integer. It should be noted that
--   the re-encoded value is usually rounded unlike PHP's
--   representation.</li>
--   <li><a>PHPSessionValueMisc</a> stores a few other types such as
--   references and values which follow the general serialization format
--   but aren't recognized by the decoder. A list of <a>PHPSessionAttr</a>
--   provides the information for reconstructing the serialized
--   representation when re-encoding this type of value.</li>
--   </ul>
data PHPSessionValue
PHPSessionValueArray :: [(PHPSessionValue, PHPSessionValue)] -> PHPSessionValue
PHPSessionValueBool :: Bool -> PHPSessionValue
PHPSessionValueFloat :: Either Int Double -> PHPSessionValue
PHPSessionValueInt :: Int -> PHPSessionValue
PHPSessionValueNull :: PHPSessionValue
PHPSessionValueObject :: PHPSessionClassName -> [(PHPSessionValue, PHPSessionValue)] -> PHPSessionValue
PHPSessionValueObjectSerializeable :: PHPSessionClassName -> ByteString -> PHPSessionValue
PHPSessionValueString :: ByteString -> PHPSessionValue
PHPSessionValueMisc :: ByteString -> [PHPSessionAttr] -> PHPSessionValue

-- | <a>PHPSessionAttr</a> are values associated with
--   <a>PHPSessionValueMisc</a> to inspect and generally re-encode the
--   necessary information for that value.
data PHPSessionAttr
PHPSessionAttrInt :: Int -> PHPSessionAttr
PHPSessionAttrFloat :: Double -> PHPSessionAttr
PHPSessionAttrNested :: [PHPSessionValue] -> PHPSessionAttr
