-- 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 ViewPatterns language extension enabled,
--   they may also be used in a pattern context (since 0.3.2.0).
module Text.URI.QQ

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

-- | Construct a RText Scheme value at compile time.
scheme :: QuasiQuoter

-- | Construct a RText Host value at compile time.
host :: QuasiQuoter

-- | Construct a RText Username value at compile
--   time.
username :: QuasiQuoter

-- | Construct a RText Password value at compile
--   time.
password :: QuasiQuoter

-- | Construct a RText PathPiece value at compile
--   time.
pathPiece :: QuasiQuoter

-- | Construct a RText QueryKey value at compile
--   time.
queryKey :: QuasiQuoter

-- | Construct a 'RText QueryValue value at compile time.
queryValue :: QuasiQuoter

-- | Construct a RText Fragment value at compile
--   time.
fragment :: QuasiQuoter

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

-- | URI scheme lens.
uriScheme :: Lens' URI (Maybe (RText 'Scheme))

-- | URI authority lens.
--   
--   Note: before version 0.1.0.0 this lens allowed to focus
--   on Maybe Authority.
uriAuthority :: Lens' URI (Either Bool Authority)

-- | URI path lens.
uriPath :: Lens' URI [RText 'PathPiece]

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

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

-- | URI query params lens.
uriQuery :: Lens' URI [QueryParam]

-- | URI fragment lens.
uriFragment :: Lens' URI (Maybe (RText 'Fragment))

-- | Authority user info lens.
authUserInfo :: Lens' Authority (Maybe UserInfo)

-- | Authority host lens.
authHost :: Lens' Authority (RText 'Host)

-- | Authority port lens.
authPort :: Lens' Authority (Maybe Word)

-- | UserInfo username lens.
uiUsername :: Lens' UserInfo (RText 'Username)

-- | UserInfo password lens.
uiPassword :: Lens' UserInfo (Maybe (RText 'Password))

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

-- | QueryParam 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 Text 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:
--   
--   https://tools.ietf.org/html/rfc3986
--   
--   This module is intended to be imported qualified, e.g.:
--   
--   
--   import Text.URI (URI)
--   import qualified Text.URI as URI
--   
--   
--   See also Text.URI.Lens for lens, prisms, and traversals; see
--   Text.URI.QQ for quasi-quoters for compile-time validation of
--   URIs and refined text components.
module Text.URI

-- | Uniform resource identifier (URI) reference. We use refined
--   Text (RText l) 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 Nothing, then the URI reference is relative
[uriScheme] :: URI -> Maybe (RText 'Scheme)

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

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

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

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

-- | The empty URI.
emptyURI :: URI

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

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

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

-- | Authority component of URI.
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, Nothing means that there was no : 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 mkURI when a given Text
--   value cannot be parsed as a URI.
newtype ParseException

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

-- | Parse exception thrown by mkURIBs when a given
--   ByteString value cannot be parsed as a URI.
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 mkScheme
Scheme :: RTextLabel

-- | See mkHost
Host :: RTextLabel

-- | See mkUsername
Username :: RTextLabel

-- | See mkPassword
Password :: RTextLabel

-- | See mkPathPiece
PathPiece :: RTextLabel

-- | See mkQueryKey
QueryKey :: RTextLabel

-- | See mkQueryValue
QueryValue :: RTextLabel

-- | See mkFragment
Fragment :: RTextLabel

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

-- | Lift a Text value into RText Host.
--   
--   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: https://tools.ietf.org/html/rfc3986#section-3.2.2
mkHost :: MonadThrow m => Text -> m (RText 'Host)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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