URI.ByteString

URI.ByteString aims to be an RFC3986 compliant URI parser that uses efficient ByteStrings for parsing and representing the data. This module provides a URI datatype as well as a parser and serializer.

Note that this library is an early release and may have issues. It is currently being used in production and no issues have been encountered, however. Please report any issues encountered to the issue tracker.

This module also provides analogs to Lens over the various types in this library. These are written in a generic way to avoid a dependency on any particular lens library. You should be able to use these with a number of packages including lens and lens-family-core.

URI-related types

newtype Scheme

Required first component to referring to a specification for the remainder of the URI's components, e.g. "http" or "https"

Constructors

Scheme

Fields

• schemeBS :: ByteString

Instances

Eq Scheme

Methods

(==) :: Scheme -> Scheme -> Bool

(/=) :: Scheme -> Scheme -> Bool

Ord Scheme

Methods

compare :: Scheme -> Scheme -> Ordering

(<) :: Scheme -> Scheme -> Bool

(<=) :: Scheme -> Scheme -> Bool

(>) :: Scheme -> Scheme -> Bool

(>=) :: Scheme -> Scheme -> Bool

max :: Scheme -> Scheme -> Scheme

min :: Scheme -> Scheme -> Scheme

Show Scheme

Methods

showsPrec :: Int -> Scheme -> ShowS

show :: Scheme -> String

showList :: [Scheme] -> ShowS

Generic Scheme

Associated Types

type Rep Scheme :: * -> *

Methods

from :: Scheme -> Rep Scheme x

to :: Rep Scheme x -> Scheme

Lift Scheme

Methods

lift :: Scheme -> Q Exp

type Rep Scheme

