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


-- | PHP session and values serialization
--   
@package hs-php-session
@version 0.0.9.2


-- | 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 Eq PHPSessionDecodingError
instance Show PHPSessionDecodingError
instance Eq PHPSessionAttr
instance Show PHPSessionAttr
instance Ord PHPSessionValue
instance Eq PHPSessionValue
instance Show PHPSessionValue
instance Eq PHPSessionClassName
instance Show PHPSessionClassName


-- | Encodes and decodes serialized PHP sessions in the format used by the
--   "php" setting for session.serialize_handler.
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

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