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
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
Ord Scheme
Show Scheme
Generic Scheme
Typeable * Scheme
type Rep Scheme

newtype Host Source

Constructors

Host
Fields hostBS :: ByteString

Instances

Eq Host
Ord Host
Show Host
Generic Host
Typeable * Host
type Rep Host

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
Ord Port
Show Port
Generic Port
Typeable * Port
type Rep Port

data Authority Source

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 Source

Constructors

UserInfo
Fields uiUsername :: ByteString uiPassword :: ByteString

Instances

Eq UserInfo
Ord UserInfo
Show UserInfo
Generic UserInfo
Typeable * UserInfo
type Rep UserInfo

newtype Query Source

Constructors

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

Instances

Eq Query
Ord Query
Show Query
Generic Query
Monoid Query
Typeable * Query
type Rep Query

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)
Ord (URIRef a)
Show (URIRef a)
Typeable (* -> *) URIRef

data Absolute Source

Instances

Typeable * Absolute

data Relative Source

Instances

Typeable * Relative

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

data URIParseError Source

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

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.