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


-- | Painfully simple URL writing combinators
--   
--   Simple URL DSL for Haskell.
--   
--   This library tries to make it easier for people to write Url strings,
--   structurally. Packages like <a>Yesod Routes</a> do a wonderful job at
--   implementing string-free routing and references, but sometimes we have
--   to compromise. This tries to make that compromise less painful.
--   
--   Use bare combinators to render your strings (kinda useless):
--   
--   <pre>
--   expandRelative $ "foo.php" &lt;?&gt; ("key1","bar") &lt;&amp;&gt; ("key2","baz")
--   
--   ↪ "foo.php?key1=bar&amp;key2=baz"
--   </pre>
--   
--   ... or use the MonadReader instance for a configurable host:
--   
--   <pre>
--   let path = runAbsoluteUrl $ url $ "foo.php" &lt;?&gt; ("key1","bar") &lt;&amp;&gt; ("key2","baz")
--   path "example.com"
--   
--   ↪ "example.com/foo.php?key1=bar&amp;key2=baz"
--   </pre>
--   
--   <tt>url</tt> puts the <tt>UrlString</tt> in a MonadReader that we can
--   use for applying our host. We use different monads for different
--   deployment schemes (currently we have 3 - <tt>RelativeUrl</tt>,
--   <tt>GroundedUrl</tt>, and <tt>AbsoluteUrl</tt>), which we can
--   integrate in different libraries, like Lucid:
--   
--   <pre>
--   (runAbsoluteUrl $ renderTextT $ do
--       foo &lt;- lift $ url $ "foo" &lt;?&gt; ("bar","baz")
--       script_ [src_ foo] "" )
--   ) "example.com"
--   
--   ↪ "&lt;script src=\"example.com/foo?bar=baz\"&gt;&lt;/script&gt;"
--   </pre>
--   
--   ... and in Scotty ...
--   
--   <pre>
--   main :: IO ()
--   main = scottyT 3000
--       rootConf
--       rootConf
--       run
--   
--     where
--       rootConf = flip runAbsoluteT "http://example.com"
--   
--       run :: ( MonadIO m
--              , MonadReader T.Text m
--              , Url T.Text m ) =&gt;
--              ScottyT LT.Text m ()
--       run = get "/" $ do
--         path &lt;- lift $ url $ "foo" &lt;?&gt; ("bar","baz")
--         text $ LT.fromStrict path
--   
--   λ&gt; curl localhost:3000/
--   ↪ "http://example.com/foo?bar=baz"
--   </pre>
--   
--   Note that in the scotty example, we don't use one of our deployment
--   schemes - this is because the <tt>scottyT</tt> function expects it's
--   underlying monad to be an instance of <tt>MonadIO</tt>, which we can
--   only instantiate in our monad transformers.
--   
--   Please take mind - the string type underlying the Url rendering is
--   generalized to <tt>Data.String.IsString</tt> for convenient use with
--   <tt>-XOverloadedStrings</tt>. However, due to that generality, we need
--   to specify the monomorphic type (like <tt>Data.Text.Text</tt> above).
@package urlpath
@version 0.1

module UrlPath.Types

-- | A Url string - a target page and GET parameters. We only require a
--   constraint of <tt>IsString</tt> so that construction can be
--   convenient, but rendering will require a monomorphic type.
data UrlString a
UrlString :: a -> [(a, a)] -> UrlString a

-- | We choose to not provide a <tt>Show</tt> instance for
--   <tt>UrlString</tt> to evade the <tt>String</tt> demand.
showUrlString :: UrlString a -> a

-- | Lifts a raw target path and a GET parameter pair into a
--   <tt>UrlString</tt>.
(<?>) :: (IsString a, Monoid a) => a -> (a, a) -> UrlString a

-- | Adds another GET parameter pair to a <tt>UrlString</tt>.
(<&>) :: (IsString a, Monoid a) => UrlString a -> (a, a) -> UrlString a

-- | Render the Url String as relative
expandRelative :: (IsString a, Monoid a) => UrlString a -> a

-- | Render the Url String as grounded
expandGrounded :: (IsString a, Monoid a) => UrlString a -> a

-- | Render the Url String as absolute - getting the root from a
--   <tt>MonadReader</tt> context. The <tt>Monoid</tt> instance will be
--   decided monomorphically, therefore a type signature will be needed
--   when ran.
expandAbsolute :: (MonadReader a m, IsString a, Monoid a) => UrlString a -> m a

-- | Render the Url String as absolute, but with your own configuration
--   type.
--   
--   <pre>
--   data SiteConfig = SiteConfig { host :: T.Text
--                                , cdnHost :: T.Text
--                                }
--     deriving (Show, Eq)
--   
--   foo :: HtmlT (Reader SiteConfig) ()
--   foo = do
--     url &lt;- lift $ expandAbsoluteWith ("foo.php" &lt;?&gt; ("bar","baz")) host
--     script_ [src_ url] ""
--   
--   bar :: LT.Text 
--   bar = (runReader (runTextT foo)) $
--     SiteConfig "example.com" "cdn.example.com"
--   </pre>
expandAbsoluteWith :: (MonadReader a m, IsString a, Monoid a) => UrlString a -> (a -> a) -> m a

