modern-uri: Modern library for working with URIs

[ bsd3, library, text ] [ Propose Tags ]

Modern library for working with URIs.

[Skip to Readme]
Versions [faq],,,,,,,,,,,,,
Change log
Dependencies base (>=4.11 && <5.0), bytestring (>=0.2 && <0.11), containers (>=0.5 && <0.7), contravariant (>=1.3 && <2.0), deepseq (>=1.3 && <1.5), exceptions (>=0.6 && <0.11), megaparsec (>=7.0 && <10.0), mtl (>=2.0 && <3.0), profunctors (>=5.2.1 && <6.0), QuickCheck (>=2.4 && <3.0), reflection (>=2.0 && <3.0), tagged (==0.8.*), template-haskell (>=2.10 && <2.17), text (>=0.2 && <1.3) [details]
License BSD-3-Clause
Author Mark Karpov <>
Maintainer Mark Karpov <>
Revised Revision 3 made by mrkkrp at 2020-09-21T18:14:11Z
Category Text
Home page
Bug tracker
Source repo head: git clone
Uploaded by mrkkrp at 2020-04-04T11:03:11Z
Distributions Arch:, LTSHaskell:, NixOS:, Stackage:
Downloads 9871 total (330 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2020-04-04 [all 1 reports]


[Index] [Quick Jump]



Turn on development settings.


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

For package maintainers and hackage trustees

Readme for modern-uri-

[back to package description]

Modern URI

License BSD3 Hackage Stackage Nightly Stackage LTS Build Status

This is a modern library for working with URIs in Haskell as per RFC 3986:


The modern-uri package features:

  • Correct by construction URI data type. The correctness is ensured by making sure that every sub-component of the URI record is by itself cannot be invalid. This boils down to careful use of types and a set of smart constructors.
  • Textual components in the URI data type are represented as Text rather than ByteString, because they are percent-decoded and so they can contain characters outside of ASCII range (i.e. Unicode). This allows for easier manipulation of URIs, while encoding and decoding headaches are handled by the parsers and renders for you.
  • Absolute and relative URIs differ only by the scheme component: if it's Nothing, then URI is relative, otherwise it's absolute.
  • Megaparsec parser that can be used as a standalone smart constructor for the URI data type (see mkURI) as well as be seamlessly integrated into a bigger Megaparsec parser that consumes strict Text (see parser) or strict ByteString (see parserBs).
  • The parser performs some normalization, for example it collapses consecutive slashes. Some smart constructors such as mkScheme and mkHost also perform normalization. So in a sense URIs are also “normalized by construction” to some extent.
  • Fast rendering to strict Text and ByteString as well as to their respective Builder types and to String/ShowS.
  • Extensive set of lensy helpers for easier manipulation of the nested data types (see Text.URI.Lens).
  • Quasi-quoters for compile-time construction of the URI data type and refined text types (see Text.URI.QQ).

Quick start

The modern-uri package serves three main purposes:

  • Construction of the URI data type.
  • Inspection and manipulation of the URI data type (in the sense of changing its parts).
  • Rendering of URIs.

Let's walk through every operation quickly.

Construction of URIs

There are four ways to create a URI value. First off, one could assemble it manually like so:

λ> :set -XOverloadedStrings
λ> import qualified Text.URI as URI
λ> scheme <- URI.mkScheme "https"
λ> scheme
λ> host <- URI.mkHost ""
λ> host
λ> let uri = URI.URI (Just scheme) (Right (URI.Authority Nothing host Nothing)) Nothing [] Nothing
λ> uri
  { uriScheme = Just "https"
  , uriAuthority = Right
        { authUserInfo = Nothing
        , authHost = ""
        , authPort = Nothing })
  , uriPath = Nothing
  , uriQuery = []
  , uriFragment = Nothing }

In this library we use quite a few refined text values. They only can be constructed by using smart constructors like mkScheme :: MonadThrow m => Text -> m (RText 'Scheme). For example, if argument to mkScheme is not a valid scheme, an exception will be thrown. Note that monads such as Maybe are also instances of the MonadThrow type class, and so the smart constructors may be used in pure setting as well.

There is a smart constructor that can make an entire URI too, it's called (unsurprisingly) mkURI:

λ> uri <- URI.mkURI ""
λ> uri
  { uriScheme = Just "https"
  , uriAuthority = Right
        { authUserInfo = Nothing
        , authHost = ""
        , authPort = Nothing })
  , uriPath = Nothing
  , uriQuery = []
  , uriFragment = Nothing }

If the argument of mkURI is not a valid URI, then an exception will be thrown. The exception will contain full context and the actual parse error.

If some refined text value or URI is known statically at compile time, we can use Template Haskell, namely the “quasi quotes” feature. To do so import the Text.URI.QQ module and enable the QuasiQuotes language extension, like so:

λ> :set -XQuasiQuotes
λ> import qualified Text.URI.QQ as QQ
λ> let uri = [QQ.uri||]
λ> uri
  { uriScheme = Just "https"
  , uriAuthority = Right
        { authUserInfo = Nothing
        , authHost = ""
        , authPort = Nothing })
  , uriPath = Nothing
  , uriQuery = []
  , uriFragment = Nothing }

Note how the value returned by the url quasi quote is pure, its construction cannot fail because when there is an invalid URI inside the quote it's a compilation error. The Text.URI.QQ module has quasi-quoters for scheme, host, and other components.

Finally, the package provides two Megaparsec parsers: parser and parserBs. The first works on strict Text, while other one works on strict ByteStrings. You can use the parsers in a bigger Megaparsec parser to parse URIs.

Inspection and manipulation

Although one could use record syntax directly, possibly with language extensions like RecordWildcards, the best way to inspect and edit parts of URI is with lenses. The lenses can be found in the Text.URI.Lens module. If you have never used the lens library, you could probably start by reading/watching materials suggested in the library description on Hackage.

Here are some examples, just to show off what you can do:

λ> import Text.URI.Lens
λ> uri <- URI.mkURI ""
λ> uri ^. uriScheme
Just "https"
λ> uri ^? uriAuthority . _Right . authHost
Just ""
λ> uri ^. isPathAbsolute
λ> uri ^. uriPath
λ> k <- URI.mkQueryKey "foo"
λ> uri ^.. uriQuery . queryParam k
-- etc.


Rendering turns a URI into a sequence of bytes or characters. Currently the following options are available:

  • render for rendering to strict Text.
  • render' for rendering to text Builder. It's possible to turn that into lazy Text by using the toLazyText function from Data.Text.Lazy.Builder.
  • renderBs for rendering to strict ByteString.
  • renderBs' for rendering to byte string Builder. Similarly it's possible to get a lazy ByteString from that by using the toLazyByteString function from Data.ByteString.Builder.
  • renderStr can be used to render to String. Sometimes it's handy. The render uses difference lists internally so it's not that slow, but in general I'd advise avoiding Strings.
  • renderStr' returns ShowS, which is just a synonym for String -> String—a function that prepends the result of rendering to a given String. This is useful when the URI you want to render is a part of a bigger output, just like with the builders mentioned above.


λ> uri <- mkURI ""
λ> render uri
λ> renderBs uri
λ> renderStr uri
-- etc.


Issues, bugs, and questions may be reported in the GitHub issue tracker for this project.

Pull requests are also welcome.


Copyright © 2017–present Mark Karpov

Distributed under BSD 3 clause license.