Modulemodern-uri-0.3.6.0Haskell2010

Text.URI

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

https://tools.ietf.org/html/rfc3986

This module is intended to be imported qualified, e.g.:

import Text.URI (URI)
import qualified Text.URI as URI

See also Text.URI.Lens for lens, prisms, and traversals; see Text.URI.QQ for quasi-quoters for compile-time validation of URIs and refined text components.

9 types
23 values

Packagemodern-uri-0.3.6.0
Exports32
LanguageHaskell2010
LicenceBSD-3-Clause
SourceURI.hs

Data types

12 declarations

datadata URI

Uniform resource identifier (URI) reference. We use refined Text (RText l) here because information is presented in human-readable form, i.e. percent-decoded, and thus it may contain Unicode characters.

Constructors

URI
- uriScheme :: Maybe (RText 'Scheme)
  URI scheme, if Nothing, then the URI reference is relative
- uriAuthority :: Either Bool Authority
  Authority component in Right or a Bool value in Left indicating if uriPath path is absolute (True) or relative (False); if we have an Authority component, then the path is necessarily absolute, see isPathAbsolute
  Note: before version 0.1.0.0 type of uriAuthority was Maybe Authority
- uriPath :: Maybe (Bool, NonEmpty (RText 'PathPiece))
  Nothing represents the empty path, while Just contains an indication Bool whether the path component has a trailing slash, and the collection of path pieces NonEmpty (RText PathPiece).
  Note: before version 0.2.0.0 type of uriPath was [RText PathPiece].
- uriQuery :: [QueryParam]
  Query parameters, RFC 3986 does not define the inner organization of query string, so we deconstruct it following RFC 1866 here
- uriFragment :: Maybe (RText 'Fragment)
  Fragment, without #

Instances10Eq, Data, Ord, Show, Generic, NFData, …

Eq URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
Data URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
Ord URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
Show URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
Generic URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
NFData URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
Hashable URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
Lift URIDefined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep URI = D1 ('MetaData "URI" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'False) (C1 ('MetaCons "URI" 'PrefixI 'True) ((S1 ('MetaSel ('Just "uriScheme") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe (RText 'Scheme))) :*: S1 ('MetaSel ('Just "uriAuthority") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Either Bool Authority))) :*: (S1 ('MetaSel ('Just "uriPath") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe (Bool, NonEmpty (RText 'PathPiece)))) :*: (S1 ('MetaSel ('Just "uriQuery") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [QueryParam]) :*: S1 ('MetaSel ('Just "uriFragment") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe (RText 'Fragment)))))))Defined in modern-uri-0.3.6.0 · Text.URI.Types

valuemkURI :: MonadThrow m => Text -> m URI

Construct a URI from Text. The input you pass to mkURI must be a valid URI as per RFC 3986, that is, its components should be percent-encoded where necessary. In case of parse failure ParseException is thrown.

This function uses the parser parser under the hood, which you can also use directly in a Megaparsec parser.

valuemkURIBs :: MonadThrow m => ByteString -> m URI

Construct a URI from ByteString. The input you pass to mkURIBs must be a valid URI as per RFC 3986, that is, its components should be percent-encoded where necessary. In case of parse failure ParseExceptionBs is thrown.

This function uses the parserBs parser under the hood, which you can also use directly in a Megaparsec parser.

valueemptyURI :: URI

The empty URI.

valuemakeAbsolute :: RText 'Scheme -> URI -> URI

Make a given URI reference absolute using the supplied RText Scheme if necessary.

valueisPathAbsolute :: URI -> Bool

Return True if path in a given URI is absolute.

valuerelativeTo

:: URI
Reference URI to make absolute
-> URI
Base URI
-> Maybe URI
The target URI

relativeTo reference base makes the reference URI absolute resolving it against the base URI.

If the base URI is not absolute itself (that is, it has no scheme), this function returns Nothing.

datadata Authority

Authority component of URI.

Constructors

Authority
- authUserInfo :: Maybe UserInfo
  User information
- authHost :: RText 'Host
  Host
- authPort :: Maybe Word
  Port number

