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


-- | Library for maintaining correctness and composability of URLs within an application.
--   
--   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.2


-- | 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 Monad m => MonadRoute (RouteT url m)
instance MonadWriter w m => MonadWriter w (RouteT url m)
instance MonadTrans (RouteT url)
instance MonadState s m => MonadState s (RouteT url m)
instance MonadRWS r w s m => MonadRWS r w s (RouteT url m)
instance MonadReader r m => MonadReader r (RouteT url m)
instance MonadIO m => MonadIO (RouteT url m)
instance MonadFix m => MonadFix (RouteT url m)
instance MonadError e m => MonadError e (RouteT url m)
instance MonadCont m => MonadCont (RouteT url m)
instance (MonadPlus m, Monad (RouteT url m)) => MonadPlus (RouteT url m)
instance Monad m => Monad (RouteT url m)
instance Alternative m => Alternative (RouteT url m)
instance Applicative m => Applicative (RouteT url m)
instance Functor m => Functor (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 Functor (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
patternParse :: ([Text] -> Either String a) -> URLParser a

-- | run a <a>URLParser</a> on a list of path segments
--   
--   returns <tt>Left <a>parse error</a></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 <a>parse error</a></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 PathInfo Integer
instance PathInfo Int
instance PathInfo [String]
instance PathInfo String
instance PathInfo [Text]
instance PathInfo Text
instance PathInfo a => GPathInfo (K1 i a)
instance (GPathInfo a, GPathInfo b) => GPathInfo (a :+: b)
instance (GPathInfo a, GPathInfo b) => GPathInfo (a :*: b)
instance (GPathInfo a, Constructor c) => GPathInfo (C1 c a)
instance GPathInfo a => GPathInfo (S1 c a)
instance GPathInfo a => GPathInfo (D1 c a)
instance GPathInfo U1

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
