-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Declarative routing for Snap. -- -- Provides the definition of a predicate type-class together with -- several concrete implementations which are used to constrain the set -- of possible Snap handlers in a type-safe way. @package snap-predicates @version 0.2.0 module Snap.Predicates.Tutorial module Snap.Predicates.MediaTypes -- | Type-class for converting a ByteString to a media-type. class (Show a, Eq a) => MType a toType :: MType a => a -> ByteString -> Maybe a -- | Type-class for converting a ByteString to a media-subtype. class (Show a, Eq a) => MSubType a toSubType :: MSubType a => a -> ByteString -> Maybe a -- | The Media-type representation. data MediaType t s MediaType :: !t -> !s -> !Double -> ![(ByteString, ByteString)] -> MediaType t s _type :: MediaType t s -> !t _subtype :: MediaType t s -> !s _quality :: MediaType t s -> !Double _params :: MediaType t s -> ![(ByteString, ByteString)] -- | Generic media-type. data Type Type :: ByteString -> Type -- | media-type and sub-type "*". data All All :: All data Application Application :: Application data Audio Audio :: Audio data Image Image :: Image data Message Message :: Message data Multipart Multipart :: Multipart data Text Text :: Text data Video Video :: Video -- | Generic media-subtype. data SubType SubType :: ByteString -> SubType data AtomXml AtomXml :: AtomXml data Css Css :: Css data Csv Csv :: Csv data Encrypted Encrypted :: Encrypted data FormData FormData :: FormData data Gif Gif :: Gif data Gzip Gzip :: Gzip data Javascript Javascript :: Javascript data Jpeg Jpeg :: Jpeg data Json Json :: Json data Mixed Mixed :: Mixed data Mp4 Mp4 :: Mp4 data Mpeg Mpeg :: Mpeg data OctetStream OctetStream :: OctetStream data Ogg Ogg :: Ogg data Partial Partial :: Partial data Plain Plain :: Plain data Png Png :: Png data Postscript Postscript :: Postscript data Protobuf Protobuf :: Protobuf data RdfXml RdfXml :: RdfXml data RssXml RssXml :: RssXml data Tar Tar :: Tar data Tiff Tiff :: Tiff data Thrift Thrift :: Thrift data Vorbis Vorbis :: Vorbis data Webm Webm :: Webm data XhtmlXml XhtmlXml :: XhtmlXml data Xml Xml :: Xml instance (Eq t, Eq s) => Eq (MediaType t s) instance (Show t, Show s) => Show (MediaType t s) instance Eq Type instance Eq Application instance Eq Audio instance Eq Image instance Eq Message instance Eq Multipart instance Eq Text instance Eq Video instance Eq SubType instance Eq AtomXml instance Eq Css instance Eq Csv instance Eq Encrypted instance Eq FormData instance Eq Gif instance Eq Gzip instance Eq Javascript instance Eq Jpeg instance Eq Json instance Eq Mixed instance Eq Mp4 instance Eq Mpeg instance Eq OctetStream instance Eq Ogg instance Eq Partial instance Eq Plain instance Eq Png instance Eq Postscript instance Eq Protobuf instance Eq RdfXml instance Eq RssXml instance Eq Tar instance Eq Tiff instance Eq Thrift instance Eq Vorbis instance Eq Webm instance Eq XhtmlXml instance Eq Xml instance Eq All instance Show All instance MSubType All instance MType All instance Show Xml instance MSubType Xml instance Show XhtmlXml instance MSubType XhtmlXml instance Show Webm instance MSubType Webm instance Show Vorbis instance MSubType Vorbis instance Show Thrift instance MSubType Thrift instance Show Tiff instance MSubType Tiff instance Show Tar instance MSubType Tar instance Show RssXml instance MSubType RssXml instance Show RdfXml instance MSubType RdfXml instance Show Protobuf instance MSubType Protobuf instance Show Postscript instance MSubType Postscript instance Show Png instance MSubType Png instance Show Plain instance MSubType Plain instance Show Partial instance MSubType Partial instance Show Ogg instance MSubType Ogg instance Show OctetStream instance MSubType OctetStream instance Show Mpeg instance MSubType Mpeg instance Show Mp4 instance MSubType Mp4 instance Show Mixed instance MSubType Mixed instance Show Json instance MSubType Json instance Show Jpeg instance MSubType Jpeg instance Show Javascript instance MSubType Javascript instance Show Gzip instance MSubType Gzip instance Show Gif instance MSubType Gif instance Show FormData instance MSubType FormData instance Show Encrypted instance MSubType Encrypted instance Show Csv instance MSubType Csv instance Show Css instance MSubType Css instance Show AtomXml instance MSubType AtomXml instance Show SubType instance MSubType SubType instance Show Video instance MType Video instance Show Text instance MType Text instance Show Multipart instance MType Multipart instance Show Message instance MType Message instance Show Image instance MType Image instance Show Audio instance MType Audio instance Show Application instance MType Application instance Show Type instance MType Type module Snap.Predicates.Error -- | The error type used as F meta-data in all snap predicates. data Error Error :: !Word -> !(Maybe ByteString) -> Error -- | (HTTP) status code _status :: Error -> !Word -- | optional status message _message :: Error -> !(Maybe ByteString) -- | Convenience function to construct Error values from status code -- and status message. err :: Word -> ByteString -> Error instance Eq Error instance Show Error module Data.Predicate.Env -- | An environment for predicates, consisting of mappings form -- ByteStrings to Dynamic values. data Env -- | An empty environment. empty :: Env -- | Try to get the associated value for the given key. Only successful -- iff, (i) Env contains a binding for k and (ii) the -- type of value and target match. lookup :: (MonadState m, StateType m ~ Env, Typeable a) => ByteString -> m (Maybe a) -- | Add a binding from key to value to Env, overriding previous -- bindings if existing. insert :: (MonadState m, StateType m ~ Env, Typeable a) => ByteString -> a -> m () module Data.Predicate -- | Delta is a measure of distance. It is (optionally) used in -- predicates that evaluate to T but not uniquely so, i.e. -- different evaluations of T are possible and they may have a -- different "fitness". -- -- An example is content-negotiation. A HTTP request may specify a -- preference list of various media-types. A predicate matching one -- specific media-type evaluates to T, but other media-types may -- match even better. To represent this ambivalence, the predicate will -- include a delta value which can be used to decide which of the -- matching predicates should be preferred. type Delta = Double -- | A Bool-like type where each branch True or False -- carries some meta-data which is threaded through Predicate -- evaluation. data Boolean f t -- | logical False with some meta-data F :: f -> Boolean f t -- | logical True with some meta-data T :: Delta -> t -> Boolean f t -- | The Predicate class declares the function apply which -- evaluates the predicate against some value, returning a value of type -- Boolean. Besides being parameterised over predicate type and -- predicate parameter, the class is also parameterised over the actual -- types of T's and F's meta-data. class Predicate p a where type family FVal p type family TVal p apply :: Predicate p a => p -> a -> State Env (Boolean (FVal p) (TVal p)) -- | A Predicate instance which always returns T with the -- given value as T's meta-data. data Const f t Const :: t -> Const f t -- | A Predicate instance which always returns F with the -- given value as F's meta-data. data Fail f t Fail :: f -> Fail f t -- | A Predicate instance corresponding to the logical OR connective -- of two Predicates. It requires the meta-data of each -- True branch to be of the same type. -- -- If both arguments evaluate to T the one with the smaller -- Delta will be preferred, or--if equal--the left-hand argument. data (:|:) a b (:|:) :: a -> b -> :|: a b type (:+:) a b = Either a b -- | A Predicate instance corresponding to the logical OR connective -- of two Predicates. The meta-data of each True branch can -- be of different types. -- -- If both arguments evaluate to T the one with the smaller -- Delta will be preferred, or--if equal--the left-hand argument. data (:||:) a b (:||:) :: a -> b -> :||: a b -- | Data-type used for tupling-up the results of :&:. data (:*:) a b (:*:) :: a -> b -> :*: a b -- | A Predicate instance corresponding to the logical AND -- connective of two Predicates. data (:&:) a b (:&:) :: a -> b -> :&: a b -- | Evaluate the given predicate p against the given value -- a. eval :: Predicate p a => p -> a -> Boolean (FVal p) (TVal p) -- | The with function will invoke the given function only if the -- predicate p applied to the test value a evaluates to -- T. with :: (Monad m, Predicate p a) => p -> a -> (TVal p -> m ()) -> m () instance (Eq f, Eq t) => Eq (Boolean f t) instance (Show f, Show t) => Show (Boolean f t) instance (Eq a, Eq b) => Eq (a :*: b) instance (Show a, Show b) => Show (a :*: b) instance (Show a, Show b) => Show (a :&: b) instance (Predicate a c, Predicate b c, FVal a ~ FVal b) => Predicate (a :&: b) c instance (Show a, Show b) => Show (a :||: b) instance (Predicate a c, Predicate b c, FVal a ~ FVal b) => Predicate (a :||: b) c instance (Show a, Show b) => Show (a :|: b) instance (Predicate a c, Predicate b c, TVal a ~ TVal b, FVal a ~ FVal b) => Predicate (a :|: b) c instance Show f => Show (Fail f t) instance Predicate (Fail f t) a instance Show t => Show (Const f t) instance Predicate (Const f t) a module Snap.Predicates.Accept -- | A Predicate against the Requests "Accept" header. data Accept t s Accept :: t -> s -> Accept t s instance (Eq t, Eq s) => Eq (Accept t s) instance (Show t, Show s) => Show (Accept t s) instance (MType t, MSubType s) => Predicate (Accept t s) Request module Snap.Predicates.Content type Content x y = MediaType x y -- | A Predicate against the Requests "Content-Type" header. data ContentType t s ContentType :: t -> s -> ContentType t s instance (Eq t, Eq s) => Eq (ContentType t s) instance (Show t, Show s) => Show (ContentType t s) instance (MType t, MSubType s) => Predicate (ContentType t s) Request module Data.ByteString.Readable -- | The type-class Readable is used to convert ByteString -- values to values of other types. Most instances assume the -- ByteString is encoded via UTF-8. -- -- Minimal complete instance definition is given by -- readByteString. class Readable a where readByteStringList s = parseList ([], s) fromByteString s = do { (v, s') <- readByteString s; if null s' then Right v else Left ("unconsumed bytes: '" <> s' <> "'.") } readByteString :: Readable a => ByteString -> Either ByteString (a, ByteString) readByteStringList :: Readable a => ByteString -> Either ByteString ([a], ByteString) fromByteString :: Readable a => ByteString -> Either ByteString a instance Readable Int instance Readable Double instance Readable Char instance Readable Text instance Readable ByteString instance Readable a => Readable [a] instance Readable a => Readable (Maybe a) module Snap.Predicates.Params -- | The most generic request parameter predicate provided. It will get all -- request parameter values of _name and pass them on to the -- conversion function _read, which might either yield an error -- message or a value. In case of error, an optional default may be -- returned instead, if nothing is provided, the error message will be -- used when construction the 400 status. data Parameter a Parameter :: !ByteString -> ([ByteString] -> Either ByteString a) -> !(Maybe a) -> Parameter a -- | request parameter name _name :: Parameter a -> !ByteString -- | conversion function _read :: Parameter a -> [ByteString] -> Either ByteString a -- | (optional) default value _default :: Parameter a -> !(Maybe a) -- | Specialisation of Parameter which returns the first request -- which could be converted to the target type. data Param a Param :: ByteString -> Param a -- | Like Param, but denoting an optional parameter, i.e. if the -- parameter is not present or can not be converted to the target type, -- the predicate will still succeed. data ParamOpt a ParamOpt :: ByteString -> ParamOpt a -- | Like Param, but in case the parameter could not be found, the -- provided default value will be used. ParamDef is provided for -- convenience and nothing else than Param || Const, e.g. ParamDef -- "foo" 0 == Param "foo" :|: Const 0. data ParamDef a ParamDef :: ByteString -> a -> ParamDef a instance Show a => Show (ParamDef a) instance (Typeable a, Readable a) => Predicate (ParamDef a) Request instance Show (ParamOpt a) instance (Typeable a, Readable a) => Predicate (ParamOpt a) Request instance Show (Param a) instance (Typeable a, Readable a) => Predicate (Param a) Request instance Show (Parameter a) instance Typeable a => Predicate (Parameter a) Request module Snap.Predicates module Snap.Routes -- | The Routes monad is used to add routing declarations via -- addRoute or one of get, post, etc. Routing -- declarations can then be turned into the ordinary snap format, i.e. -- MonadSnap m => [(ByteString, m a)] or into strings. data Routes m a -- | Turn route definitions into a list of Strings. showRoutes :: Routes m () -> [String] -- | Turn route definitions into "snapable" format, i.e. Routes are grouped -- per path and selection evaluates routes against the given Snap -- Request. expandRoutes :: MonadSnap m => Routes m () -> [(ByteString, m ())] -- | Add a route for some Method and path (potentially with variable -- captures), and constrained the some Predicate. addRoute :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => Method -> ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. get :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. get_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. head :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. head_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. post :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. post_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. put :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. put_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. delete :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. delete_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. trace :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. trace_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. options :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. options_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method. connect :: (MonadSnap m, Show p, Predicate p Request, FVal p ~ Error) => ByteString -> (TVal p -> m ()) -> p -> Routes m () -- | Specialisation of addRoute for a specific HTTP Method -- taking no Predicate into consideration. connect_ :: MonadSnap m => ByteString -> (() -> m ()) -> Routes m () instance Monad (Routes m)