Changed description
from
Simple URL DSL for Haskell.
This library tries to make it easier for people to write Url strings,
structurally. Packages like <https://hackage.haskell.org/package/yesod-routes Yesod Routes>
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):
> expandRelative $ "foo.php" <?> ("key1","bar") <&> ("key2","baz")
>
> ↪ "foo.php?key1=bar&key2=baz"
... or use the MonadReader instance for a configurable host:
> let path = runAbsoluteUrl $ url $ "foo.php" <?> ("key1","bar") <&> ("key2","baz")
> path "example.com"
>
> ↪ "example.com/foo.php?key1=bar&key2=baz"
@url@ puts the @UrlString@ in a MonadReader that we can use for applying our
host. We use different monads for different deployment schemes (currently we
have 3 - @RelativeUrl@, @GroundedUrl@, and @AbsoluteUrl@), which we can
integrate in different libraries, like Lucid:
> (runAbsoluteUrl $ renderTextT $ do
> foo <- lift $ url $ "foo" <?> ("bar","baz")
> script_ [src_ foo] "" )
> ) "example.com"
>
> ↪ "<script src=\"example.com/foo?bar=baz\"></script>"
... and in Scotty ...
> 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 ) =>
> ScottyT LT.Text m ()
> run = get "/" $ do
> path <- lift $ url $ "foo" <?> ("bar","baz")
> text $ LT.fromStrict path
>
> λ> curl localhost:3000/
> ↪ "http://example.com/foo?bar=baz"
Note that in the scotty example, we don't use one of our deployment schemes -
this is because the @scottyT@ function expects it's underlying monad to be an
instance of @MonadIO@, which we can only instantiate in our monad transformers.
Please take mind - the string type underlying the Url rendering is generalized
to @Data.String.IsString@ for convenient use with @-XOverloadedStrings@. However,
due to that generality, we need to specify the monomorphic type (like
@Data.Text.Text@ above).
to Simple URL DSL for Haskell.
This library tries to make it easier for people to write Url strings,
structurally. Packages like <https://hackage.haskell.org/package/yesod-routes Yesod Routes>
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):
> expandRelative $ "foo.php" <?> ("key1","bar") <&> ("key2","baz")
>
> ↪ "foo.php?key1=bar&key2=baz"
... or use the MonadReader instance for a configurable host:
> let path = runAbsoluteUrlT $ queryUrl $ "foo.php" <?> ("key1","bar") <&> ("key2","baz")
> path "example.com"
>
> ↪ "example.com/foo.php?key1=bar&key2=baz"
@url@ puts the @UrlString@ in a MonadReader that we can use for applying our
host. We use different monads for different deployment schemes (currently we
have 3 - @RelativeUrl@, @GroundedUrl@, and @AbsoluteUrl@), which we can
integrate in different libraries, like Lucid:
> (runAbsoluteUrlT $ renderTextT $ do
> foo <- lift $ queryUrl $ "foo" <?> ("bar","baz")
> script_ [src_ foo] "" )
> ) "example.com"
>
> ↪ "<script src=\"example.com/foo?bar=baz\"></script>"
... and in Scotty ...
> main :: IO ()
> main = scottyT 3000
> rootConf
> rootConf
> run
>
> where
> rootConf = flip runAbsoluteUrlT "http://example.com"
>
> run :: ( MonadIO m
> , MonadReader T.Text m
> , Url T.Text m ) =>
> ScottyT LT.Text m ()
> run = get "/" $ do
> path <- lift $ queryUrl $ "foo" <?> ("bar","baz")
> text $ LT.fromStrict path
>
> λ> curl localhost:3000/
> ↪ "http://example.com/foo?bar=baz"
Note that in the scotty example, we don't use one of our deployment schemes -
this is because the @scottyT@ function expects it's underlying monad to be an
instance of @MonadIO@, which we can only instantiate in our monad transformers.
Please take mind - the string type underlying the Url rendering is generalized
to @Data.String.IsString@ for convenient use with @-XOverloadedStrings@. However,
due to that generality, we need to specify the monomorphic type (like
@Data.Text.Text@ above).