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

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

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 are 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]

Properties

Versions	0.1.0.0, 0.1.0.1, 0.2.0.0, 0.2.1.1, 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-04T03:18:32Z

Modules

Dormouse
- Dormouse.Uri
  - Dormouse.Uri.Encode
  - Dormouse.Uri.Exception
  - Dormouse.Uri.QQ
  - Dormouse.Uri.RFC3986
- Dormouse.Url
  - Dormouse.Url.Builder
  - Dormouse.Url.Exception
  - Dormouse.Url.QQ

Downloads

dormouse-uri-0.2.1.1.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

philcurzon

For package maintainers and hackage trustees

edit package information

Readme for dormouse-uri-0.2.1.1

[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)