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


-- | Modern library for working with URIs
--   
--   Modern library for working with URIs.
@package modern-uri
@version 0.3.6.1


-- | Quasi-quoters for compile-time construction of URIs and refined text
--   values.
--   
--   All of the quasi-quoters in this module can be used in an expression
--   context. With the <tt>ViewPatterns</tt> language extension enabled,
--   they may also be used in a pattern context (since <i>0.3.2.0</i>).
module Text.URI.QQ

-- | Construct a <a>URI</a> value at compile time.
uri :: QuasiQuoter

-- | Construct a <tt><a>RText</a> <a>Scheme</a></tt> value at compile time.
scheme :: QuasiQuoter

-- | Construct a <tt><a>RText</a> <a>Host</a></tt> value at compile time.
host :: QuasiQuoter

-- | Construct a <tt><a>RText</a> <a>Username</a></tt> value at compile
--   time.
username :: QuasiQuoter

-- | Construct a <tt><a>RText</a> <a>Password</a></tt> value at compile
--   time.
password :: QuasiQuoter

-- | Construct a <tt><a>RText</a> <a>PathPiece</a></tt> value at compile
--   time.
pathPiece :: QuasiQuoter

-- | Construct a <tt><a>RText</a> <a>QueryKey</a></tt> value at compile
--   time.
queryKey :: QuasiQuoter

-- | Construct a <tt>'RText <a>QueryValue</a></tt> value at compile time.
queryValue :: QuasiQuoter

-- | Construct a <tt><a>RText</a> <a>Fragment</a></tt> value at compile
--   time.
fragment :: QuasiQuoter


-- | Lenses for working with the <a>URI</a> data type and its internals.
module Text.URI.Lens

-- | <a>URI</a> scheme lens.
uriScheme :: Lens' URI (Maybe (RText 'Scheme))

-- | <a>URI</a> authority lens.
--   
--   <b>Note</b>: before version <i>0.1.0.0</i> this lens allowed to focus
--   on <tt><a>Maybe</a> <a>Authority</a></tt>.
uriAuthority :: Lens' URI (Either Bool Authority)

-- | <a>URI</a> path lens.
uriPath :: Lens' URI [RText 'PathPiece]

-- | A getter that can tell if path component of a <a>URI</a> is absolute.
isPathAbsolute :: Getter URI Bool

-- | A 0-1 traversal allowing to view and manipulate trailing slash.
uriTrailingSlash :: Traversal' URI Bool

-- | <a>URI</a> query params lens.
uriQuery :: Lens' URI [QueryParam]

-- | <a>URI</a> fragment lens.
uriFragment :: Lens' URI (Maybe (RText 'Fragment))

-- | <a>Authority</a> user info lens.
authUserInfo :: Lens' Authority (Maybe UserInfo)

-- | <a>Authority</a> host lens.
authHost :: Lens' Authority (RText 'Host)

-- | <a>Authority</a> port lens.
authPort :: Lens' Authority (Maybe Word)

-- | <a>UserInfo</a> username lens.
uiUsername :: Lens' UserInfo (RText 'Username)

-- | <a>UserInfo</a> password lens.
uiPassword :: Lens' UserInfo (Maybe (RText 'Password))

-- | <a>QueryParam</a> prism for query flags.
_QueryFlag :: Prism' QueryParam (RText 'QueryKey)

-- | <a>QueryParam</a> prism for query parameters.
_QueryParam :: Prism' QueryParam (RText 'QueryKey, RText 'QueryValue)

-- | Check if the given query key is present in the collection of query
--   parameters.
queryFlag :: RText 'QueryKey -> Getter [QueryParam] Bool

