Copyright	(c) Soostone Inc., 2014-2015 Michael Xavier, 2014-2015
License	BSD3
Maintainer	michael.xavier@soostone.com
Stability	experimental
Safe Haskell	None
Language	Haskell2010

URI.ByteString

Contents

URI-related types
Operations
Parsing
Serializing
- Normalized Serialization
Low level utility functions
Lenses

Description

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.

Synopsis

URI-related types

newtype Scheme Source

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 Source
Ord Scheme Source
Show Scheme Source
Generic Scheme Source
Lift Scheme Source
type Rep Scheme Source

newtype Host Source

Constructors

Host
Fields hostBS :: ByteString

Instances

Eq Host Source
Ord Host Source
Show Host Source
Generic Host Source
Lift Host Source
type Rep Host Source

newtype Port Source

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 Source
Ord Port Source
Show Port Source
Generic Port Source
Lift Port Source
type Rep Port Source

data Authority Source

Constructors

Authority
Fields authorityUserInfo :: Maybe UserInfo authorityHost :: Host authorityPort :: Maybe Port

Instances

Eq Authority Source
Ord Authority Source
Show Authority Source
Generic Authority Source
Lift Authority Source
type Rep Authority Source

data UserInfo Source

Constructors

UserInfo
Fields uiUsername :: ByteString uiPassword :: ByteString

Instances

Eq UserInfo Source
Ord UserInfo Source
Show UserInfo Source
Generic UserInfo Source
Lift UserInfo Source
type Rep UserInfo Source

newtype Query Source

Constructors

Query
Fields queryPairs :: [(ByteString, ByteString)]

Instances

Eq Query Source
Ord Query Source
Show Query Source
Generic Query Source
Monoid Query Source
Lift Query Source
type Rep Query Source

data URIRef a where Source

Note: URI fragment does not include the #

Constructors

URI :: Scheme -> Maybe Authority -> ByteString -> Query -> Maybe ByteString -> URIRef Absolute
Fields uriScheme :: Scheme uriAuthority :: Maybe Authority uriPath :: ByteString uriQuery :: Query uriFragment :: Maybe ByteString
RelativeRef :: Maybe Authority -> ByteString -> Query -> Maybe ByteString -> URIRef Relative
Fields rrAuthority :: Maybe Authority rrPath :: ByteString rrQuery :: Query rrFragment :: Maybe ByteString

Instances

Eq (URIRef a) Source
Ord (URIRef a) Source
Show (URIRef a) Source
Lift a0 => Lift (URIRef a) Source

data Absolute Source

Instances

Lift Absolute Source

data Relative Source

Instances

Lift Relative Source

data SchemaError Source

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 Source
Read SchemaError Source
Show SchemaError Source
Generic SchemaError Source
type Rep SchemaError Source

data URIParseError Source

Constructors

MalformedScheme SchemaError
MalformedUserInfo
MalformedQuery
MalformedFragment
MalformedHost
MalformedPort
MalformedPath
OtherError String	Catchall for unpredictable errors

Instances

Eq URIParseError Source
Read URIParseError Source
Show URIParseError Source
Generic URIParseError Source
type Rep URIParseError Source

data URIParserOptions Source

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

Constructors

URIParserOptions
Fields upoValidQueryChar :: Word8 -> Bool

strictURIParserOptions :: URIParserOptions Source

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 Source

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 Source

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 Source
Show URINormalizationOptions Source

noNormalization :: URINormalizationOptions Source

All normalization options disabled

rfc3986Normalization :: URINormalizationOptions Source

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

Downcase Scheme
Downcase Host
Remove Dot Segments

httpNormalization :: URINormalizationOptions Source

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 Source

All options enabled

httpDefaultPorts :: Map Scheme Port Source

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 Source

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

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

Like parseURI, but do not parse scheme.

uriParser :: URIParserOptions -> Parser (URIRef Absolute) Source

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

relativeRefParser :: URIParserOptions -> Parser (URIRef Relative) Source

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

Serializing

serializeURIRef :: URIRef a -> Builder Source

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 Source

Like serializeURIRef, with conversion into a strict ByteString.

Normalized Serialization

normalizeURIRef :: URINormalizationOptions -> URIRef a -> Builder Source

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 Source