Hackage :: [Package]

dormouse-uri: Library for type-safe representations of Uri/Urls

[ bsd3, library, web ] [ Propose Tags ] [ Report a vulnerability ]

Dormouse-Uri provides type safe handling of Uris and Urls.

Uri sytax is well defined according to RFC 3986, Dormouse-Uri parses and encodes Uris according to the syntax defined in this document.

We define Url as an absolute URI associated with web resources, the current version of Dormouse-Uri restricts Urls to the http and https schemes.

Dormouse-Uri has the following features:

  • The Uri and Url data types use Data.Text internally, this allows you to freely include percent-decoded characters which will be properly rendered when the Url/Uri is encoded.

  • Quasiquoters to allow safe construction of Uri/Urls from string literals.

  • DataKinds allow Urls to be restricted to the http or https schemes at the type level.

  • A UrlBuilder syntax to allow type-safe construction/concatenation of Urls from their components, e.g. path and query parameters.

Please see https://dormouse.io for full documentation.

[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.1.0.0, 0.1.0.1, 0.2.0.0, 0.3.0.0
Change log ChangeLog.md
Dependencies attoparsec (>=0.13.2.4 && <0.15), base (>=4.7 && <5), bytestring (>=0.10.8 && <0.12.0), case-insensitive (>=1.2.1.0 && <2.0.0), containers (>=0.6.2.1 && <0.7), http-types (>=0.12.3 && <0.13), safe-exceptions (>=0.1.7 && <0.2.0), template-haskell (>=2.15.0 && <3.0.0), text (>=2.0.0 && <3.0.0) [details]
License BSD-3-Clause
Copyright 2020-2021 Phil Curzon
Author Phil Curzon
Maintainer phil@novelfs.org
Category Web
Home page https://dormouse.io/uri.html
Bug tracker https://github.com/theinnerlight/dormouse/issues
Source repo head: git clone https://github.com/theinnerlight/dormouse
Uploaded by philcurzon at 2024-09-04T10:21:23Z
Distributions
Reverse Dependencies 1 direct, 0 indirect [details]
Downloads 523 total (9 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-09-04 [all 1 reports]

Readme for dormouse-uri-0.3.0.0

[back to package description]

Dormouse-Uri

Dormouse-Uri provides type safe handling of Uris and Urls.

Uri sytax is well defined according to RFC 3986, Dormouse-Uri parses and encodes Uris according to the syntax defined in this document.

We define Url as an absolute URI associated with web resources, the current version of Dormouse-Uri restricts Urls to the http and https schemes.

Dormouse-Uri has the following features:

  • The Uri/Url data types use Data.Text internally, this allows you to freely include percent-decoded characters which will be properly rendered when the Url/Uri is encoded.
  • Quasiquoters to allow safe construction of Uri/Urls from string literals.
  • DataKinds allow Urls to be restricted to the http or https schemes are the type level.
  • A UrlBuilder syntax to allow type-safe construction/concatenation of Urls from their components, e.g. path and query parameters.

Constructing Uris

{-# LANGUAGE QuasiQuotes #-}

import Dormouse.Uri
import Dormouse.Uri.QQ

telUri :: Uri
telUri = [uri|tel:+1-816-555-1212|]

mailtoUri :: Uri
mailtoUri = [uri|mailto:John.Doe@example.com|]

httpUri :: Uri
httpUri = [uri|http://haskell.org|]

Constructing Urls

You can construct Urls using the helper QuasiQuoters:

{-# LANGUAGE DataKinds #-}
{-# LANGUAGE QuasiQuotes #-}

import Dormouse.Url
import Dormouse.Url.QQ

githubHttpsUrl :: Url "https"
githubHttpsUrl = [https|https://github.com|]

githubHttpUrl :: Url "http"
githubHttpUrl = [http|http://github.com|]

githubAnyUrl :: AnyUrl
githubAnyUrl = [url|http://github.com|]

You can use the Url Builder syntax to modify an existing Url safely to include paths, adding the import:

import Dormouse.Url.Builder

To allow:

dormouseHttpsUrl :: Url "https"
dormouseHttpsUrl = githubHttpsUrl </> "TheInnerLight" </> "dormouse"

The Url will be constructed safely so that any characters that wouldn't normally be allowed in a Url path are percent-encoded before the url is resolved by Dormouse.

You can also handle query parameters using similar syntax:

searchUrl :: Url "https"
searchUrl = [https|https://google.com|] </> "search" ? "q" =: ("haskell" :: String)