Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (inaki@blueleaf.cc) |
Safe Haskell | None |
Language | Haskell2010 |
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.)
Synopsis
- 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
Memory-managed wrapper type.
URI (ManagedPtr URI) |
Instances
BoxedObject URI Source # | |
tag ~ AttrSet => Constructible URI tag Source # | |
Defined in GI.Soup.Structs.URI |
Methods
copy
:: (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
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m Text | Returns: the decoded URI part. |
encode
:: (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
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's fragment.
Since: 2.32
getHost
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's host.
Since: 2.32
getPassword
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's password.
Since: 2.32
getPath
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's path.
Since: 2.32
getPort
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Word32 | Returns: |
Gets uri
's port.
Since: 2.32
getQuery
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's query.
Since: 2.32
getScheme
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's scheme.
Since: 2.32
getUser
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> m Text | Returns: |
Gets uri
's user.
Since: 2.32
hostEqual
:: (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
:: (HasCallStack, MonadIO m) | |
=> URI | |
-> m Word32 | Returns: a hash |
Hashes key
, considering only the scheme, host, and port.
Since: 2.28
new
:: (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
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Text |
|
-> m URI | Returns: a parsed |
Parses uriString
relative to base
.
normalize
:: (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
:: (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
:: (HasCallStack, MonadIO m) | |
=> URI |
|
-> Maybe Text |
|
-> m () |
Sets uri
's password to password
.
setPath
Sets uri
's path to path
.
setPort
:: (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
:: (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
:: (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
Sets uri
's user to user
.
toString
:: (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
a fragment identifier within path
, or Nothing
clearURIFragment :: MonadIO m => URI -> m () Source #
Set the value of the “fragment
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#fragment
getURIFragment :: MonadIO m => URI -> m (Maybe Text) Source #
Get the value of the “fragment
” field.
When overloading is enabled, this is equivalent to
get
uRI #fragment
setURIFragment :: MonadIO m => URI -> CString -> m () Source #
Set the value of the “fragment
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #fragment:=
value ]
host
the hostname or IP address, or Nothing
clearURIHost :: MonadIO m => URI -> m () Source #
Set the value of the “host
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#host
getURIHost :: MonadIO m => URI -> m (Maybe Text) Source #
Get the value of the “host
” field.
When overloading is enabled, this is equivalent to
get
uRI #host
setURIHost :: MonadIO m => URI -> CString -> m () Source #
Set the value of the “host
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #host:=
value ]
password
a password, or Nothing
clearURIPassword :: MonadIO m => URI -> m () Source #
Set the value of the “password
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#password
getURIPassword :: MonadIO m => URI -> m (Maybe Text) Source #
Get the value of the “password
” field.
When overloading is enabled, this is equivalent to
get
uRI #password
setURIPassword :: MonadIO m => URI -> CString -> m () Source #
Set the value of the “password
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #password:=
value ]
path
the path on host
clearURIPath :: MonadIO m => URI -> m () Source #
Set the value of the “path
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#path
getURIPath :: MonadIO m => URI -> m (Maybe Text) Source #
Get the value of the “path
” field.
When overloading is enabled, this is equivalent to
get
uRI #path
setURIPath :: MonadIO m => URI -> CString -> m () Source #
Set the value of the “path
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #path:=
value ]
port
the port number on host
getURIPort :: MonadIO m => URI -> m Word32 Source #
Get the value of the “port
” field.
When overloading is enabled, this is equivalent to
get
uRI #port
setURIPort :: MonadIO m => URI -> Word32 -> m () Source #
Set the value of the “port
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #port:=
value ]
query
a query for path
, or Nothing
clearURIQuery :: MonadIO m => URI -> m () Source #
Set the value of the “query
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#query
getURIQuery :: MonadIO m => URI -> m (Maybe Text) Source #
Get the value of the “query
” field.
When overloading is enabled, this is equivalent to
get
uRI #query
setURIQuery :: MonadIO m => URI -> CString -> m () Source #
Set the value of the “query
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #query:=
value ]
scheme
the URI scheme (eg, "http")
clearURIScheme :: MonadIO m => URI -> m () Source #
Set the value of the “scheme
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#scheme
getURIScheme :: MonadIO m => URI -> m (Maybe Text) Source #
Get the value of the “scheme
” field.
When overloading is enabled, this is equivalent to
get
uRI #scheme
setURIScheme :: MonadIO m => URI -> CString -> m () Source #
Set the value of the “scheme
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #scheme:=
value ]
user
a username, or Nothing
clearURIUser :: MonadIO m => URI -> m () Source #
Set the value of the “user
” field to Nothing
.
When overloading is enabled, this is equivalent to
clear
#user
getURIUser :: MonadIO m => URI -> m (Maybe Text) Source #
Get the value of the “user
” field.
When overloading is enabled, this is equivalent to
get
uRI #user
setURIUser :: MonadIO m => URI -> CString -> m () Source #
Set the value of the “user
” field.
When overloading is enabled, this is equivalent to
set
uRI [ #user:=
value ]