-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Haskell URI parsing as ByteStrings
--   
--   uri-bytestring aims to be an RFC3986 compliant URI parser that uses
--   efficient ByteStrings for parsing and representing the URI data.
@package uri-bytestring
@version 0.2.2.0


-- | 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.
module URI.ByteString

-- | Required first component to referring to a specification for the
--   remainder of the URI's components, e.g. "http" or "https"
newtype Scheme
Scheme :: ByteString -> Scheme
[schemeBS] :: Scheme -> ByteString
newtype Host
Host :: ByteString -> Host
[hostBS] :: Host -> ByteString

-- | While some libraries have chosen to limit this to a Word16, the spec
--   only specifies that the string be comprised of digits.
newtype Port
Port :: Int -> Port
[portNumber] :: Port -> Int
data Authority
Authority :: Maybe UserInfo -> Host -> Maybe Port -> Authority
[authorityUserInfo] :: Authority -> Maybe UserInfo
[authorityHost] :: Authority -> Host
[authorityPort] :: Authority -> Maybe Port
data UserInfo
UserInfo :: ByteString -> ByteString -> UserInfo
[uiUsername] :: UserInfo -> ByteString
[uiPassword] :: UserInfo -> ByteString
newtype Query
Query :: [(ByteString, ByteString)] -> Query
[queryPairs] :: Query -> [(ByteString, ByteString)]

-- | Note: URI fragment does not include the #
data URIRef a
[URI] :: {uriScheme :: Scheme, uriAuthority :: Maybe Authority, uriPath :: ByteString, uriQuery :: Query, uriFragment :: Maybe ByteString} -> URIRef Absolute
[RelativeRef] :: {rrAuthority :: Maybe Authority, rrPath :: ByteString, rrQuery :: Query, rrFragment :: Maybe ByteString} -> URIRef Relative
data Absolute
data Relative

-- | URI Parser Types
data SchemaError

-- | Scheme must start with an alphabet character
NonAlphaLeading :: SchemaError

-- | Subsequent characters in the schema were invalid
InvalidChars :: SchemaError

-- | Schemas must be followed by a colon
MissingColon :: SchemaError
data URIParseError
MalformedScheme :: SchemaError -> URIParseError
MalformedUserInfo :: URIParseError
MalformedQuery :: URIParseError
MalformedFragment :: URIParseError
MalformedHost :: URIParseError
MalformedPort :: URIParseError
MalformedPath :: URIParseError

-- | Catchall for unpredictable errors
OtherError :: String -> URIParseError

-- | Options for the parser. You will probably want to use either
--   "strictURIParserOptions" or "laxURIParserOptions"
data URIParserOptions
URIParserOptions :: (Word8 -> Bool) -> URIParserOptions
[upoValidQueryChar] :: URIParserOptions -> Word8 -> Bool

-- | 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.
strictURIParserOptions :: URIParserOptions

-- | Lax URI Parser config. Use this if you you want to handle common
--   deviations from the spec gracefully.
--   
--   <ul>
--   <li>Allows non-encoded [ and ] in query string</li>
--   </ul>
laxURIParserOptions :: URIParserOptions
data URINormalizationOptions
URINormalizationOptions :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Map Scheme Port -> URINormalizationOptions

-- | hTtP -&gt; http
[unoDowncaseScheme] :: URINormalizationOptions -> Bool

-- | eXaMpLe.org -&gt; example.org
[unoDowncaseHost] :: URINormalizationOptions -> Bool

-- | If the scheme is known and the port is the default (e.g. 80 for http)
--   it is removed.
[unoDropDefPort] :: URINormalizationOptions -> Bool

-- | If the path is empty, set it to /
[unoSlashEmptyPath] :: URINormalizationOptions -> Bool

-- | Rewrite path from /foo//bar///baz to /foo/bar/baz
[unoDropExtraSlashes] :: URINormalizationOptions -> Bool

-- | Sorts parameters by parameter name
[unoSortParameters] :: URINormalizationOptions -> Bool

-- | Remove dot segments as per <a>RFC3986 Section 5.2.4</a>
[unoRemoveDotSegments] :: URINormalizationOptions -> Bool

-- | Map of known schemes to their default ports. Used when
--   <a>unoDropDefPort</a> is enabled.
[unoDefaultPorts] :: URINormalizationOptions -> Map Scheme Port

-- | All normalization options disabled
noNormalization :: URINormalizationOptions

-- | Only normalizations deemed appropriate for all protocols by RFC3986
--   enabled, namely:
--   
--   <ul>
--   <li>Downcase Scheme</li>
--   <li>Downcase Host</li>
--   <li>Remove Dot Segments</li>
--   </ul>
rfc3986Normalization :: URINormalizationOptions

-- | The same as <a>rfc3986Normalization</a> but with additional enabled
--   features if you're working with HTTP URIs:
--   
--   <ul>
--   <li>Drop Default Port (with <a>httpDefaultPorts</a>)</li>
--   <li>Drop Extra Slashes</li>
--   </ul>
httpNormalization :: URINormalizationOptions

-- | All options enabled
aggressiveNormalization :: URINormalizationOptions

-- | The set of known default ports to schemes. Currently only contains
--   http/80 and https/443. Feel free to extend it if needed with
--   <a>unoDefaultPorts</a>.
httpDefaultPorts :: Map Scheme Port

-- | <tt>toAbsolute scheme ref</tt> converts <tt>ref</tt> to an absolute
--   URI. If <tt>ref</tt> is already absolute, then it is unchanged.
toAbsolute :: Scheme -> URIRef a -> URIRef Absolute