-- | Manipulate a query parameter by its key. Note that since there may be
--   several query parameters with the same key this is a traversal that
--   can return/modify several items at once.
queryParam :: RText 'QueryKey -> Traversal' [QueryParam] (RText 'QueryValue)

-- | A getter that can project <a>Text</a> from refined text values.
unRText :: forall (l :: RTextLabel) f. (Contravariant f, Functor f) => (Text -> f Text) -> RText l -> f (RText l)


-- | This is a modern library for working with URIs as per RFC 3986:
--   
--   <a>https://tools.ietf.org/html/rfc3986</a>
--   
--   This module is intended to be imported qualified, e.g.:
--   
--   <pre>
--   import Text.URI (URI)
--   import qualified Text.URI as URI
--   </pre>
--   
--   See also <a>Text.URI.Lens</a> for lens, prisms, and traversals; see
--   <a>Text.URI.QQ</a> for quasi-quoters for compile-time validation of
--   URIs and refined text components.
module Text.URI

-- | Uniform resource identifier (URI) reference. We use refined
--   <a>Text</a> (<tt><a>RText</a> l</tt>) here because information is
--   presented in human-readable form, i.e. percent-decoded, and thus it
--   may contain Unicode characters.
data URI
URI :: Maybe (RText 'Scheme) -> Either Bool Authority -> Maybe (Bool, NonEmpty (RText 'PathPiece)) -> [QueryParam] -> Maybe (RText 'Fragment) -> URI

-- | URI scheme, if <a>Nothing</a>, then the URI reference is relative
[uriScheme] :: URI -> Maybe (RText 'Scheme)

-- | <a>Authority</a> component in <a>Right</a> or a <a>Bool</a> value in
--   <a>Left</a> indicating if <a>uriPath</a> path is absolute
--   (<a>True</a>) or relative (<a>False</a>); if we have an
--   <a>Authority</a> component, then the path is necessarily absolute, see
--   <a>isPathAbsolute</a>
--   
--   <b>Note</b>: before version <i>0.1.0.0</i> type of <a>uriAuthority</a>
--   was <tt><a>Maybe</a> <a>Authority</a></tt>
[uriAuthority] :: URI -> Either Bool Authority

-- | <a>Nothing</a> represents the empty path, while <a>Just</a> contains
--   an indication <a>Bool</a> whether the path component has a trailing
--   slash, and the collection of path pieces <tt><a>NonEmpty</a>
--   (<a>RText</a> <a>PathPiece</a>)</tt>.
--   
--   <b>Note</b>: before version <i>0.2.0.0</i> type of <a>uriPath</a> was
--   <tt>[<a>RText</a> <a>PathPiece</a>]</tt>.
[uriPath] :: URI -> Maybe (Bool, NonEmpty (RText 'PathPiece))

-- | Query parameters, RFC 3986 does not define the inner organization of
--   query string, so we deconstruct it following RFC 1866 here
[uriQuery] :: URI -> [QueryParam]

-- | Fragment, without <tt>#</tt>
[uriFragment] :: URI -> Maybe (RText 'Fragment)

-- | Construct a <a>URI</a> from <a>Text</a>. The input you pass to
--   <a>mkURI</a> must be a valid URI as per RFC 3986, that is, its
--   components should be percent-encoded where necessary. In case of parse
--   failure <a>ParseException</a> is thrown.
--   
--   This function uses the <a>parser</a> parser under the hood, which you
--   can also use directly in a Megaparsec parser.
mkURI :: MonadThrow m => Text -> m URI

-- | Construct a <a>URI</a> from <a>ByteString</a>. The input you pass to
--   <a>mkURIBs</a> must be a valid URI as per RFC 3986, that is, its
--   components should be percent-encoded where necessary. In case of parse
--   failure <a>ParseExceptionBs</a> is thrown.
--   
--   This function uses the <a>parserBs</a> parser under the hood, which
--   you can also use directly in a Megaparsec parser.
mkURIBs :: MonadThrow m => ByteString -> m URI

-- | The empty <a>URI</a>.
emptyURI :: URI

-- | Make a given <a>URI</a> reference absolute using the supplied
--   <tt><a>RText</a> <a>Scheme</a></tt> if necessary.
makeAbsolute :: RText 'Scheme -> URI -> URI

-- | Return <a>True</a> if path in a given <a>URI</a> is absolute.
isPathAbsolute :: URI -> Bool

-- | <tt><a>relativeTo</a> reference base</tt> makes the <tt>reference</tt>
--   <a>URI</a> absolute resolving it against the <tt>base</tt> <a>URI</a>.
--   
--   If the base <a>URI</a> is not absolute itself (that is, it has no
--   scheme), this function returns <a>Nothing</a>.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-5.2</a>.
relativeTo :: URI -> URI -> Maybe URI

-- | Authority component of <a>URI</a>.
data Authority
Authority :: Maybe UserInfo -> RText 'Host -> Maybe Word -> Authority

-- | User information
[authUserInfo] :: Authority -> Maybe UserInfo

-- | Host
[authHost] :: Authority -> RText 'Host

-- | Port number
[authPort] :: Authority -> Maybe Word

-- | User info as a combination of username and password.
data UserInfo
UserInfo :: RText 'Username -> Maybe (RText 'Password) -> UserInfo

-- | Username
[uiUsername] :: UserInfo -> RText 'Username

-- | Password, <a>Nothing</a> means that there was no <tt>:</tt> character
--   in the user info string
[uiPassword] :: UserInfo -> Maybe (RText 'Password)

-- | Query parameter either in the form of flag or as a pair of key and
--   value. A key cannot be empty, while a value can.
data QueryParam

-- | Flag parameter
QueryFlag :: RText 'QueryKey -> QueryParam

-- | Key–value pair
QueryParam :: RText 'QueryKey -> RText 'QueryValue -> QueryParam

-- | Parse exception thrown by <tt>mkURI</tt> when a given <a>Text</a>
--   value cannot be parsed as a <a>URI</a>.
newtype ParseException

-- | Arguments are: original input and parse error
ParseException :: ParseErrorBundle Text Void -> ParseException

-- | Parse exception thrown by <tt>mkURIBs</tt> when a given
--   <a>ByteString</a> value cannot be parsed as a <a>URI</a>.
newtype ParseExceptionBs

-- | Arguments are: original input and parse error
ParseExceptionBs :: ParseErrorBundle ByteString Void -> ParseExceptionBs

-- | Refined text labelled at the type level.
data RText (l :: RTextLabel)

-- | Refined text labels.
data RTextLabel

-- | See <a>mkScheme</a>
Scheme :: RTextLabel

-- | See <a>mkHost</a>
Host :: RTextLabel

-- | See <a>mkUsername</a>
Username :: RTextLabel

-- | See <a>mkPassword</a>
Password :: RTextLabel

-- | See <a>mkPathPiece</a>
PathPiece :: RTextLabel

-- | See <a>mkQueryKey</a>
QueryKey :: RTextLabel

-- | See <a>mkQueryValue</a>
QueryValue :: RTextLabel

-- | See <a>mkFragment</a>
Fragment :: RTextLabel

-- | Lift a <a>Text</a> value into <tt><a>RText</a> <a>Scheme</a></tt>.
--   
--   Scheme names consist of a sequence of characters beginning with a
--   letter and followed by any combination of letters, digits, plus
--   <tt>"+"</tt>, period <tt>"."</tt>, or hyphen <tt>"-"</tt>.
--   
--   This smart constructor performs normalization of valid schemes by
--   converting them to lower case.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.1</a>
mkScheme :: MonadThrow m => Text -> m (RText 'Scheme)

-- | Lift a <a>Text</a> value into <tt><a>RText</a> <a>Host</a></tt>.
--   
--   The host sub-component of authority is identified by an IP literal
--   encapsulated within square brackets, an IPv4 address in dotted-decimal
--   form, or a registered name.
--   
--   This smart constructor performs normalization of valid hosts by
--   converting them to lower case.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.2.2</a>
mkHost :: MonadThrow m => Text -> m (RText 'Host)

-- | Lift a <a>Text</a> value into <tt><a>RText</a> <a>Username</a></tt>.
--   
--   This smart constructor does not perform any sort of normalization.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.2.1</a>
mkUsername :: MonadThrow m => Text -> m (RText 'Username)

-- | Lift a <a>Text</a> value into <tt><a>RText</a> <a>Password</a></tt>.
--   
--   This smart constructor does not perform any sort of normalization.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.2.1</a>
mkPassword :: MonadThrow m => Text -> m (RText 'Password)

-- | Lift a <a>Text</a> value into <tt><a>RText</a> <a>PathPiece</a></tt>.
--   
--   This smart constructor does not perform any sort of normalization.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.3</a>
mkPathPiece :: MonadThrow m => Text -> m (RText 'PathPiece)

-- | Lift a <a>Text</a> value into <tt>'RText <a>QueryKey</a></tt>.
--   
--   This smart constructor does not perform any sort of normalization.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.4</a>
mkQueryKey :: MonadThrow m => Text -> m (RText 'QueryKey)

-- | Lift a <a>Text</a> value into <tt><a>RText</a> <a>QueryValue</a></tt>.
--   
--   This smart constructor does not perform any sort of normalization.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.4</a>
mkQueryValue :: MonadThrow m => Text -> m (RText 'QueryValue)

-- | Lift a <a>Text</a> value into <tt><a>RText</a> <a>Fragment</a></tt>.
--   
--   This smart constructor does not perform any sort of normalization.
--   
--   See also: <a>https://tools.ietf.org/html/rfc3986#section-3.5</a>
mkFragment :: MonadThrow m => Text -> m (RText 'Fragment)

-- | Project a plain strict <a>Text</a> value from a refined
--   <tt><a>RText</a> l</tt> value.
unRText :: forall (l :: RTextLabel). RText l -> Text

-- | The exception is thrown when a refined <tt><a>RText</a> l</tt> value
--   cannot be constructed due to the fact that given <a>Text</a> value is
--   not correct.
data RTextException

-- | <a>RTextLabel</a> identifying what sort of refined text value could
--   not be constructed and the input that was supplied, as a <a>Text</a>
--   value
RTextException :: RTextLabel -> Text -> RTextException

-- | This parser can be used to parse <a>URI</a> from strict <a>Text</a>.
--   Remember to use a concrete non-polymorphic parser type for efficiency.
parser :: MonadParsec e Text m => m URI

-- | This parser can be used to parse <a>URI</a> from strict
--   <a>ByteString</a>. Remember to use a concrete non-polymorphic parser
--   type for efficiency.
parserBs :: MonadParsec e ByteString m => m URI

-- | Render a given <a>URI</a> value as strict <a>Text</a>.
render :: URI -> Text

-- | Render a given <a>URI</a> value as a <a>Builder</a>.
render' :: URI -> Builder

-- | Render a given <a>URI</a> value as a strict <a>ByteString</a>.
renderBs :: URI -> ByteString

-- | Render a given <a>URI</a> value as a <a>Builder</a>.
renderBs' :: URI -> Builder

-- | Render a given <a>URI</a> value as a <a>String</a>.
renderStr :: URI -> String

-- | Render a given <a>URI</a> value as <a>ShowS</a>.
renderStr' :: URI -> ShowS
