uri-bytestring-0.3.2.1: Haskell URI parsing as ByteStrings

Copyright(c) Soostone Inc. 2014-2015
Michael Xavier 2014-2015
LicenseBSD3
Maintainermichael.xavier@soostone.com
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

URI.ByteString

Contents

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

Instances
Eq Scheme Source # 
Instance details

Defined in URI.ByteString.Types

Methods

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

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

Ord Scheme Source # 
Instance details

Defined in URI.ByteString.Types

Show Scheme Source # 
Instance details

Defined in URI.ByteString.Types

Generic Scheme Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep Scheme :: * -> * #

Methods

from :: Scheme -> Rep Scheme x #

to :: Rep Scheme x -> Scheme #

Lift Scheme Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: Scheme -> Q Exp #

type Rep Scheme Source # 
Instance details

Defined in URI.ByteString.Types

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

newtype Host Source #

Constructors

Host 

Fields

Instances
Eq Host Source # 
Instance details

Defined in URI.ByteString.Types

Methods

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

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

Ord Host Source # 
Instance details

Defined in URI.ByteString.Types

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 Source # 
Instance details

Defined in URI.ByteString.Types

Methods

showsPrec :: Int -> Host -> ShowS #

show :: Host -> String #

showList :: [Host] -> ShowS #

Generic Host Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep Host :: * -> * #

Methods

from :: Host -> Rep Host x #

to :: Rep Host x -> Host #

Lift Host Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: Host -> Q Exp #

type Rep Host Source # 
Instance details

Defined in URI.ByteString.Types

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

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

Instances
Eq Port Source # 
Instance details

Defined in URI.ByteString.Types

Methods

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

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

Ord Port Source # 
Instance details

Defined in URI.ByteString.Types

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 Source # 
Instance details

Defined in URI.ByteString.Types

Methods

showsPrec :: Int -> Port -> ShowS #

show :: Port -> String #

showList :: [Port] -> ShowS #

Generic Port Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep Port :: * -> * #

Methods

from :: Port -> Rep Port x #

to :: Rep Port x -> Port #

Lift Port Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: Port -> Q Exp #

type Rep Port Source # 
Instance details

Defined in URI.ByteString.Types

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

data Authority Source #

Instances
Eq Authority Source # 
Instance details

Defined in URI.ByteString.Types

Ord Authority Source # 
Instance details

Defined in URI.ByteString.Types

Show Authority Source # 
Instance details

Defined in URI.ByteString.Types

Generic Authority Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep Authority :: * -> * #

Lift Authority Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: Authority -> Q Exp #

type Rep Authority Source # 
Instance details

Defined in URI.ByteString.Types

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

data UserInfo Source #

Constructors

UserInfo 
Instances
Eq UserInfo Source # 
Instance details

Defined in URI.ByteString.Types

Ord UserInfo Source # 
Instance details

Defined in URI.ByteString.Types

Show UserInfo Source # 
Instance details

Defined in URI.ByteString.Types

Generic UserInfo Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep UserInfo :: * -> * #

Methods

from :: UserInfo -> Rep UserInfo x #

to :: Rep UserInfo x -> UserInfo #

Lift UserInfo Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: UserInfo -> Q Exp #

type Rep UserInfo Source # 
Instance details

Defined in URI.ByteString.Types

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

newtype Query Source #

Constructors

Query 
Instances
Eq Query Source # 
Instance details

Defined in URI.ByteString.Types

Methods

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

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

Ord Query Source # 
Instance details

Defined in URI.ByteString.Types

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 Source # 
Instance details

Defined in URI.ByteString.Types

Methods

showsPrec :: Int -> Query -> ShowS #

show :: Query -> String #

showList :: [Query] -> ShowS #

Generic Query Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep Query :: * -> * #

Methods

from :: Query -> Rep Query x #

to :: Rep Query x -> Query #

Semigroup Query Source # 
Instance details

Defined in URI.ByteString.Types

Methods

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

sconcat :: NonEmpty Query -> Query #

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

Monoid Query Source # 
Instance details

Defined in URI.ByteString.Types

Methods

mempty :: Query #

mappend :: Query -> Query -> Query #

mconcat :: [Query] -> Query #

Lift Query Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: Query -> Q Exp #

