-- 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.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 plain, Monoid plain) => UrlString plain -> plain

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

-- | 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 plain m, IsString plain, Monoid plain) => UrlString plain -> m plain

-- | 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 plain, Monoid plain) => UrlString plain -> (a -> plain) -> m plain

-- | 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 m h b
RelativeUrlT :: (h -> m b) -> RelativeUrlT m h b
runRelativeUrlT :: RelativeUrlT m h b -> h -> m b

-- | 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 m h b
GroundedUrlT :: (h -> m b) -> GroundedUrlT m h b
runGroundedUrlT :: GroundedUrlT m h b -> h -> m b
newtype GroundedUrl h a
GroundedUrl :: (h -> a) -> GroundedUrl h a
runGroundedUrl :: GroundedUrl h a -> h -> a
newtype AbsoluteUrlT m h b
AbsoluteUrlT :: (h -> m b) -> AbsoluteUrlT m h b
runAbsoluteUrlT :: AbsoluteUrlT m h b -> h -> m b
newtype AbsoluteUrl h a
AbsoluteUrl :: (h -> a) -> AbsoluteUrl h a
runAbsoluteUrl :: AbsoluteUrl h a -> h -> a
instance Functor m => Functor (RelativeUrlT m h)
instance Functor (RelativeUrl h)
instance IsString a => MonadReader a (AbsoluteUrl a)
instance Monad (AbsoluteUrl h)
instance Applicative (AbsoluteUrl h)
instance Functor (AbsoluteUrl h)
instance (Monad m, IsString h) => MonadReader h (AbsoluteUrlT m h)
instance Monad m => Monad (AbsoluteUrlT m h)
instance Applicative f => Applicative (AbsoluteUrlT f h)
instance Functor f => Functor (AbsoluteUrlT f h)
instance IsString a => MonadReader a (GroundedUrl a)
instance Monad (GroundedUrl h)
instance Applicative (GroundedUrl h)
instance Functor (GroundedUrl h)
instance (Monad m, IsString h) => MonadReader h (GroundedUrlT m h)
instance Monad m => Monad (GroundedUrlT m h)
instance Applicative f => Applicative (GroundedUrlT f h)
instance Functor f => Functor (GroundedUrlT f h)
instance IsString a => MonadReader a (RelativeUrl a)
instance Monad (RelativeUrl h)
instance Applicative (RelativeUrl h)
instance (Monad m, IsString h) => MonadReader h (RelativeUrlT m h)
instance Monad m => Monad (RelativeUrlT m h)
instance Applicative f => Applicative (RelativeUrlT f h)

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 plain m => UrlReader plain m
runUrlReader :: (UrlReader plain m, Url plain m) => m plain b -> plain -> b

-- | <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 plain, Monoid plain, MonadReader plain (m plain)) => Url plain (m :: * -> * -> *)
url :: Url plain m => UrlString plain -> m plain plain
plainUrl :: Url plain m => plain -> m plain plain
instance (Monad m, Monoid plain, IsString plain) => Url plain (AbsoluteUrlT m)
instance (Monad m, Monoid plain, IsString plain) => Url plain (GroundedUrlT m)
instance (Monad m, Monoid plain, IsString plain) => Url plain (RelativeUrlT m)
instance (Monoid plain, IsString plain) => UrlReader plain AbsoluteUrl
instance (Monoid plain, IsString plain) => Url plain AbsoluteUrl
instance (Monoid plain, IsString plain) => UrlReader plain GroundedUrl
instance (Monoid plain, IsString plain) => Url plain GroundedUrl
instance (Monoid plain, IsString plain) => UrlReader plain RelativeUrl
instance (Monoid plain, IsString plain) => Url plain RelativeUrl