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


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

-- | Returns path segments as well as possible query string components
--   
--   For example:
--   
--   <pre>
--   decodePathInfoParams "/home?q=1"
--   </pre>
--   
--   (["home"],[("q",Just "1")])
decodePathInfoParams :: ByteString -> ([Text], [(Text, Maybe Text)])


-- | 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 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 GHC.Base.Monad m => Web.Routes.RouteT.MonadRoute (Web.Routes.RouteT.RouteT url m)
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 Control.Monad.Fail.MonadFail m => Control.Monad.Fail.MonadFail (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)

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
toPathSegments :: PathInfo url => url -> [Text]
fromPathSegments :: PathInfo url => URLParser url
toPathSegments :: (PathInfo url, Generic url, GPathInfo (Rep url)) => url -> [Text]
fromPathSegments :: (PathInfo url, Generic url, GPathInfo (Rep 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

-- | parse a <a>String</a> into '(url, Query)' using <a>PathInfo</a>.
--   
--   returns <tt>Left "parse error"</tt> on failure
--   
--   returns <tt>Right (url, Query</tt> on success
fromPathInfoParams :: PathInfo url => ByteString -> Either String (url, [(Text, Maybe Text)])

-- | 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 <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <a>id</a>
--   <a>to</a> . <a>from</a> ≡ <a>id</a>
--   </pre>
class () => Generic a
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.Int.Int8
instance Web.Routes.PathInfo.PathInfo GHC.Int.Int16
instance Web.Routes.PathInfo.PathInfo GHC.Int.Int32
instance Web.Routes.PathInfo.PathInfo GHC.Int.Int64
instance Web.Routes.PathInfo.PathInfo GHC.Num.Integer.Integer
instance Web.Routes.PathInfo.PathInfo GHC.Types.Word
instance Web.Routes.PathInfo.PathInfo GHC.Word.Word8
instance Web.Routes.PathInfo.PathInfo GHC.Word.Word16
instance Web.Routes.PathInfo.PathInfo GHC.Word.Word32
instance Web.Routes.PathInfo.PathInfo GHC.Word.Word64
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)

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