-- | Rendering mode transformer. This isn't an instance of
--   <tt>UrlReader</tt> - to use, simple <tt>lift</tt> as many levels as
--   you need:
--   
--   <pre>
--   foo :: Monad m =&gt; HtmlT (RelativeUrlT m) ()
--   foo = do
--     path &lt;- lift $ url $ "foo.php" &lt;?&gt; ("bar","baz")
--     script_ [src_ path] ""
--   </pre>
--   
--   When rendering <tt>foo</tt>, simply use the Transformer's <tt>run</tt>
--   function to convert it to a reader:
--   
--   <pre>
--   bar :: ( Monad m, IsString a, Monoid a ) =&gt; m a
--   bar = (runRelativeUrlT (renderTextT foo)) "example.com"
--   </pre>
newtype RelativeUrlT h m a
RelativeUrlT :: (h -> m a) -> RelativeUrlT h m a
runRelativeUrlT :: RelativeUrlT h m a -> h -> m a

-- | Concrete Monad for automatically coercing HtmlT's to use a mode of Url
--   rendering (relative, grounded, or absolute).
--   
--   <pre>
--   foo :: HtmlT RelativeUrl ()
--   foo = do
--     path &lt;- lift $ url $ "foo.php" &lt;?&gt; ("bar","baz")
--     script_ [src_ path] ""
--   </pre>
--   
--   when running the monad reader, use the <tt>runUrlReader</tt> member
--   function of the <tt>UrlReader</tt> typeclass:
--   
--   <pre>
--   bar :: ( IsString a, Monoid a ) =&gt; a
--   bar = (runUrlReader (renderTextT foo)) "example.com"
--   </pre>
--   
--   To change the deployment sheme, simply coerce the environment monad in
--   <tt>foo</tt>.
newtype RelativeUrl h a
RelativeUrl :: (h -> a) -> RelativeUrl h a
runRelativeUrl :: RelativeUrl h a -> h -> a
newtype GroundedUrlT h m a
GroundedUrlT :: (h -> m a) -> GroundedUrlT h m a
runGroundedUrlT :: GroundedUrlT h m a -> h -> m a
newtype GroundedUrl h a
GroundedUrl :: (h -> a) -> GroundedUrl h a
runGroundedUrl :: GroundedUrl h a -> h -> a
newtype AbsoluteUrlT h m a
AbsoluteUrlT :: (h -> m a) -> AbsoluteUrlT h m a
runAbsoluteUrlT :: AbsoluteUrlT h m a -> h -> m a
newtype AbsoluteUrl h a
AbsoluteUrl :: (h -> a) -> AbsoluteUrl h a
runAbsoluteUrl :: AbsoluteUrl h a -> h -> a
instance Functor m => Functor (RelativeUrlT h m)
instance Functor (RelativeUrl h)
instance IsString a => MonadReader a (AbsoluteUrl a)
instance Monad (AbsoluteUrl h)
instance Applicative (AbsoluteUrl h)
instance Functor (AbsoluteUrl h)
instance MonadIO m => MonadIO (AbsoluteUrlT a m)
instance (Monad m, IsString a) => MonadReader a (AbsoluteUrlT a m)
instance MonadTrans (AbsoluteUrlT h)
instance Monad m => Monad (AbsoluteUrlT h m)
instance Applicative f => Applicative (AbsoluteUrlT h f)
instance Functor f => Functor (AbsoluteUrlT h f)
instance IsString a => MonadReader a (GroundedUrl a)
instance Monad (GroundedUrl h)
instance Applicative (GroundedUrl h)
instance Functor (GroundedUrl h)
instance MonadIO m => MonadIO (GroundedUrlT a m)
instance (Monad m, IsString a) => MonadReader a (GroundedUrlT a m)
instance MonadTrans (GroundedUrlT h)
instance Monad m => Monad (GroundedUrlT h m)
instance Applicative f => Applicative (GroundedUrlT h f)
instance Functor f => Functor (GroundedUrlT h f)
instance IsString a => MonadReader a (RelativeUrl a)
instance Monad (RelativeUrl h)
instance Applicative (RelativeUrl h)
instance MonadIO m => MonadIO (RelativeUrlT a m)
instance (Monad m, IsString a) => MonadReader a (RelativeUrlT a m)
instance MonadTrans (RelativeUrlT h)
instance Monad m => Monad (RelativeUrlT h m)
instance Applicative f => Applicative (RelativeUrlT h f)

module UrlPath

-- | Overload deployment schemes with this - then, all that's needed is a
--   type coercion to change deployment. This only works with flat
--   (co)monads, so monad transformers are out.
class Url string m => UrlReader string m
runUrlReader :: (UrlReader string m, Url string m) => m string -> string -> string

-- | <tt>Url</tt> is a relationship between an underlying (monomorphic)
--   string type <tt>string</tt>, and a deployment context <tt>m</tt>. We
--   try to make the deployment and implementation type coercible at the
--   top level - coercing your final expression to <tt>String</tt> or
--   <tt>T.Text</tt> will have <i>all</i> use-cases coerce to that type,
--   similarly with the deployment scheme.
--   
--   We chose to not force <tt>MonadReader</tt> as a superclass for
--   <tt>m</tt> due to the monomorphic demand on functional dependencies.
class (IsString string, Monoid string, MonadReader string m) => Url string (m :: * -> *)
url :: Url string m => UrlString string -> m string
stringUrl :: Url string m => string -> m string
instance (Monad m, Monoid a, IsString a) => Url a (AbsoluteUrlT a m)
instance (Monad m, Monoid a, IsString a) => Url a (GroundedUrlT a m)
instance (Monad m, Monoid a, IsString a) => Url a (RelativeUrlT a m)
instance (Monoid a, IsString a) => UrlReader a (AbsoluteUrl a)
instance (Monoid a, IsString a) => Url a (AbsoluteUrl a)
instance (Monoid a, IsString a) => UrlReader a (GroundedUrl a)
instance (Monoid a, IsString a) => Url a (GroundedUrl a)
instance (Monoid a, IsString a) => UrlReader a (RelativeUrl a)
instance (Monoid a, IsString a) => Url a (RelativeUrl a)