Copyright | (c) Soostone Inc., 2014 Michael Xavier, 2014 |
---|---|
License | BSD3 |
Maintainer | michael.xavier@soostone.com |
Stability | experimental |
Safe Haskell | None |
Language | Haskell2010 |
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.
- newtype Scheme = Scheme {}
- newtype Host = Host {}
- newtype Port = Port {}
- data Authority = Authority {}
- data UserInfo = UserInfo {}
- newtype Query = Query {
- getQuery :: [(ByteString, ByteString)]
- data URI = URI {}
- data SchemaError
- data URIParseError
- data URIParserOptions = URIParserOptions {
- upoValidQueryChar :: Word8 -> Bool
- strictURIParserOptions :: URIParserOptions
- laxURIParserOptions :: URIParserOptions
- parseURI :: URIParserOptions -> ByteString -> Either URIParseError URI
- serializeURI :: URI -> Builder
URI-related types
Required first component to referring to a specification for the remainder of the URI's components, e.g. "http" or "https"
While some libraries have chosen to limit this to a Word16, the spec only specifies that the string be comprised of digits.
URI | |
|
data SchemaError Source
URI Parser
NonAlphaLeading | Scheme must start with an alphabet character |
InvalidChars | Subsequent characters in the schema were invalid |
MissingColon | Schemas must be followed by a colon |
data URIParseError Source
MalformedScheme SchemaError | |
MalformedUserInfo | |
MalformedQuery | |
MalformedFragment | |
MalformedHost | |
MalformedPort | |
MalformedPath | |
OtherError String | Catchall for unpredictable errors |
data URIParserOptions Source
Options for the parser. You will probably want to use either "strictURIParserOptions" or "laxURIParserOptions"
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"