Painfully simple URL writing combinators

Version on this page:2.1.0@rev:1
LTS Haskell 15.16:9.0.1
Stackage Nightly 2020-04-13:9.0.1
Latest on Hackage:9.0.1

See all snapshots urlpath appears in

MIT licensed and maintained by Athan Clark
This version can be pinned in stack with:urlpath-2.1.0@sha256:a342b25d9ea3984cf20025d421f59629d7abdf4bd2b42a4e9ef53ba5729f13e1,4451

Module documentation for 2.1.0

Used by 1 package in lts-3.22(full list with versions):

Simple URL DSL for Haskell.

This library tries to make it easier for people to write Url strings, structurally. Packages like 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 = 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).