Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
GI.Soup.Structs.URI
Contents
Description
A URI
represents a (parsed) URI. URI
supports RFC 3986
(URI Generic Syntax), and can parse any valid URI. However, libsoup
only uses "http" and "https" URIs internally; You can use
SOUP_URI_VALID_FOR_HTTP()
to test if a URI
is a valid HTTP
URI.
scheme
will always be set in any URI. It is an interned string and
is always all lowercase. (If you parse a URI with a non-lowercase
scheme, it will be converted to lowercase.) The macros
SOUP_URI_SCHEME_HTTP
and SOUP_URI_SCHEME_HTTPS
provide the
interned values for "http" and "https" and can be compared against
URI scheme
values.
user
and password
are parsed as defined in the older URI specs
(ie, separated by a colon; RFC 3986 only talks about a single
"userinfo" field). Note that password
is not included in the
output of uRIToString
. libsoup does not normally use these
fields; authentication is handled via Session
signals.
host
contains the hostname, and port
the port specified in the
URI. If the URI doesn't contain a hostname, host
will be Nothing
,
and if it doesn't specify a port, port
may be 0. However, for
"http" and "https" URIs, host
is guaranteed to be non-Nothing
(trying to parse an http URI with no host
will return Nothing
), and
port
will always be non-0 (because libsoup knows the default value
to use when it is not specified in the URI).
path
is always non-Nothing
. For http/https URIs, path
will never be
an empty string either; if the input URI has no path, the parsed
URI
will have a path
of "/".
query
and fragment
are optional for all URI types.
formDecode
may be useful for parsing query
.
Note that path
, query
, and fragment
may contain
%<!-- -->-encoded characters. uRINew
calls
uriNormalize
on them, but not uriDecode
. This is
necessary to ensure that uRIToString
will generate a URI
that has exactly the same meaning as the original. (In theory,
URI
should leave user
, password
, and host
partially-encoded
as well, but this would be more annoying than useful.)
- newtype URI = URI (ManagedPtr URI)
- newZeroURI :: MonadIO m => m URI
- noURI :: Maybe URI
- uRICopy :: (HasCallStack, MonadIO m) => URI -> m URI
- uRICopyHost :: (HasCallStack, MonadIO m) => URI -> m URI
- uRIDecode :: (HasCallStack, MonadIO m) => Text -> m Text
- uRIEncode :: (HasCallStack, MonadIO m) => Text -> Maybe Text -> m Text
- uRIEqual :: (HasCallStack, MonadIO m) => URI -> URI -> m Bool
- uRIFree :: (HasCallStack, MonadIO m) => URI -> m ()
- uRIGetFragment :: (HasCallStack, MonadIO m) => URI -> m Text
- uRIGetHost :: (HasCallStack, MonadIO m) => URI -> m Text
- uRIGetPassword :: (HasCallStack, MonadIO m) => URI -> m Text
- uRIGetPath :: (HasCallStack, MonadIO m) => URI -> m Text
- uRIGetPort :: (HasCallStack, MonadIO m) => URI -> m Word32
- uRIGetQuery :: (HasCallStack, MonadIO m) => URI -> m Text
- uRIGetScheme :: (HasCallStack, MonadIO m) => URI -> m Text
- uRIGetUser :: (HasCallStack, MonadIO m) => URI -> m Text
- uRIHostEqual :: (HasCallStack, MonadIO m) => URI -> URI -> m Bool
- uRIHostHash :: (HasCallStack, MonadIO m) => URI -> m Word32
- uRINew :: (HasCallStack, MonadIO m) => Maybe Text -> m (Maybe URI)
- uRINewWithBase :: (HasCallStack, MonadIO m) => URI -> Text -> m URI
- uRINormalize :: (HasCallStack, MonadIO m) => Text -> Maybe Text -> m Text
- uRISetFragment :: (HasCallStack, MonadIO m) => URI -> Maybe Text -> m ()
- uRISetHost :: (HasCallStack, MonadIO m) => URI -> Maybe Text -> m ()
- uRISetPassword :: (HasCallStack, MonadIO m) => URI -> Maybe Text -> m ()
- uRISetPath :: (HasCallStack, MonadIO m) => URI -> Text -> m ()
- uRISetPort :: (HasCallStack, MonadIO m) => URI -> Word32 -> m ()
- uRISetQuery :: (HasCallStack, MonadIO m) => URI -> Maybe Text -> m ()
- uRISetQueryFromForm :: (HasCallStack, MonadIO m) => URI -> Map Text Text -> m ()
- uRISetScheme :: (HasCallStack, MonadIO m) => URI -> Text -> m ()
- uRISetUser :: (HasCallStack, MonadIO m) => URI -> Maybe Text -> m ()
- uRIToString :: (HasCallStack, MonadIO m) => URI -> Bool -> m Text
- uRIUsesDefaultPort :: (HasCallStack, MonadIO m) => URI -> m Bool
- clearURIFragment :: MonadIO m => URI -> m ()
- getURIFragment :: MonadIO m => URI -> m (Maybe Text)
- setURIFragment :: MonadIO m => URI -> CString -> m ()
- clearURIHost :: MonadIO m => URI -> m ()
- getURIHost :: MonadIO m => URI -> m (Maybe Text)
- setURIHost :: MonadIO m => URI -> CString -> m ()
- clearURIPassword :: MonadIO m => URI -> m ()
- getURIPassword :: MonadIO m => URI -> m (Maybe Text)
- setURIPassword :: MonadIO m => URI -> CString -> m ()
- clearURIPath :: MonadIO m => URI -> m ()
- getURIPath :: MonadIO m => URI -> m (Maybe Text)
- setURIPath :: MonadIO m => URI -> CString -> m ()
- getURIPort :: MonadIO m => URI -> m Word32
- setURIPort :: MonadIO m => URI -> Word32 -> m ()
- clearURIQuery :: MonadIO m => URI -> m ()
- getURIQuery :: MonadIO m => URI -> m (Maybe Text)
- setURIQuery :: MonadIO m => URI -> CString -> m ()
- clearURIScheme :: MonadIO m => URI -> m ()
- getURIScheme :: MonadIO m => URI -> m (Maybe Text)
- setURIScheme :: MonadIO m => URI -> CString -> m ()
- clearURIUser :: MonadIO m => URI -> m ()
- getURIUser :: MonadIO m => URI -> m (Maybe Text)
- setURIUser :: MonadIO m => URI -> CString -> m ()
Exported types
Constructors
URI (ManagedPtr URI) |
Instances
BoxedObject URI Source # | |
(~) AttrOpTag tag AttrSet => Constructible URI tag Source # | |
Methods
copy
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m URI | Returns: a copy of |
Copies uri
copyHost
Makes a copy of uri
, considering only the protocol, host, and port
Since: 2.28
decode
Arguments
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m Text | Returns: the decoded URI part. |
encode
Arguments
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Maybe Text |
|
-> m Text | Returns: the encoded URI part |
This %<!-- -->-encodes the given URI part and returns the escaped version in allocated memory, which the caller must free when it is done.
equal
Tests whether or not uri1
and uri2
are equal in all parts
free
getFragment
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's fragment.
Since: 2.32
getHost
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's host.
Since: 2.32
getPassword
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's password.
Since: 2.32
getPath
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's path.
Since: 2.32
getPort
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Word32 | Returns: |
Gets uri
's port.
Since: 2.32
getQuery
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's query.
Since: 2.32
getScheme
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's scheme.
Since: 2.32
getUser
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's user.
Since: 2.32
hostEqual
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI | |
-> URI | |
-> m Bool | Returns: whether or not the URIs are equal in scheme, host, and port. |
Compares v1
and v2
, considering only the scheme, host, and port.
Since: 2.28
hostHash
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI | |
-> m Word32 | Returns: a hash |
Hashes key
, considering only the scheme, host, and port.
Since: 2.28
new
Arguments
:: (HasCallStack, MonadIO m) | |
=> Maybe Text |
|
-> m (Maybe URI) | Returns: a |
Parses an absolute URI.
You can also pass Nothing
for uriString
if you want to get back an
"empty" URI
that you can fill in by hand. (You will need to
call at least uRISetScheme
and uRISetPath
, since
those fields are required.)
newWithBase
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Text |
|
-> m URI | Returns: a parsed |
Parses uriString
relative to base
.
normalize
Arguments
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Maybe Text |
|
-> m Text | Returns: the normalized URI part |
%<!-- -->-decodes any "unreserved" characters (or characters in
unescapeExtra
) in part
, and %<!-- -->-encodes any non-ASCII
characters, spaces, and non-printing characters in part
.
"Unreserved" characters are those that are not allowed to be used
for punctuation according to the URI spec. For example, letters are
unreserved, so uriNormalize
will turn
<literal>http://example.com/foo/b%<!-- -->61r</literal> into
<literal>http://example.com/foo/bar</literal>, which is guaranteed
to mean the same thing. However, "/" is "reserved", so
<literal>http://example.com/foo%<!-- -->2Fbar</literal> would not
be changed, because it might mean something different to the
server.
In the past, this would return Nothing
if part
contained invalid
percent-encoding, but now it just ignores the problem (as
uRINew
already did).
setFragment
Sets uri
's fragment to fragment
.
setHost
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Maybe Text |
|
-> m () |
Sets uri
's host to host
.
If host
is an IPv6 IP address, it should not include the brackets
required by the URI syntax; they will be added automatically when
converting uri
to a string.
http and https URIs should not have a Nothing
host
.
setPassword
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Maybe Text |
|
-> m () |
Sets uri
's password to password
.
setPath
Sets uri
's path to path
.
setPort
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Word32 |
|
-> m () |
Sets uri
's port to port
. If port
is 0, uri
will not have an
explicitly-specified port.
setQuery
Sets uri
's query to query
.
setQueryFromForm
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Map Text Text |
|
-> m () |
Sets uri
's query to the result of encoding form
according to the
HTML form rules. See formEncodeHash
for more information.
setScheme
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Text |
|
-> m () |
Sets uri
's scheme to scheme
. This will also set uri
's port to
the default port for scheme
, if known.
setUser
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Maybe Text |
|
-> m () |
Sets uri
's user to user
.
toString
Arguments
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Bool |
|
-> m Text | Returns: a string representing |
Returns a string representing uri
.
If justPathAndQuery
is True
, this concatenates the path and query
together. That is, it constructs the string that would be needed in
the Request-Line of an HTTP request for uri
.
Note that the output will never contain a password, even if uri
does.
usesDefaultPort
Tests if uri
uses the default port for its scheme. (Eg, 80 for
http.) (This only works for http, https and ftp; libsoup does not know
the default ports of other protocols.)
Properties
fragment
clearURIFragment :: MonadIO m => URI -> m () Source #
host
clearURIHost :: MonadIO m => URI -> m () Source #
password
clearURIPassword :: MonadIO m => URI -> m () Source #
path
clearURIPath :: MonadIO m => URI -> m () Source #
port
query
clearURIQuery :: MonadIO m => URI -> m () Source #
scheme
clearURIScheme :: MonadIO m => URI -> m () Source #
user
clearURIUser :: MonadIO m => URI -> m () Source #