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

Ord Scheme

Show Scheme

Generic Scheme

Typeable * Scheme

type Rep Scheme

newtype Host

Constructors

Host

Fields

hostBS :: ByteString

Instances

Eq Host

Ord Host

Show Host

Generic Host

Typeable * Host

type Rep Host

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

Ord Port

Show Port

Generic Port

Typeable * Port

type Rep Port

data Authority

Constructors

Authority

Fields

authorityUserInfo :: Maybe UserInfo

authorityHost :: Host

authorityPort :: Maybe Port

Instances

Eq Authority

Ord Authority

Show Authority

Generic Authority

Typeable * Authority

type Rep Authority

data UserInfo

Constructors

UserInfo

Fields

uiUsername :: ByteString

uiPassword :: ByteString

Instances

Eq UserInfo

Ord UserInfo

Show UserInfo

Generic UserInfo

Typeable * UserInfo

type Rep UserInfo

newtype Query

Constructors

Query

Fields

queryPairs :: [(ByteString, ByteString)]

Instances

Eq Query

Ord Query

Show Query

Generic Query

Monoid Query

Typeable * Query

type Rep Query

data URI

Constructors

URI

Fields

uriScheme :: Scheme

uriAuthority :: Maybe Authority

uriPath :: ByteString

uriQuery :: Query

uriFragment :: Maybe ByteString

URI fragment. Does not include the #

Instances

Eq URI

Ord URI

Show URI

Generic URI

Typeable * URI

type Rep URI

data RelativeRef

Constructors

RelativeRef

Fields

rrAuthority :: Maybe Authority

rrPath :: ByteString

rrQuery :: Query

rrFragment :: Maybe ByteString

URI fragment. Does not include the #

Instances

Eq RelativeRef

Ord RelativeRef

Show RelativeRef

Generic RelativeRef

Typeable * RelativeRef

type Rep RelativeRef

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

Read SchemaError

Show SchemaError

Generic SchemaError

Typeable * SchemaError

type Rep SchemaError

data URIParseError

Constructors

MalformedScheme SchemaError

MalformedUserInfo

MalformedQuery

MalformedFragment

MalformedHost

MalformedPort

MalformedPath

OtherError String

Catchall for unpredictable errors

Instances

Eq URIParseError

Read URIParseError

Show URIParseError

Generic URIParseError

Typeable * URIParseError

type Rep URIParseError

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

Parsing

parseURI :: URIParserOptions -> ByteString -> Either URIParseError URI

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 RelativeRef

Like parseURI, but do not parse scheme.

uriParser :: URIParserOptions -> Parser URI

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

relativeRefParser :: URIParserOptions -> Parser RelativeRef

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

Serializing

serializeURI :: URI -> Builder

URI Serializer

Serialize a URI into a Builder.

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

>>> BB.toLazyByteString $ serializeURI $ 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"

serializeURI' :: URI -> ByteString

Like serializeURI, with conversion into a strict ByteString.

serializeRelativeRef :: RelativeRef -> Builder

Like serializeURI, but do not render scheme.

serializeRelativeRef' :: URI -> ByteString

Like serializeRelativeRef, with conversion into a strict 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

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 URI

uriSchemeL :: Lens' URI Scheme

uriAuthorityL :: Lens' URI (Maybe Authority)

uriPathL :: Lens' URI ByteString

uriQueryL :: Lens' URI Query

uriFragmentL :: Lens' URI (Maybe ByteString)

Lenses over RelativeRef

rrAuthorityL :: Lens' RelativeRef (Maybe Authority)

rrPathL :: Lens' RelativeRef ByteString

rrQueryL :: Lens' RelativeRef Query

rrFragmentL :: Lens' RelativeRef (Maybe ByteString)

Lenses over URIParserOptions

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