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


-- | portable, type-safe URL routing
--   
--   A collection of types and functions that ensure that URLs generated by
--   an application are valid. Need more properties here.
@package web-routes
@version 0.27.10


-- | Declaration of the <a>RouteT</a> monad transformer
module Web.Routes.RouteT

-- | monad transformer for generating URLs
newtype RouteT url m a
RouteT :: ((url -> [(Text, Maybe Text)] -> Text) -> m a) -> RouteT url m a
[unRouteT] :: RouteT url m a -> (url -> [(Text, Maybe Text)] -> Text) -> m a
class (Monad m) => MonadRoute m where type family URL m
askRouteFn :: MonadRoute m => m (URL m -> [(Text, Maybe Text)] -> Text)

-- | convert a <a>RouteT</a> based route handler to a handler that can be
--   used with the <tt>Site</tt> type
--   
--   NOTE: this function used to be the same as <a>unRouteT</a>. If you
--   want the old behavior, just call <a>unRouteT</a>.
runRouteT :: (url -> RouteT url m a) -> ((url -> [(Text, Maybe Text)] -> Text) -> url -> m a)

-- | Transform the computation inside a <tt>RouteT</tt>.
mapRouteT :: (m a -> n b) -> RouteT url m a -> RouteT url n b

-- | Execute a computation in a modified environment
withRouteT :: ((url' -> [(Text, Maybe Text)] -> Text) -> (url -> [(Text, Maybe Text)] -> Text)) -> RouteT url m a -> RouteT url' m a
liftRouteT :: m a -> RouteT url m a
askRouteT :: (Monad m) => RouteT url m (url -> [(Text, Maybe Text)] -> Text)
showURL :: (MonadRoute m) => URL m -> m Text
showURLParams :: (MonadRoute m) => URL m -> [(Text, Maybe Text)] -> m Text
nestURL :: (url1 -> url2) -> RouteT url1 m a -> RouteT url2 m a
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Web.Routes.RouteT.RouteT url m)
instance GHC.Base.Functor m => GHC.Base.Functor (Web.Routes.RouteT.RouteT url m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Web.Routes.RouteT.RouteT url m)
instance GHC.Base.Alternative m => GHC.Base.Alternative (Web.Routes.RouteT.RouteT url m)
instance GHC.Base.Monad m => GHC.Base.Monad (Web.Routes.RouteT.RouteT url m)
instance (GHC.Base.MonadPlus m, GHC.Base.Monad (Web.Routes.RouteT.RouteT url m)) => GHC.Base.MonadPlus (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.Cont.Class.MonadCont m => Control.Monad.Cont.Class.MonadCont (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.RWS.Class.MonadRWS r w s m => Control.Monad.RWS.Class.MonadRWS r w s (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Web.Routes.RouteT.RouteT url m)
instance Control.Monad.Trans.Class.MonadTrans (Web.Routes.RouteT.RouteT url)
instance Control.Monad.Writer.Class.MonadWriter w m => Control.Monad.Writer.Class.MonadWriter w (Web.Routes.RouteT.RouteT url m)
instance GHC.Base.Monad m => Web.Routes.RouteT.MonadRoute (Web.Routes.RouteT.RouteT url m)


-- | Conversions between raw pathinfos and decoded path segments.
module Web.Routes.Base

-- | Encodes a list of path segments into a valid URL fragment.
--   
--   This function takes the following three steps:
--   
--   <ul>
--   <li>UTF-8 encodes the characters.</li>
--   <li>Performs percent encoding on all unreserved characters, as well as
--   :@=+$,</li>
--   <li>Intercalates with a slash.</li>
--   </ul>
--   
--   For example:
--   
--   <pre>
--   encodePathInfo [\"foo\", \"bar\", \"baz\"]
--   </pre>
--   
--   "foo/bar/baz"
--   
--   <pre>
--   encodePathInfo [\"foo bar\", \"baz\/bin\"]
--   </pre>
--   
--   "foo%20bar/baz%2Fbin"
--   
--   <pre>
--   encodePathInfo [\"שלום\"]
--   </pre>
--   
--   "%D7%A9%D7%9C%D7%95%D7%9D"
encodePathInfo :: [Text] -> [(Text, Maybe Text)] -> Text

-- | Performs the inverse operation of <a>encodePathInfo</a>.
--   
--   In particular, this function:
--   
--   <ul>
--   <li>Splits a string at each occurence of a forward slash.</li>
--   <li>Percent-decodes the individual pieces.</li>
--   <li>UTF-8 decodes the resulting data.</li>
--   </ul>
--   
--   This utilizes <a>decodeString</a> from the utf8-string library, and
--   thus all UTF-8 decoding errors are handled as per that library.
--   
--   In general, you will want to strip the leading slash from a pathinfo
--   before passing it to this function. For example:
--   
--   <pre>
--   decodePathInfo \"\"
--   </pre>
--   
--   []
--   
--   <pre>
--   decodePathInfo \"\/\"
--   </pre>
--   
--   <ul>
--   <li><i>""</i></li>
--   </ul>
--   
--   Note that while function accepts a <a>Text</a> value, it is expected
--   that <a>Text</a> will only contain the subset of characters which are
--   allowed to appear in a URL.
decodePathInfo :: ByteString -> [Text]

module Web.Routes.Site

-- | A site groups together the three functions necesary to make an
--   application:
--   
--   <ul>
--   <li>A function to convert from the URL type to path segments.</li>
--   <li>A function to convert from path segments to the URL, if
--   possible.</li>
--   <li>A function to return the application for a given URL.</li>
--   </ul>
--   
--   There are two type parameters for Site: the first is the URL datatype,
--   the second is the application datatype. The application datatype will
--   depend upon your server backend.
data Site url a
Site :: ((url -> [(Text, Maybe Text)] -> Text) -> url -> a) -> (url -> ([Text], [(Text, Maybe Text)])) -> ([Text] -> Either String url) -> Site url a

-- | Return the appropriate application for a given URL.
--   
--   The first argument is a function which will give an appropriate URL
--   (as a String) for a URL datatype. This is usually constructed by a
--   combination of <a>formatPathSegments</a> and the prepending of an
--   absolute application root.
--   
--   Well behaving applications should use this function to generating all
--   internal URLs.
[handleSite] :: Site url a -> (url -> [(Text, Maybe Text)] -> Text) -> url -> a

-- | This function must be the inverse of <a>parsePathSegments</a>.
[formatPathSegments] :: Site url a -> url -> ([Text], [(Text, Maybe Text)])

-- | This function must be the inverse of <a>formatPathSegments</a>.
[parsePathSegments] :: Site url a -> [Text] -> Either String url

-- | Override the "default" URL, ie the result of <a>parsePathSegments</a>
--   [].
setDefault :: url -> Site url a -> Site url a

-- | Retrieve the application to handle a given request.
--   
--   NOTE: use <a>decodePathInfo</a> to convert a <a>ByteString</a> url to
--   a properly decoded list of path segments
runSite :: Text -> Site url a -> [Text] -> (Either String a)
instance GHC.Base.Functor (Web.Routes.Site.Site url)

module Web.Routes.PathInfo
stripOverlap :: (Eq a) => [a] -> [a] -> [a]
stripOverlapBS :: ByteString -> ByteString -> ByteString
stripOverlapText :: Text -> Text -> Text
type URLParser a = GenParser Text () a
pToken :: tok -> (Text -> Maybe a) -> URLParser a

-- | match on a specific string
segment :: Text -> URLParser Text

-- | match on any string
anySegment :: URLParser Text

-- | apply a function to the remainder of the segments
--   
--   useful if you want to just do normal pattern matching: &gt; &gt; foo
--   ["foo", "bar"] = Right (Foo Bar) &gt; foo ["baz"] = Right Baz &gt; foo
--   _ = Left "parse error"
--   
--   <pre>
--   patternParse foo
--   </pre>
patternParse :: ([Text] -> Either String a) -> URLParser a

-- | run a <a>URLParser</a> on a list of path segments
--   
--   returns <tt>Left "parse error"</tt> on failure.
--   
--   returns <tt>Right a</tt> on success
parseSegments :: URLParser a -> [Text] -> Either String a

-- | Simple parsing and rendering for a type to and from URL path segments.
--   
--   If you're using GHC 7.2 or later, you can use <tt>DeriveGeneric</tt>
--   to derive instances of this class:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   data Sitemap = Home | BlogPost Int deriving Generic
--   instance PathInfo Sitemap
--   </pre>
--   
--   This results in the following instance:
--   
--   <pre>
--   instance PathInfo Sitemap where
--       toPathSegments Home = ["home"]
--       toPathSegments (BlogPost x) = "blog-post" : toPathSegments x
--       fromPathSegments = Home &lt;$ segment "home"
--                      &lt;|&gt; BlogPost &lt;$ segment "blog-post" &lt;*&gt; fromPathSegments
--   </pre>
--   
--   And here it is in action:
--   
--   <pre>
--   &gt;&gt;&gt; toPathInfo (BlogPost 123)
--   "/blog-post/123"
--   
--   &gt;&gt;&gt; fromPathInfo "/blog-post/123" :: Either String Sitemap
--   Right (BlogPost 123)
--   </pre>
--   
--   To instead derive instances using <tt>TemplateHaskell</tt>, see
--   <a>web-routes-th</a>.
class PathInfo url where toPathSegments = gtoPathSegments . from fromPathSegments = to <$> gfromPathSegments
toPathSegments :: PathInfo url => url -> [Text]
fromPathSegments :: PathInfo url => URLParser url

-- | convert url into the path info portion of a URL
toPathInfo :: (PathInfo url) => url -> Text

-- | convert url + params into the path info portion of a URL + a query
--   string
toPathInfoParams :: (PathInfo url) => url -> [(Text, Maybe Text)] -> Text

-- | parse a <a>String</a> into <tt>url</tt> using <a>PathInfo</a>.
--   
--   returns <tt>Left "parse error"</tt> on failure
--   
--   returns <tt>Right url</tt> on success
fromPathInfo :: (PathInfo url) => ByteString -> Either String url

-- | turn a routing function into a <a>Site</a> value using the
--   <a>PathInfo</a> class
mkSitePI :: (PathInfo url) => ((url -> [(Text, Maybe Text)] -> Text) -> url -> a) -> Site url a

-- | show Parsec <a>ParseError</a> using terms that relevant to parsing a
--   url
showParseError :: ParseError -> String

-- | Representable types of kind *. This class is derivable in GHC with the
--   DeriveGeneric flag on.
class Generic a
instance Web.Routes.PathInfo.GPathInfo GHC.Generics.U1
instance Web.Routes.PathInfo.GPathInfo a => Web.Routes.PathInfo.GPathInfo (GHC.Generics.D1 c a)
instance Web.Routes.PathInfo.GPathInfo a => Web.Routes.PathInfo.GPathInfo (GHC.Generics.S1 c a)
instance (Web.Routes.PathInfo.GPathInfo a, GHC.Generics.Constructor c) => Web.Routes.PathInfo.GPathInfo (GHC.Generics.C1 c a)
instance (Web.Routes.PathInfo.GPathInfo a, Web.Routes.PathInfo.GPathInfo b) => Web.Routes.PathInfo.GPathInfo (a GHC.Generics.:*: b)
instance (Web.Routes.PathInfo.GPathInfo a, Web.Routes.PathInfo.GPathInfo b) => Web.Routes.PathInfo.GPathInfo (a GHC.Generics.:+: b)
instance Web.Routes.PathInfo.PathInfo a => Web.Routes.PathInfo.GPathInfo (GHC.Generics.K1 i a)
instance Web.Routes.PathInfo.PathInfo Data.Text.Internal.Text
instance Web.Routes.PathInfo.PathInfo [Data.Text.Internal.Text]
instance Web.Routes.PathInfo.PathInfo GHC.Base.String
instance Web.Routes.PathInfo.PathInfo [GHC.Base.String]
instance Web.Routes.PathInfo.PathInfo GHC.Types.Int
instance Web.Routes.PathInfo.PathInfo GHC.Integer.Type.Integer

module Web.Routes.QuickCheck

-- | test that a <a>PathInfo</a> instance is valid
--   
--   Generates <tt>Arbitrary</tt> <tt>url</tt> values and checks that:
--   
--   fromPathInfo . toPathInfo == id
pathInfoInverse_prop :: (Eq url, PathInfo url) => url -> Bool

module Web.Routes
