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

URI.ByteString

Contents

URI-related types
Parsing
Serializing

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.

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 getScheme :: ByteString

Instances

Eq Scheme
Show Scheme
Generic Scheme
Typeable * Scheme
type Rep Scheme

newtype Host Source

Constructors

Host
Fields getHost :: ByteString

Instances

Eq 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 getPort :: Int

Instances

Eq 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
Show Authority
Generic Authority
Typeable * Authority
type Rep Authority

data UserInfo Source

Constructors

UserInfo
Fields uiUsername :: ByteString uiPassword :: ByteString

Instances

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

newtype Query Source

Constructors

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

Instances

Eq Query
Show Query
Monoid Query

data URI Source

Constructors

URI
Fields uriScheme :: Scheme uriAuthority :: Maybe Authority uriPath :: ByteString uriQuery :: Query uriFragment :: Maybe ByteString URI fragment. Does not include the #

Instances

Eq URI
Show URI
Generic URI
Typeable * URI
type Rep URI

data SchemaError Source

URI Parser

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

Parsing

parseURI :: URIParserOptions -> ByteString -> Either URIParseError URI 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 {getScheme = "http"}, uriAuthority = Just (Authority {authorityUserInfo = Nothing, authorityHost = Host {getHost = "www.example.org"}, authorityPort = Nothing}), uriPath = "/foo", uriQuery = Query {getQuery = [("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 {getScheme = "http"}, uriAuthority = Just (Authority {authorityUserInfo = Nothing, authorityHost = Host {getHost = "www.example.org"}, authorityPort = Nothing}), uriPath = "/foo", uriQuery = Query {getQuery = [("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 {getScheme = "http"}, uriAuthority = Just (Authority {authorityUserInfo = Nothing, authorityHost = Host {getHost = "www.example.org"}, authorityPort = Nothing}), uriPath = "/foo", uriQuery = Query {getQuery = [("bar[]","baz")]}, uriFragment = Nothing})

Serializing

serializeURI :: URI -> Builder Source

URI Serializer

Serialize a URI into a strict ByteString Example:

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