type Rep Query Source # 
Instance details

Defined in URI.ByteString.Types

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

data URIRef a where Source #

Note: URI fragment does not include the #

Instances
Eq (URIRef a) Source # 
Instance details

Defined in URI.ByteString.Types

Methods

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

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

Ord (URIRef a) Source # 
Instance details

Defined in URI.ByteString.Types

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) Source # 
Instance details

Defined in URI.ByteString.Types

Methods

showsPrec :: Int -> URIRef a -> ShowS #

show :: URIRef a -> String #

showList :: [URIRef a] -> ShowS #

Lift (URIRef a) Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: URIRef a -> Q Exp #

data Absolute Source #

Instances
Lift Absolute Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: Absolute -> Q Exp #

data Relative Source #

Instances
Lift Relative Source # 
Instance details

Defined in URI.ByteString.Types

Methods

lift :: Relative -> Q Exp #

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 # 
Instance details

Defined in URI.ByteString.Types

Read SchemaError Source # 
Instance details

Defined in URI.ByteString.Types

Show SchemaError Source # 
Instance details

Defined in URI.ByteString.Types

Generic SchemaError Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep SchemaError :: * -> * #

type Rep SchemaError Source # 
Instance details

Defined in URI.ByteString.Types

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

data URIParseError Source #

Instances
Eq URIParseError Source # 
Instance details

Defined in URI.ByteString.Types

Read URIParseError Source # 
Instance details

Defined in URI.ByteString.Types

Show URIParseError Source # 
Instance details

Defined in URI.ByteString.Types

Generic URIParseError Source # 
Instance details

Defined in URI.ByteString.Types

Associated Types

type Rep URIParseError :: * -> * #

type Rep URIParseError Source # 
Instance details

Defined in URI.ByteString.Types

type Rep URIParseError = D1 (MetaData "URIParseError" "URI.ByteString.Types" "uri-bytestring-0.3.2.1-IIZl8eanLpZ3VX2nnJKH0T" False) (((C1 (MetaCons "MalformedScheme" PrefixI False) (S1 (MetaSel (Nothing :: Maybe 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 :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String)))))

data URIParserOptions Source #

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

Constructors

URIParserOptions 

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

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:

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

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.

Low level utility functions

urlDecode Source #

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

ByteString Utilities

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

urlEncodeQuery :: ByteString -> Builder Source #

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

urlEncodePath :: ByteString -> Builder Source #

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

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

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

Lenses

Lenses over Scheme

Lenses over Host

Lenses over Port

Lenses over Authority

Lenses over UserInfo

Lenses over Query

Lenses over URIRef

queryL :: Lens' (URIRef a) Query Source #

Lenses over URIParserOptions

Deprecated

serializeURI :: URIRef Absolute -> Builder Source #

Deprecated: Use serializeURIRef instead

Serialize a URI into a Builder.

serializeURI' :: URIRef Absolute -> ByteString Source #

Deprecated: Use serializeURIRef' instead

Like serializeURI, with conversion into a strict ByteString.

serializeRelativeRef :: URIRef Relative -> Builder Source #

Deprecated: Use serializeURIRef instead

Like serializeURI, but do not render scheme.

serializeRelativeRef' :: URIRef Relative -> ByteString Source #

Deprecated: Use serializeURIRef' instead

Like serializeRelativeRef, with conversion into a strict ByteString.

uriAuthorityL :: Lens' URI (Maybe Authority) Source #

Deprecated: Use authorityL instead

uriPathL :: Lens' URI ByteString Source #

Deprecated: Use pathL instead

uriQueryL :: Lens' URI Query Source #

Deprecated: Use queryL instead

uriFragmentL :: Lens' URI (Maybe ByteString) Source #

Deprecated: Use fragmentL instead

rrAuthorityL :: Lens' RelativeRef (Maybe Authority) Source #

Deprecated: Use authorityL instead

rrPathL :: Lens' RelativeRef ByteString Source #

Deprecated: Use pathL instead

rrQueryL :: Lens' RelativeRef Query Source #

Deprecated: Use queryL instead

rrFragmentL :: Lens' RelativeRef (Maybe ByteString) Source #

Deprecated: Use fragmentL instead