type Rep Scheme = D1 * (MetaData "Scheme" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" True) (C1 * (MetaCons "Scheme" PrefixI True) (S1 * (MetaSel (Just Symbol "schemeBS") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * ByteString)))

newtype Host

Constructors

Host

Fields

• hostBS :: ByteString

Instances

Eq Host

Methods

(==) :: Host -> Host -> Bool

(/=) :: Host -> Host -> Bool

Ord Host

Methods

compare :: Host -> Host -> Ordering

(<) :: Host -> Host -> Bool

(<=) :: Host -> Host -> Bool

(>) :: Host -> Host -> Bool

(>=) :: Host -> Host -> Bool

max :: Host -> Host -> Host

min :: Host -> Host -> Host

Show Host

Methods

showsPrec :: Int -> Host -> ShowS

show :: Host -> String

showList :: [Host] -> ShowS

Generic Host

Associated Types

type Rep Host :: * -> *

Methods

from :: Host -> Rep Host x

to :: Rep Host x -> Host

Lift Host

Methods

lift :: Host -> Q Exp

type Rep Host

type Rep Host = D1 * (MetaData "Host" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" True) (C1 * (MetaCons "Host" PrefixI True) (S1 * (MetaSel (Just Symbol "hostBS") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * ByteString)))

newtype Port

While some libraries have chosen to limit this to a Word16, the spec only specifies that the string be comprised of digits.

Constructors

Port

Fields

• portNumber :: Int

Instances

Eq Port

Methods

(==) :: Port -> Port -> Bool

(/=) :: Port -> Port -> Bool

Ord Port

Methods

compare :: Port -> Port -> Ordering

(<) :: Port -> Port -> Bool

(<=) :: Port -> Port -> Bool

(>) :: Port -> Port -> Bool

(>=) :: Port -> Port -> Bool

max :: Port -> Port -> Port

min :: Port -> Port -> Port

Show Port

Methods

showsPrec :: Int -> Port -> ShowS

show :: Port -> String

showList :: [Port] -> ShowS

Generic Port

Associated Types

type Rep Port :: * -> *

Methods

from :: Port -> Rep Port x

to :: Rep Port x -> Port

Lift Port

Methods

lift :: Port -> Q Exp

type Rep Port

type Rep Port = D1 * (MetaData "Port" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" True) (C1 * (MetaCons "Port" PrefixI True) (S1 * (MetaSel (Just Symbol "portNumber") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Int)))

data Authority

Constructors

Authority

Fields

• authorityUserInfo :: Maybe UserInfo
• authorityHost :: Host
• authorityPort :: Maybe Port

Instances

Eq Authority

Methods

(==) :: Authority -> Authority -> Bool

(/=) :: Authority -> Authority -> Bool

Ord Authority

Methods

compare :: Authority -> Authority -> Ordering

(<) :: Authority -> Authority -> Bool

(<=) :: Authority -> Authority -> Bool

(>) :: Authority -> Authority -> Bool

(>=) :: Authority -> Authority -> Bool

max :: Authority -> Authority -> Authority

min :: Authority -> Authority -> Authority

Show Authority

Methods

showsPrec :: Int -> Authority -> ShowS

show :: Authority -> String

showList :: [Authority] -> ShowS

Generic Authority

Associated Types

type Rep Authority :: * -> *

Methods

from :: Authority -> Rep Authority x

to :: Rep Authority x -> Authority

Lift Authority

Methods

lift :: Authority -> Q Exp

type Rep Authority

type Rep Authority = D1 * (MetaData "Authority" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" False) (C1 * (MetaCons "Authority" PrefixI True) ((:*:) * (S1 * (MetaSel (Just Symbol "authorityUserInfo") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (Maybe UserInfo))) ((:*:) * (S1 * (MetaSel (Just Symbol "authorityHost") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * Host)) (S1 * (MetaSel (Just Symbol "authorityPort") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (Maybe Port))))))

data UserInfo

Constructors

UserInfo

Fields

• uiUsername :: ByteString
• uiPassword :: ByteString

Instances

Eq UserInfo

Methods

(==) :: UserInfo -> UserInfo -> Bool

(/=) :: UserInfo -> UserInfo -> Bool

Ord UserInfo

Methods

compare :: UserInfo -> UserInfo -> Ordering

(<) :: UserInfo -> UserInfo -> Bool

(<=) :: UserInfo -> UserInfo -> Bool

(>) :: UserInfo -> UserInfo -> Bool

(>=) :: UserInfo -> UserInfo -> Bool

max :: UserInfo -> UserInfo -> UserInfo

min :: UserInfo -> UserInfo -> UserInfo

Show UserInfo

Methods

showsPrec :: Int -> UserInfo -> ShowS

show :: UserInfo -> String

showList :: [UserInfo] -> ShowS

Generic UserInfo

Associated Types

type Rep UserInfo :: * -> *

Methods

from :: UserInfo -> Rep UserInfo x

to :: Rep UserInfo x -> UserInfo

Lift UserInfo

Methods

lift :: UserInfo -> Q Exp

type Rep UserInfo

type Rep UserInfo = D1 * (MetaData "UserInfo" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" False) (C1 * (MetaCons "UserInfo" PrefixI True) ((:*:) * (S1 * (MetaSel (Just Symbol "uiUsername") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * ByteString)) (S1 * (MetaSel (Just Symbol "uiPassword") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * ByteString))))

newtype Query

Constructors

Query

Fields

• queryPairs :: [(ByteString, ByteString)]

Instances

Eq Query

Methods

(==) :: Query -> Query -> Bool

(/=) :: Query -> Query -> Bool

Ord Query

Methods

compare :: Query -> Query -> Ordering

(<) :: Query -> Query -> Bool

(<=) :: Query -> Query -> Bool

(>) :: Query -> Query -> Bool

(>=) :: Query -> Query -> Bool

max :: Query -> Query -> Query

min :: Query -> Query -> Query

Show Query

Methods

showsPrec :: Int -> Query -> ShowS

show :: Query -> String

showList :: [Query] -> ShowS

Generic Query

Associated Types

type Rep Query :: * -> *

Methods

from :: Query -> Rep Query x

to :: Rep Query x -> Query

Semigroup Query

Methods

(<>) :: Query -> Query -> Query

sconcat :: NonEmpty Query -> Query

stimes :: Integral b => b -> Query -> Query

Monoid Query

Methods

mempty :: Query

mappend :: Query -> Query -> Query

mconcat :: [Query] -> Query

Lift Query

Methods

lift :: Query -> Q Exp

type Rep Query

type Rep Query = D1 * (MetaData "Query" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" True) (C1 * (MetaCons "Query" PrefixI True) (S1 * (MetaSel (Just Symbol "queryPairs") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * [(ByteString, ByteString)])))

data URIRef a where

Note: URI fragment does not include the #

Constructors

URI :: {..} -> URIRef Absolute

Fields

• uriScheme :: Scheme
• uriAuthority :: Maybe Authority
• uriPath :: ByteString
• uriQuery :: Query
• uriFragment :: Maybe ByteString

RelativeRef :: {..} -> URIRef Relative

Fields

• rrAuthority :: Maybe Authority
• rrPath :: ByteString
• rrQuery :: Query
• rrFragment :: Maybe ByteString

Instances

Eq (URIRef a)

Methods

(==) :: URIRef a -> URIRef a -> Bool

(/=) :: URIRef a -> URIRef a -> Bool

Ord (URIRef a)

Methods

compare :: URIRef a -> URIRef a -> Ordering

(<) :: URIRef a -> URIRef a -> Bool

(<=) :: URIRef a -> URIRef a -> Bool

(>) :: URIRef a -> URIRef a -> Bool

(>=) :: URIRef a -> URIRef a -> Bool

max :: URIRef a -> URIRef a -> URIRef a

min :: URIRef a -> URIRef a -> URIRef a

Show (URIRef a)

Methods

showsPrec :: Int -> URIRef a -> ShowS

show :: URIRef a -> String

showList :: [URIRef a] -> ShowS

Lift (URIRef a)

Methods

lift :: URIRef a -> Q Exp

data Absolute

Instances

Lift Absolute

Methods

lift :: Absolute -> Q Exp

data Relative

Instances

Lift Relative

Methods

lift :: Relative -> Q Exp

data SchemaError

URI Parser Types

Constructors

NonAlphaLeading

Scheme must start with an alphabet character

InvalidChars

Subsequent characters in the schema were invalid

MissingColon

Schemas must be followed by a colon

Instances

Eq SchemaError

Methods

(==) :: SchemaError -> SchemaError -> Bool

(/=) :: SchemaError -> SchemaError -> Bool

Read SchemaError

Methods

readsPrec :: Int -> ReadS SchemaError

readList :: ReadS [SchemaError]

readPrec :: ReadPrec SchemaError

readListPrec :: ReadPrec [SchemaError]

Show SchemaError

Methods

showsPrec :: Int -> SchemaError -> ShowS

show :: SchemaError -> String

showList :: [SchemaError] -> ShowS

Generic SchemaError

Associated Types

type Rep SchemaError :: * -> *

Methods

from :: SchemaError -> Rep SchemaError x

to :: Rep SchemaError x -> SchemaError

type Rep SchemaError

type Rep SchemaError = D1 * (MetaData "SchemaError" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" False) ((:+:) * (C1 * (MetaCons "NonAlphaLeading" PrefixI False) (U1 *)) ((:+:) * (C1 * (MetaCons "InvalidChars" PrefixI False) (U1 *)) (C1 * (MetaCons "MissingColon" PrefixI False) (U1 *))))

data URIParseError

Constructors

MalformedScheme SchemaError

MalformedUserInfo

MalformedQuery

MalformedFragment

MalformedHost

MalformedPort

MalformedPath

OtherError String

Catchall for unpredictable errors

Instances

Eq URIParseError

Methods

(==) :: URIParseError -> URIParseError -> Bool

(/=) :: URIParseError -> URIParseError -> Bool

Read URIParseError

Methods

readsPrec :: Int -> ReadS URIParseError

readList :: ReadS [URIParseError]

readPrec :: ReadPrec URIParseError

readListPrec :: ReadPrec [URIParseError]

Show URIParseError

Methods

showsPrec :: Int -> URIParseError -> ShowS

show :: URIParseError -> String

showList :: [URIParseError] -> ShowS

Generic URIParseError

Associated Types

type Rep URIParseError :: * -> *

Methods

from :: URIParseError -> Rep URIParseError x

to :: Rep URIParseError x -> URIParseError

type Rep URIParseError

type Rep URIParseError = D1 * (MetaData "URIParseError" "URI.ByteString.Types" "uri-bytestring-0.3.1.1-BZVIM4BgX7XLjOTOhGNd2x" False) ((:+:) * ((:+:) * ((:+:) * (C1 * (MetaCons "MalformedScheme" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * SchemaError))) (C1 * (MetaCons "MalformedUserInfo" PrefixI False) (U1 *))) ((:+:) * (C1 * (MetaCons "MalformedQuery" PrefixI False) (U1 *)) (C1 * (MetaCons "MalformedFragment" PrefixI False) (U1 *)))) ((:+:) * ((:+:) * (C1 * (MetaCons "MalformedHost" PrefixI False) (U1 *)) (C1 * (MetaCons "MalformedPort" PrefixI False) (U1 *))) ((:+:) * (C1 * (MetaCons "MalformedPath" PrefixI False) (U1 *)) (C1 * (MetaCons "OtherError" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * String))))))

data URIParserOptions

Options for the parser. You will probably want to use either "strictURIParserOptions" or "laxURIParserOptions"

Constructors

URIParserOptions

Fields

• upoValidQueryChar :: Word8 -> Bool

strictURIParserOptions :: URIParserOptions

Strict URI Parser config. Follows RFC3986 as-specified. Use this if you can be certain that your URIs are properly encoded or if you want parsing to fail if they deviate from the spec at all.

laxURIParserOptions :: URIParserOptions

Lax URI Parser config. Use this if you you want to handle common deviations from the spec gracefully.

• Allows non-encoded [ and ] in query string

data URINormalizationOptions

Constructors

URINormalizationOptions

Fields

• unoDowncaseScheme :: Bool

  hTtP -> http

• unoDowncaseHost :: Bool

  eXaMpLe.org -> example.org

• unoDropDefPort :: Bool

  If the scheme is known and the port is the default (e.g. 80 for http) it is removed.

• unoSlashEmptyPath :: Bool

  If the path is empty, set it to /

• unoDropExtraSlashes :: Bool

  Rewrite path from /foo//bar///baz to /foo/bar/baz

• unoSortParameters :: Bool

  Sorts parameters by parameter name

• unoRemoveDotSegments :: Bool

  Remove dot segments as per RFC3986 Section 5.2.4

• unoDefaultPorts :: Map Scheme Port

  Map of known schemes to their default ports. Used when unoDropDefPort is enabled.

Instances

Eq URINormalizationOptions

Methods

(==) :: URINormalizationOptions -> URINormalizationOptions -> Bool

(/=) :: URINormalizationOptions -> URINormalizationOptions -> Bool

Show URINormalizationOptions

Methods

showsPrec :: Int -> URINormalizationOptions -> ShowS

show :: URINormalizationOptions -> String

showList :: [URINormalizationOptions] -> ShowS

noNormalization :: URINormalizationOptions

All normalization options disabled

rfc3986Normalization :: URINormalizationOptions

Only normalizations deemed appropriate for all protocols by RFC3986 enabled, namely:

• Downcase Scheme
• Downcase Host
• Remove Dot Segments

httpNormalization :: URINormalizationOptions

The same as rfc3986Normalization but with additional enabled features if you're working with HTTP URIs:

• Drop Default Port (with httpDefaultPorts)
• Drop Extra Slashes

aggressiveNormalization :: URINormalizationOptions

All options enabled

httpDefaultPorts :: Map Scheme Port

The set of known default ports to schemes. Currently only contains http/80 and https/443. Feel free to extend it if needed with unoDefaultPorts.

Operations

toAbsolute :: Scheme -> URIRef a -> URIRef Absolute

toAbsolute scheme ref converts ref to an absolute URI. If ref is already absolute, then it is unchanged.

Parsing

parseURI :: URIParserOptions -> ByteString -> Either URIParseError (URIRef Absolute)

Parse a strict ByteString into a URI or an error.

Example:

>>> parseURI strictURIParserOptions "http://www.example.org/foo?bar=baz#quux"
Right (URI {uriScheme = Scheme {schemeBS = "http"}, uriAuthority = Just (Authority {authorityUserInfo = Nothing, authorityHost = Host {hostBS = "www.example.org"}, authorityPort = Nothing}), uriPath = "/foo", uriQuery = Query {queryPairs = [("bar","baz")]}, uriFragment = Just "quux"})

>>> parseURI strictURIParserOptions "$$$$://badurl.example.org"
Left (MalformedScheme NonAlphaLeading)

There are some urls that you'll encounter which defy the spec, such as those with square brackets in the query string. If you must be able to parse those, you can use "laxURIParserOptions" or specify your own

>>> parseURI strictURIParserOptions "http://www.example.org/foo?bar[]=baz"
Left MalformedQuery

>>> parseURI laxURIParserOptions "http://www.example.org/foo?bar[]=baz"
Right (URI {uriScheme = Scheme {schemeBS = "http"}, uriAuthority = Just (Authority {authorityUserInfo = Nothing, authorityHost = Host {hostBS = "www.example.org"}, authorityPort = Nothing}), uriPath = "/foo", uriQuery = Query {queryPairs = [("bar[]","baz")]}, uriFragment = Nothing})

>>> let myLaxOptions = URIParserOptions { upoValidQueryChar = liftA2 (||) (upoValidQueryChar strictURIParserOptions) (inClass "[]")}
>>> parseURI myLaxOptions "http://www.example.org/foo?bar[]=baz"
Right (URI {uriScheme = Scheme {schemeBS = "http"}, uriAuthority = Just (Authority {authorityUserInfo = Nothing, authorityHost = Host {hostBS = "www.example.org"}, authorityPort = Nothing}), uriPath = "/foo", uriQuery = Query {queryPairs = [("bar[]","baz")]}, uriFragment = Nothing})

parseRelativeRef :: URIParserOptions -> ByteString -> Either URIParseError (URIRef Relative)

Like parseURI, but do not parse scheme.

uriParser :: URIParserOptions -> Parser (URIRef Absolute)

Underlying attoparsec parser. Useful for composing with your own parsers.

relativeRefParser :: URIParserOptions -> Parser (URIRef Relative)

Underlying attoparsec parser. Useful for composing with your own parsers.

Serializing

serializeURIRef :: URIRef a -> Builder

URI Serializer

Serialize a URI reference into a Builder.

Example of serializing + converting to a lazy Data.ByteString.Lazy.ByteString:

>>> BB.toLazyByteString $ serializeURIRef $ URI {uriScheme = Scheme {schemeBS = "http"}, uriAuthority = Just (Authority {authorityUserInfo = Nothing, authorityHost = Host {hostBS = "www.example.org"}, authorityPort = Nothing}), uriPath = "/foo", uriQuery = Query {queryPairs = [("bar","baz")]}, uriFragment = Just "quux"}
"http://www.example.org/foo?bar=baz#quux"

serializeURIRef' :: URIRef a -> ByteString

Like serializeURIRef, with conversion into a strict ByteString.

Normalized Serialization

normalizeURIRef :: URINormalizationOptions -> URIRef a -> Builder

Similar to serializeURIRef but performs configurable degrees of URI normalization. If your goal is the fastest serialization speed possible, serializeURIRef will be fine. If you intend on comparing URIs (say for caching purposes), you'll want to use this.

normalizeURIRef' :: URINormalizationOptions -> URIRef a -> ByteString

Low level utility functions

urlDecode

Arguments

:: Bool

Whether to decode + to ' '

-> ByteString

-> ByteString

This function was extracted from the http-types package. The license can be found in licenseshttp-typesLICENSE

urlDecodeQuery :: ByteString -> ByteString

ByteString Utilities

Decoding specifically for the query string, which decodes + as space. Shorthand for urlDecode True

urlEncodeQuery :: ByteString -> Builder

Encode a ByteString for use in the query section of a URL

urlEncodePath :: ByteString -> Builder

Encode a ByteString for use in the path section of a URL

urlEncode :: [Word8] -> ByteString -> Builder

Percent-encoding for URLs. Specify a list of additional unreserved characters to permit.

Lenses

Lenses over Scheme

schemeBSL :: Lens' Scheme ByteString

Lenses over Host

hostBSL :: Lens' Host ByteString

Lenses over Port

portNumberL :: Lens' Port Int

Lenses over Authority

authorityUserInfoL :: Lens' Authority (Maybe UserInfo)

authorityHostL :: Lens' Authority Host

authorityPortL :: Lens' Authority (Maybe Port)

Lenses over UserInfo

uiUsernameL :: Lens' UserInfo ByteString

uiPasswordL :: Lens' UserInfo ByteString

Lenses over Query

queryPairsL :: Lens' Query [(ByteString, ByteString)]

Lenses over URIRef

uriSchemeL :: Lens' (URIRef Absolute) Scheme

authorityL :: Lens' (URIRef a) (Maybe Authority)

pathL :: Lens' (URIRef a) ByteString

queryL :: Lens' (URIRef a) Query

fragmentL :: Lens' (URIRef a) (Maybe ByteString)

Lenses over URIParserOptions

upoValidQueryCharL :: Lens' URIParserOptions (Word8 -> Bool)

Deprecated

type URI = URIRef Absolute

type RelativeRef = URIRef Relative

serializeURI :: URIRef Absolute -> Builder

Deprecated: Use serializeURIRef instead

Serialize a URI into a Builder.

serializeURI' :: URIRef Absolute -> ByteString

Deprecated: Use serializeURIRef' instead

Like serializeURI, with conversion into a strict ByteString.

serializeRelativeRef :: URIRef Relative -> Builder

Deprecated: Use serializeURIRef instead

Like serializeURI, but do not render scheme.

serializeRelativeRef' :: URIRef Relative -> ByteString

Deprecated: Use serializeURIRef' instead

Like serializeRelativeRef, with conversion into a strict ByteString.

uriAuthorityL :: Lens' URI (Maybe Authority)

Deprecated: Use authorityL instead

uriPathL :: Lens' URI ByteString

Deprecated: Use pathL instead

uriQueryL :: Lens' URI Query

Deprecated: Use queryL instead

uriFragmentL :: Lens' URI (Maybe ByteString)

Deprecated: Use fragmentL instead

rrAuthorityL :: Lens' RelativeRef (Maybe Authority)

Deprecated: Use authorityL instead

rrPathL :: Lens' RelativeRef ByteString

Deprecated: Use pathL instead

rrQueryL :: Lens' RelativeRef Query

Deprecated: Use queryL instead

rrFragmentL :: Lens' RelativeRef (Maybe ByteString)

Deprecated: Use fragmentL instead