-- 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
-- | PHPSessionValue Represents a PHP value, which may be a number,
-- string, array, object, boolean, null, or references.
--
--
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
-- | PHPSessionAttr are values associated with
-- PHPSessionValueMisc to inspect and generally re-encode the
-- necessary information for that value.
data PHPSessionAttr
PHPSessionAttrInt :: Int -> PHPSessionAttr
PHPSessionAttrFloat :: Double -> PHPSessionAttr
PHPSessionAttrNested :: [PHPSessionValue] -> PHPSessionAttr
-- | PHPSessionDecodingError are error types that can be returned if
-- decoding did not succeed. They are returned by the Either
-- versions of the decoding functions.
--
--
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
-- | Non-coerced translation between PHPSessionValue and various
-- Haskell types. convTo provide convenient translation from
-- native types to PHPSessionValue, while translation from
-- PHPSessionValue to native types is provided through
-- convFrom and convFromSafe.
module Data.PHPSession.Conv
-- | convTo is a convenience function that converts natively typed
-- values to PHPSessionValue, with the resulting PHP type
-- determined by the type cast or inferred.
--
--
-- arrayOfPHPStrings :: PHPSessionValue
-- arrayOfPHPStrings =
-- let str1 = "Hello" :: BS.ByteString
-- str2 = "World"
-- in convTo [(0 :: Int, str1), (1, str2)]
--
--
-- In the above example code, the OverloadedStrings language
-- extension is assumed.
convTo :: ConversionToPHPValue a => a -> PHPSessionValue
-- | convFrom and convFromSafe are convenience functions that
-- translate PHP values stored as PHPSessionValue 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 Data.PHPSession.ImplicitConv.
--
-- The example arrayOfPHPStrings definition given in convTo can be
-- reverted back to Haskell types, which evaluates to
-- [(0,"Hello"),(1,"World")].
--
--
-- >>> convFrom arrayOfPHPStrings :: [(Int,LBS.ByteString)]
-- [(0,"Hello"),(1,"World")]
--
--
-- However, if the desired type signature is changed to a completely
-- different type, then a runtime exception is thrown:
--
--
-- >>> convFrom arrayOfPHPStrings :: [(Int,Int)]
-- *** Exception: Type mismatch converting from (PHPSessionValueString "Hello") to Int
--
--
-- Where there is the possibility that the value being sought may be
-- NULL, the type should be (Maybe a).
convFrom :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> b
-- | A version of convFrom which returns a Left 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 ConversionFromPHPValueOrMismatch a => ConversionFromPHPValueOrMismatch (Maybe a)
instance ConversionFromPHPValueOrMismatch ByteString
instance ConversionFromPHPValueOrMismatch ByteString
instance ConversionFromPHPValueOrMismatch (PHPSessionClassName, ByteString)
instance ConversionFromPHPValueOrMismatch (PHPSessionClassName, [(PHPSessionValue, PHPSessionValue)])
instance ConversionFromPHPValueOrMismatch (Either Double ByteString)
instance Integral n => ConversionFromPHPValueOrMismatch (Either n ByteString)
instance ConversionFromPHPValueOrMismatch (Either Double ByteString)
instance Integral n => ConversionFromPHPValueOrMismatch (Either n ByteString)
instance Integral n => ConversionFromPHPValueOrMismatch (Either n Double)
instance ConversionFromPHPValueOrMismatch Int64
instance ConversionFromPHPValueOrMismatch Int32
instance ConversionFromPHPValueOrMismatch Int
instance ConversionFromPHPValueOrMismatch Double
instance ConversionFromPHPValueOrMismatch Bool
instance (ConversionFromPHPValueOrMismatch a, ConversionFromPHPValueOrMismatch b) => ConversionFromPHPValueOrMismatch [(a, b)]
instance ConversionFromPHPValueOrMismatch b => ConversionFromPHPValueOrMismatch [(PHPSessionValue, b)]
instance ConversionFromPHPValueOrMismatch a => ConversionFromPHPValueOrMismatch [(a, PHPSessionValue)]
instance ConversionFromPHPValueOrMismatch [(PHPSessionValue, PHPSessionValue)]
instance ConversionToPHPValue ByteString
instance ConversionToPHPValue ByteString
instance ConversionToPHPValue (PHPSessionClassName, ByteString)
instance ConversionToPHPValue (PHPSessionClassName, [(PHPSessionValue, PHPSessionValue)])
instance ConversionToPHPValue a => ConversionToPHPValue (Maybe a)
instance ConversionToPHPValue Int64
instance ConversionToPHPValue Int32
instance ConversionToPHPValue Int
instance ConversionToPHPValue Double
instance ConversionToPHPValue Bool
instance (ConversionToPHPValue a, ConversionToPHPValue b) => ConversionToPHPValue [(a, b)]
instance ConversionToPHPValue [(PHPSessionValue, PHPSessionValue)]
instance ConversionToPHPValue PHPSessionValue
-- | Non-coerced and coerced rule sets for converting
-- PHPSessionValue objects to Bool.
module Data.PHPSession.ImplicitConv.ConvBool
-- | Returns the value of a boolean value as a Bool, or returns
-- False as the default Bool value if the PHPSessionValue
-- is not a boolean type. This function is similar to the "strict
-- comparison" operator against the boolean TRUE value.
boolDefaultFalseFrom :: PHPSessionValue -> Bool
-- | Returns the value of a boolean value as a Bool, or returns True
-- as the default Bool value if the PHPSessionValue is not
-- a boolean type.
boolDefaultTrueFrom :: PHPSessionValue -> Bool
-- | Coerces a PHPSessionValue to a Bool 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 TRUE.
-- http://php.net/manual/language.types.boolean.php
--
-- Values that result in True are TRUE, non-zero
-- numbers, non-empty strings other than "0", objects, and non-empty
-- arrays.
--
-- A conversion documented in the PHP manual involving SimpleXML
-- objects that coerce to FALSE instead of
-- TRUE 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. boolFromReducedLooseCoercionSafe 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 boolFromPHPLooseComparisonWithTrue where
-- NULL returns Nothing and all other inputs
-- returns Just with the boolean result.
boolFromPHPLooseComparisonWithTrueNullable :: PHPSessionValue -> Maybe Bool
-- | Coerces a PHPSessionValue to a Bool through a reduced
-- subset of valid values. boolFromReducedLooseCoercionSafe and
-- boolFromReducedLooseCoercion are functions intended for testing
-- a variable for a boolean "confirmation" from a limited number of
-- probable representations.
--
-- Values that result in True are TRUE, non-zero
-- numbers, "1" and "-1".
--
-- Values that result in False are FALSE, zero
-- numbers, NULL, "0" and "".
--
-- Values such as arrays, objects and arbitrary strings, are invalid with
-- this function and return an error. In the case of
-- boolFromReducedLooseCoercionSafe this returns a Left
-- with the error message.
boolFromReducedLooseCoercionSafe :: PHPSessionValue -> Either String Bool
-- | A version of boolFromReducedLooseCoercionSafe that may throw
-- exceptions.
boolFromReducedLooseCoercion :: PHPSessionValue -> Bool
-- | A version of boolFromReducedLooseCoercionSafe where
-- NULL returns Right Nothing and all other
-- inputs returns Right Just with the boolean result. May
-- return Left with an error message if given invalid values.
boolFromReducedLooseCoercionNullableSafe :: PHPSessionValue -> Either String (Maybe Bool)
-- | A version of boolFromReducedLooseCoercion where
-- NULL returns Nothing and all other inputs
-- returns Just 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 False instead of True. Values that
-- return False are NAN, 0, the empty string "",
-- NULL and FALSE
--
-- PHP objects, arrays and objects implementing Serializable always
-- return True.
--
-- 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 False are the empty string "", the string
-- containing "0", 0, NULL and FALSE.
--
-- PHP objects, arrays and objects implementing Serializable always
-- return True.
--
-- Perl's boolean coercion rules are described in the section "Truth and
-- Falsehood" of "perlsyn".
-- http://perldoc.perl.org/perlsyn.html#Truth-and-Falsehood
boolFromPerlBooleanCoercionRules :: PHPSessionValue -> Bool
-- | Alternative boolean coercion based on non-overloaded Python rules.
-- Values that return False are the empty array
-- [], the empty string "", 0, NULL and
-- FALSE.
--
-- PHP objects and objects implementing Serializable always return
-- True.
--
-- Python's boolean conversion rules are described in "Truth Value
-- Testing" in section 3.1 of Python 2.5's Library Reference.
-- https://docs.python.org/release/2.5.2/lib/truth.html
boolFromPythonBooleanCoercionRules :: PHPSessionValue -> Bool
-- | Alternative boolean coercion based on Lua rules, all values are
-- True except NULL and FALSE.
--
-- For Lua's conversion rules, refer to the passage in section 2.4.4
-- "Control Structures" of Lua 5.1's Manual.
-- http://www.lua.org/manual/5.1/manual.html
boolFromLuaBooleanCoercionRules :: PHPSessionValue -> Bool
-- | Functions for performing conversion from PHPSessionValue
-- 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:
--
--
-- - Conversions that are documented as undefined behaviour in the PHP
-- manual will throw definite exceptions with these functions.
-- - A significant difference from PHP's conversion rules is that
-- NULL cannot be directly converted to any data type
-- except to Bool, otherwise NULL has to be
-- handled by using the type Maybe a to capture nullable
-- values.
-- - 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.
-- - Numbers can be converted to strings, but only strings that satisfy
-- reads str = [(value, "")] can be converted back to
-- numbers.
-- - 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.
--
module Data.PHPSession.ImplicitConv.PHPTypeCoercion
-- | convFromPHPImplicit and convFromPHPImplicitSafe are
-- functions that convert values stored as PHPSessionValue into
-- appropriate Haskell types depending on the desired type cast or
-- inferred. Unlike the convFrom and convFromSafe functions
-- provided in Data.PHPSession.Conv, 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 arrayOfPHPStrings definition given in the example
-- documented in Data.PHPSession.Conv can be evaluated to
-- [(0,"Hello"),(1,"World")].
--
--
-- >>> convFromPHPImplicit arrayOfPHPStrings :: [(Int,LBS.ByteString)]
-- [(0,"Hello"),(1,"World")]
--
--
-- However, if the desired type signature is changed:
--
--
-- >>> convFromPHPImplicit arrayOfPHPStrings :: [(LBS.ByteString,LBS.ByteString)]
-- [("0","Hello"),("1","World")]
--
--
-- Where there is the possibility that the value being sought may be
-- NULL, the type should be (Maybe a).
convFromPHPImplicit :: ConversionFromPHPImplicitValueOrMismatch b => PHPSessionValue -> b
-- | convFromPHPImplicitSafe is a version of
-- convFromPHPImplicit that returns a Left 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 ConversionFromPHPImplicitValueOrMismatch a => ConversionFromPHPImplicitValueOrMismatch (Maybe a)
instance ConversionFromPHPImplicitValueOrMismatch ByteString
instance ConversionFromPHPImplicitValueOrMismatch ByteString
instance ConversionFromPHPImplicitValueOrMismatch (PHPSessionClassName, ByteString)
instance ConversionFromPHPImplicitValueOrMismatch (PHPSessionClassName, [(PHPSessionValue, PHPSessionValue)])
instance ConversionFromPHPImplicitValueOrMismatch Int64
instance ConversionFromPHPImplicitValueOrMismatch Int32
instance ConversionFromPHPImplicitValueOrMismatch Int
instance ConversionFromPHPImplicitValueOrMismatch Double
instance ConversionFromPHPImplicitValueOrMismatch Bool
instance (ConversionFromPHPImplicitValueOrMismatch a, ConversionFromPHPImplicitValueOrMismatch b) => ConversionFromPHPImplicitValueOrMismatch [(a, b)]
instance ConversionFromPHPImplicitValueOrMismatch b => ConversionFromPHPImplicitValueOrMismatch [(PHPSessionValue, b)]
instance ConversionFromPHPImplicitValueOrMismatch [(PHPSessionValue, PHPSessionValue)]
-- | 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 decodePHPSessionValue and convFrom
-- to decode and convert values from the serialized contents of a
-- ByteString to [(Int,ByteString)]:
--
--
-- import qualified Data.PHPSession as PHPSess
--
-- getArrayValues :: LBS.ByteString -> [(Int, LBS.ByteString)]
-- getArrayValues encoded =
-- case PHPSess.decodePHPSessionValue encoded of
-- Nothing -> [] :: [(Int,LBS.ByteString)]
-- Just b -> PHPSess.convFrom b
--
--
-- Starting from a value output from the following PHP code:
--
-- <?php echo serialize(array(0 =>
-- 'Hello', 5 => 'World')); /* Outputs:
-- "a:2:{i:0;s:5:\"Hello\";i:5;s:5:\"World\";}" */
--
-- The following can be computed:
--
--
-- >>> getArrayValues $ LBS.pack "a:2:{i:0;s:5:\"Hello\";i:5;s:5:\"World\";}"
-- [(0,"Hello"),(5,"World")]
--
module Data.PHPSession
-- | Decodes a ByteString containing a serialization of a list of
-- session variables using the "php" session serialization format into a
-- PHPSessionVariableList
decodePHPSession :: ByteString -> Maybe PHPSessionVariableList
-- | A version of decodePHPSession that returns a
-- PHPSessionDecodingError when decoding the ByteString
-- fails.
decodePHPSessionEither :: ByteString -> Either PHPSessionDecodingError PHPSessionVariableList
-- | Decodes a ByteString containing a session serialization of a
-- value into a PHPSessionValue. The format being decoded is
-- similar if not probably the same format used by PHP's
-- serialize/unserialize functions. Nothing is returned if the
-- input bytestring could not be parsed correctly.
decodePHPSessionValue :: ByteString -> Maybe PHPSessionValue
-- | A version of decodePHPSessionValue that returns
-- PHPSessionDecodingError when decoding the ByteString
-- fails.
decodePHPSessionValueEither :: ByteString -> Either PHPSessionDecodingError PHPSessionValue
-- | Encode a PHPSessionVariableList into a ByteString
-- containing the serialization of a list of session variables using the
-- "php" session serialization format.
encodePHPSession :: PHPSessionVariableList -> ByteString
-- | Encode a PHPSessionValue into a ByteString 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
-- | convTo is a convenience function that converts natively typed
-- values to PHPSessionValue, with the resulting PHP type
-- determined by the type cast or inferred.
--
--
-- arrayOfPHPStrings :: PHPSessionValue
-- arrayOfPHPStrings =
-- let str1 = "Hello" :: BS.ByteString
-- str2 = "World"
-- in convTo [(0 :: Int, str1), (1, str2)]
--
--
-- In the above example code, the OverloadedStrings language
-- extension is assumed.
convTo :: ConversionToPHPValue a => a -> PHPSessionValue
-- | convFrom and convFromSafe are convenience functions that
-- translate PHP values stored as PHPSessionValue 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 Data.PHPSession.ImplicitConv.
--
-- The example arrayOfPHPStrings definition given in convTo can be
-- reverted back to Haskell types, which evaluates to
-- [(0,"Hello"),(1,"World")].
--
--
-- >>> convFrom arrayOfPHPStrings :: [(Int,LBS.ByteString)]
-- [(0,"Hello"),(1,"World")]
--
--
-- However, if the desired type signature is changed to a completely
-- different type, then a runtime exception is thrown:
--
--
-- >>> convFrom arrayOfPHPStrings :: [(Int,Int)]
-- *** Exception: Type mismatch converting from (PHPSessionValueString "Hello") to Int
--
--
-- Where there is the possibility that the value being sought may be
-- NULL, the type should be (Maybe a).
convFrom :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> b
-- | A version of convFrom which returns a Left with an error
-- message instead of throwing an exception.
convFromSafe :: ConversionFromPHPValueOrMismatch b => PHPSessionValue -> Either String b
-- | Decodes as much of a ByteString as needed into a
-- PHPSessionValue 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.
-- Nothing is returned if the input bytestring could not be parsed
-- correctly.
decodePartialPHPSessionValue :: ByteString -> Maybe (PHPSessionValue, ByteString)
-- | A version of decodePartialPHPSessionValue that uses Either, on
-- decoding error a PHPSessionDecodingError 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
-- | PHPSessionValue Represents a PHP value, which may be a number,
-- string, array, object, boolean, null, or references.
--
--
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
-- | PHPSessionAttr are values associated with
-- PHPSessionValueMisc to inspect and generally re-encode the
-- necessary information for that value.
data PHPSessionAttr
PHPSessionAttrInt :: Int -> PHPSessionAttr
PHPSessionAttrFloat :: Double -> PHPSessionAttr
PHPSessionAttrNested :: [PHPSessionValue] -> PHPSessionAttr