-- | Parse a strict ByteString into a URI or an error.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; 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"})
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseURI strictURIParserOptions "$$$$://badurl.example.org"
--   Left (MalformedScheme NonAlphaLeading)
--   </pre>
--   
--   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
--   
--   <pre>
--   &gt;&gt;&gt; parseURI strictURIParserOptions "http://www.example.org/foo?bar[]=baz"
--   Left MalformedQuery
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 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})
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let myLaxOptions = URIParserOptions { upoValidQueryChar = liftA2 (||) (upoValidQueryChar strictURIParserOptions) (inClass "[]")}
--   
--   &gt;&gt;&gt; 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})
--   </pre>
parseURI :: URIParserOptions -> ByteString -> Either URIParseError (URIRef Absolute)

-- | Like <a>parseURI</a>, but do not parse scheme.
parseRelativeRef :: URIParserOptions -> ByteString -> Either URIParseError (URIRef Relative)

-- | Underlying attoparsec parser. Useful for composing with your own
--   parsers.
uriParser :: URIParserOptions -> Parser (URIRef Absolute)

-- | Underlying attoparsec parser. Useful for composing with your own
--   parsers.
relativeRefParser :: URIParserOptions -> Parser (URIRef Relative)

-- | URI Serializer
--   
--   Serialize a URI reference into a <a>Builder</a>.
--   
--   Example of serializing + converting to a lazy
--   <a>Data.ByteString.Lazy.ByteString</a>:
--   
--   <pre>
--   &gt;&gt;&gt; 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"
--   </pre>
serializeURIRef :: URIRef a -> Builder

-- | Like <a>serializeURIRef</a>, with conversion into a strict
--   <a>ByteString</a>.
serializeURIRef' :: URIRef a -> ByteString

-- | Similar to <a>serializeURIRef</a> but performs configurable degrees of
--   URI normalization. If your goal is the fastest serialization speed
--   possible, <a>serializeURIRef</a> will be fine. If you intend on
--   comparing URIs (say for caching purposes), you'll want to use this.
normalizeURIRef :: URINormalizationOptions -> URIRef a -> Builder
normalizeURIRef' :: URINormalizationOptions -> URIRef a -> ByteString

-- | This function was extracted from the <tt>http-types</tt> package. The
--   license can be found in licenses<i>http-types</i>LICENSE
urlDecode :: Bool -> ByteString -> ByteString

-- | ByteString Utilities
--   
--   Decoding specifically for the query string, which decodes + as space.
--   Shorthand for <tt>urlDecode True</tt>
urlDecodeQuery :: ByteString -> ByteString

-- | Encode a ByteString for use in the query section of a URL
urlEncodeQuery :: ByteString -> Builder

-- | Encode a ByteString for use in the path section of a URL
urlEncodePath :: ByteString -> Builder

-- | Percent-encoding for URLs. Specify a list of additional unreserved
--   characters to permit.
urlEncode :: [Word8] -> ByteString -> Builder
schemeBSL :: Lens' Scheme ByteString
hostBSL :: Lens' Host ByteString
portNumberL :: Lens' Port Int
authorityUserInfoL :: Lens' Authority (Maybe UserInfo)
authorityHostL :: Lens' Authority Host
authorityPortL :: Lens' Authority (Maybe Port)
uiUsernameL :: Lens' UserInfo ByteString
uiPasswordL :: Lens' UserInfo ByteString
queryPairsL :: Lens' Query [(ByteString, ByteString)]
uriSchemeL :: Lens' (URIRef Absolute) Scheme
authorityL :: Lens' (URIRef a) (Maybe Authority)
pathL :: Lens' (URIRef a) ByteString
queryL :: Lens' (URIRef a) Query
fragmentL :: Lens' (URIRef a) (Maybe ByteString)
upoValidQueryCharL :: Lens' URIParserOptions (Word8 -> Bool)
type URI = URIRef Absolute
type RelativeRef = URIRef Relative

-- | Serialize a URI into a Builder.

-- | <i>Deprecated: Use <a>serializeURIRef</a> instead</i>
serializeURI :: URIRef Absolute -> Builder

-- | Like <a>serializeURI</a>, with conversion into a strict
--   <a>ByteString</a>.

-- | <i>Deprecated: Use <a>serializeURIRef'</a> instead</i>
serializeURI' :: URIRef Absolute -> ByteString

-- | Like <a>serializeURI</a>, but do not render scheme.

-- | <i>Deprecated: Use <a>serializeURIRef</a> instead</i>
serializeRelativeRef :: URIRef Relative -> Builder

-- | Like <a>serializeRelativeRef</a>, with conversion into a strict
--   <a>ByteString</a>.

-- | <i>Deprecated: Use <a>serializeURIRef'</a> instead</i>
serializeRelativeRef' :: URIRef Relative -> ByteString

-- | <i>Deprecated: Use <a>authorityL</a> instead</i>
uriAuthorityL :: Lens' URI (Maybe Authority)

-- | <i>Deprecated: Use <a>pathL</a> instead</i>
uriPathL :: Lens' URI ByteString

-- | <i>Deprecated: Use <a>queryL</a> instead</i>
uriQueryL :: Lens' URI Query

-- | <i>Deprecated: Use <a>fragmentL</a> instead</i>
uriFragmentL :: Lens' URI (Maybe ByteString)

-- | <i>Deprecated: Use <a>authorityL</a> instead</i>
rrAuthorityL :: Lens' RelativeRef (Maybe Authority)

-- | <i>Deprecated: Use <a>pathL</a> instead</i>
rrPathL :: Lens' RelativeRef ByteString

-- | <i>Deprecated: Use <a>queryL</a> instead</i>
rrQueryL :: Lens' RelativeRef Query

-- | <i>Deprecated: Use <a>fragmentL</a> instead</i>
rrFragmentL :: Lens' RelativeRef (Maybe ByteString)