Instances10Eq, Data, Ord, Show, Generic, NFData, …

Eq AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
Data AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
Ord AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
Show AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
Generic AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
NFData AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
Hashable AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
Lift AuthorityDefined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep Authority = D1 ('MetaData "Authority" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'False) (C1 ('MetaCons "Authority" 'PrefixI 'True) (S1 ('MetaSel ('Just "authUserInfo") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe UserInfo)) :*: (S1 ('MetaSel ('Just "authHost") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (RText 'Host)) :*: S1 ('MetaSel ('Just "authPort") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe Word)))))Defined in modern-uri-0.3.6.0 · Text.URI.Types

datadata UserInfo

User info as a combination of username and password.

Constructors

UserInfo
- uiUsername :: RText 'Username
  Username
- uiPassword :: Maybe (RText 'Password)
  Password, Nothing means that there was no : character in the user info string

Instances10Eq, Data, Ord, Show, Generic, NFData, …

Eq UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
Data UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
Ord UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
Show UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
Generic UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
NFData UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
Hashable UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
Lift UserInfoDefined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep UserInfo = D1 ('MetaData "UserInfo" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'False) (C1 ('MetaCons "UserInfo" 'PrefixI 'True) (S1 ('MetaSel ('Just "uiUsername") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (RText 'Username)) :*: S1 ('MetaSel ('Just "uiPassword") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe (RText 'Password)))))Defined in modern-uri-0.3.6.0 · Text.URI.Types

datadata QueryParam

Query parameter either in the form of flag or as a pair of key and value. A key cannot be empty, while a value can.

Constructors

QueryFlag (RText 'QueryKey)
Flag parameter
QueryParam (RText 'QueryKey) (RText 'QueryValue)
Key–value pair

Instances10Eq, Data, Ord, Show, Generic, NFData, …

Eq QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
Data QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
Ord QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
Show QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
Generic QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
NFData QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
Hashable QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
Lift QueryParamDefined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep QueryParam = D1 ('MetaData "QueryParam" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'False) (C1 ('MetaCons "QueryFlag" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (RText 'QueryKey))) :+: C1 ('MetaCons "QueryParam" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (RText 'QueryKey)) :*: S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (RText 'QueryValue))))Defined in modern-uri-0.3.6.0 · Text.URI.Types

newtypenewtype ParseException

Parse exception thrown by mkURI when a given Text value cannot be parsed as a URI.

Constructors

ParseException (ParseErrorBundle Text Void)
Arguments are: original input and parse error

Instances7Eq, Data, Show, Generic, Exception, NFData, …

Eq ParseExceptionDefined in modern-uri-0.3.6.0 · Text.URI.Types
Data ParseExceptionDefined in modern-uri-0.3.6.0 · Text.URI.Types
Show ParseExceptionDefined in modern-uri-0.3.6.0 · Text.URI.Types
Generic ParseExceptionDefined in modern-uri-0.3.6.0 · Text.URI.Types
Exception ParseExceptionDefined in modern-uri-0.3.6.0 · Text.URI.Types
NFData ParseExceptionDefined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep ParseException = D1 ('MetaData "ParseException" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'True) (C1 ('MetaCons "ParseException" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (ParseErrorBundle Text Void))))Defined in modern-uri-0.3.6.0 · Text.URI.Types

newtypenewtype ParseExceptionBs

Parse exception thrown by mkURIBs when a given ByteString value cannot be parsed as a URI.

Constructors

ParseExceptionBs (ParseErrorBundle ByteString Void)
Arguments are: original input and parse error

Instances7Eq, Data, Show, Generic, Exception, NFData, …

Eq ParseExceptionBsDefined in modern-uri-0.3.6.0 · Text.URI.Types
Data ParseExceptionBsDefined in modern-uri-0.3.6.0 · Text.URI.Types
Show ParseExceptionBsDefined in modern-uri-0.3.6.0 · Text.URI.Types
Generic ParseExceptionBsDefined in modern-uri-0.3.6.0 · Text.URI.Types
Exception ParseExceptionBsDefined in modern-uri-0.3.6.0 · Text.URI.Types
NFData ParseExceptionBsDefined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep ParseExceptionBs = D1 ('MetaData "ParseExceptionBs" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'True) (C1 ('MetaCons "ParseExceptionBs" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (ParseErrorBundle ByteString Void))))Defined in modern-uri-0.3.6.0 · Text.URI.Types

Refined text

12 declarations

Refined text values can only be created by using the smart constructors listed below, such as mkScheme. This eliminates the possibility of having an invalid component in URI which could invalidate the whole URI.

Note that the refined text RText type is labelled at the type level with RTextLabels, which see.

When an invalid Text value is passed to a smart constructor, it rejects it by throwing the RTextException. Remember that the Maybe datatype is also an instance of MonadThrow, and so one could as well use the smart constructors in the Maybe monad.

newtypenewtype RText (l :: RTextLabel)

Refined text labelled at the type level.

Instances17Lift, Eq, Data, Ord, Show, Generic, …

Typeable l => Lift (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Eq (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Typeable l => Data (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Ord (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Show (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Generic (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
NFData (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'Fragment)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'Host)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'Password)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'PathPiece)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'QueryKey)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'QueryValue)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'Scheme)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Arbitrary (RText 'Username)Defined in modern-uri-0.3.6.0 · Text.URI.Types
Hashable (RText l)Defined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep (RText l) = D1 ('MetaData "RText" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'True) (C1 ('MetaCons "RText" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)))Defined in modern-uri-0.3.6.0 · Text.URI.Types

datadata RTextLabel

Refined text labels.

Constructors

Scheme
See mkScheme
Host
See mkHost
Username
See mkUsername
Password
See mkPassword
PathPiece
See mkPathPiece
QueryKey
See mkQueryKey
QueryValue
See mkQueryValue
Fragment
See mkFragment

Instances6Eq, Data, Ord, Show, Generic, Rep

Eq RTextLabelDefined in modern-uri-0.3.6.0 · Text.URI.Types
Data RTextLabelDefined in modern-uri-0.3.6.0 · Text.URI.Types
Ord RTextLabelDefined in modern-uri-0.3.6.0 · Text.URI.Types
Show RTextLabelDefined in modern-uri-0.3.6.0 · Text.URI.Types
Generic RTextLabelDefined in modern-uri-0.3.6.0 · Text.URI.Types
type Rep RTextLabel = D1 ('MetaData "RTextLabel" "Text.URI.Types" "modern-uri-0.3.6.0-38unqINNGnZ4tnObMjfOTS" 'False) (((C1 ('MetaCons "Scheme" 'PrefixI 'False) U1 :+: C1 ('MetaCons "Host" 'PrefixI 'False) U1) :+: (C1 ('MetaCons "Username" 'PrefixI 'False) U1 :+: C1 ('MetaCons "Password" 'PrefixI 'False) U1)) :+: ((C1 ('MetaCons "PathPiece" 'PrefixI 'False) U1 :+: C1 ('MetaCons "QueryKey" 'PrefixI 'False) U1) :+: (C1 ('MetaCons "QueryValue" 'PrefixI 'False) U1 :+: C1 ('MetaCons "Fragment" 'PrefixI 'False) U1)))Defined in modern-uri-0.3.6.0 · Text.URI.Types

valuemkScheme :: MonadThrow m => Text -> m (RText 'Scheme)

Lift a Text value into RText Scheme.

Scheme names consist of a sequence of characters beginning with a letter and followed by any combination of letters, digits, plus "+", period ".", or hyphen "-".

This smart constructor performs normalization of valid schemes by converting them to lower case.

valuemkHost :: MonadThrow m => Text -> m (RText 'Host)

Lift a Text value into RText Host.

The host sub-component of authority is identified by an IP literal encapsulated within square brackets, an IPv4 address in dotted-decimal form, or a registered name.

This smart constructor performs normalization of valid hosts by converting them to lower case.

valuemkUsername :: MonadThrow m => Text -> m (RText 'Username)

Lift a Text value into RText Username.