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

-- | 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] :: Scheme -> Maybe Authority -> ByteString -> Query -> Maybe ByteString -> URIRef Absolute
[RelativeRef] :: Maybe Authority -> ByteString -> Query -> 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 :: Bool -> URIParserOptions
[upoLaxQueryParsing] :: URIParserOptions -> 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.
--   
--   
--   
- Allows non-encoded [ and ] in query string
--   
laxURIParserOptions :: URIParserOptions
data URINormalizationOptions
URINormalizationOptions :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Map Scheme Port -> URINormalizationOptions

-- | hTtP -> http
[unoDowncaseScheme] :: URINormalizationOptions -> Bool

-- | eXaMpLe.org -> 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 RFC3986 Section 5.2.4
[unoRemoveDotSegments] :: URINormalizationOptions -> Bool

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

-- | All normalization options disabled
noNormalization :: URINormalizationOptions

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

-- | The same as rfc3986Normalization but with additional enabled
--   features if you're working with HTTP URIs:
--   
--   
--   
- Drop Default Port (with httpDefaultPorts)
--   
- Drop Extra Slashes
--   
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
--   unoDefaultPorts.
httpDefaultPorts :: Map Scheme Port

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

-- | 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})
--   
parseURI :: URIParserOptions -> ByteString -> Either URIParseError (URIRef Absolute)

-- | Like parseURI, 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 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 -> Builder

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

-- | Serialize the query part of a url serializeQuery opts mempty =
--   "" serializeQuery opts (Query [("a","b"),("c","d")]) =
--   "?a=b&c=d"
serializeQuery :: URINormalizationOptions -> Query -> Builder
serializeQuery' :: URINormalizationOptions -> Query -> ByteString
serializeFragment :: Maybe ByteString -> Builder
serializeFragment' :: Maybe ByteString -> ByteString
serializeAuthority :: URINormalizationOptions -> Maybe Scheme -> Authority -> Builder
serializeAuthority' :: URINormalizationOptions -> Maybe Scheme -> Authority -> ByteString
serializeUserInfo :: UserInfo -> Builder
serializeUserInfo' :: UserInfo -> ByteString

-- | 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.
normalizeURIRef :: URINormalizationOptions -> URIRef a -> Builder
normalizeURIRef' :: URINormalizationOptions -> URIRef a -> 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 :: forall a f. Functor f => (Maybe Authority -> f (Maybe Authority)) -> URIRef a -> f (URIRef a)
pathL :: forall a f. Functor f => (ByteString -> f ByteString) -> URIRef a -> f (URIRef a)
queryL :: forall a f. Functor f => (Query -> f Query) -> URIRef a -> f (URIRef a)
fragmentL :: forall a f. Functor f => (Maybe ByteString -> f (Maybe ByteString)) -> URIRef a -> f (URIRef a)
upoValidQueryCharL :: Lens' URIParserOptions Bool
type URI = URIRef Absolute
type RelativeRef = URIRef Relative

-- | Serialize a URI into a Builder.

-- | Deprecated: Use serializeURIRef instead
serializeURI :: URIRef Absolute -> Builder

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

-- | Deprecated: Use serializeURIRef' instead
serializeURI' :: URIRef Absolute -> ByteString

-- | Like serializeURI, but do not render scheme.

-- | Deprecated: Use serializeURIRef instead
serializeRelativeRef :: URIRef Relative -> Builder

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

-- | Deprecated: Use serializeURIRef' instead
serializeRelativeRef' :: URIRef Relative -> ByteString

-- | Deprecated: Use authorityL instead
uriAuthorityL :: Lens' URI (Maybe Authority)

-- | Deprecated: Use pathL instead
uriPathL :: Lens' URI ByteString

-- | Deprecated: Use queryL instead
uriQueryL :: Lens' URI Query

-- | Deprecated: Use fragmentL instead
uriFragmentL :: Lens' URI (Maybe ByteString)

-- | Deprecated: Use authorityL instead
rrAuthorityL :: Lens' RelativeRef (Maybe Authority)

-- | Deprecated: Use pathL instead
rrPathL :: Lens' RelativeRef ByteString

-- | Deprecated: Use queryL instead
rrQueryL :: Lens' RelativeRef Query

-- | Deprecated: Use fragmentL instead
rrFragmentL :: Lens' RelativeRef (Maybe ByteString)

module URI.ByteString.QQ

-- | Allows uri literals via QuasiQuotes language extension.
--   
--   
--   >>> stackage = [uri|http://stackage.org|]
--   
uri :: QuasiQuoter

-- | Allows relative ref literals via QuasiQuotes language extension.
--   
--   
--   >>> ref = [relativeRef|/foo?bar=baz#quux|]
--   
relativeRef :: QuasiQuoter
