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

Exported types
Methods
Properties

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

Synopsis

Exported types

newtype URI Source #

Constructors

URI (ManagedPtr URI)

Instances

BoxedObject URI Source #
Methods boxedType :: URI -> IO GType #
(~) AttrOpTag tag AttrSet => Constructible URI tag Source #
Methods new :: MonadIO m => (ManagedPtr URI -> URI) -> [AttrOp URI tag] -> m URI #
((~) * info (ResolveURIMethod t URI), MethodInfo * info URI p) => IsLabel t (URI -> p) Source #
Methods fromLabel :: Proxy# Symbol t -> URI -> p #
((~) * info (ResolveURIMethod t URI), MethodInfo * info URI p) => IsLabelProxy t (URI -> p) Source #
Methods fromLabelProxy :: Proxy Symbol t -> URI -> p #
HasAttributeList * URI Source #

((~) * signature (m Bool), MonadIO m) => MethodInfo * URIUsesDefaultPortMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIUsesDefaultPortMethodInfo URI -> signature -> s #
((~) * signature (Bool -> m Text), MonadIO m) => MethodInfo * URIToStringMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIToStringMethodInfo URI -> signature -> s #
((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetUserMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetUserMethodInfo URI -> signature -> s #
((~) * signature (Text -> m ()), MonadIO m) => MethodInfo * URISetSchemeMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetSchemeMethodInfo URI -> signature -> s #
((~) * signature (Map Text Text -> m ()), MonadIO m) => MethodInfo * URISetQueryFromFormMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetQueryFromFormMethodInfo URI -> signature -> s #
((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetQueryMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetQueryMethodInfo URI -> signature -> s #
((~) * signature (Word32 -> m ()), MonadIO m) => MethodInfo * URISetPortMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetPortMethodInfo URI -> signature -> s #
((~) * signature (Text -> m ()), MonadIO m) => MethodInfo * URISetPathMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetPathMethodInfo URI -> signature -> s #
((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetPasswordMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetPasswordMethodInfo URI -> signature -> s #
((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetHostMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetHostMethodInfo URI -> signature -> s #
((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetFragmentMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetFragmentMethodInfo URI -> signature -> s #
((~) * signature (Text -> m URI), MonadIO m) => MethodInfo * URINewWithBaseMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URINewWithBaseMethodInfo URI -> signature -> s #
((~) * signature (m Word32), MonadIO m) => MethodInfo * URIHostHashMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIHostHashMethodInfo URI -> signature -> s #
((~) * signature (URI -> m Bool), MonadIO m) => MethodInfo * URIHostEqualMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIHostEqualMethodInfo URI -> signature -> s #
((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetUserMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetUserMethodInfo URI -> signature -> s #
((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetSchemeMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetSchemeMethodInfo URI -> signature -> s #
((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetQueryMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetQueryMethodInfo URI -> signature -> s #
((~) * signature (m Word32), MonadIO m) => MethodInfo * URIGetPortMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetPortMethodInfo URI -> signature -> s #
((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetPathMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetPathMethodInfo URI -> signature -> s #
((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetPasswordMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetPasswordMethodInfo URI -> signature -> s #
((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetHostMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetHostMethodInfo URI -> signature -> s #
((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetFragmentMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetFragmentMethodInfo URI -> signature -> s #
((~) * signature (m ()), MonadIO m) => MethodInfo * URIFreeMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIFreeMethodInfo URI -> signature -> s #
((~) * signature (URI -> m Bool), MonadIO m) => MethodInfo * URIEqualMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIEqualMethodInfo URI -> signature -> s #
((~) * signature (m URI), MonadIO m) => MethodInfo * URICopyHostMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URICopyHostMethodInfo URI -> signature -> s #
((~) * signature (m URI), MonadIO m) => MethodInfo * URICopyMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URICopyMethodInfo URI -> signature -> s #
type AttributeList URI Source #
type AttributeList URI

newZeroURI :: MonadIO m => m URI Source #

Construct a URI struct initialized to zero.

noURI :: Maybe URI Source #

Methods

copy

data URICopyMethodInfo Source #

Instances

((~) * signature (m URI), MonadIO m) => MethodInfo * URICopyMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URICopyMethodInfo URI -> signature -> s #

uRICopy Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m URI	Returns: a copy of `uri`, which must be freed with `uRIFree`

Copies uri

copyHost

data URICopyHostMethodInfo Source #

Instances

((~) * signature (m URI), MonadIO m) => MethodInfo * URICopyHostMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URICopyHostMethodInfo URI -> signature -> s #

uRICopyHost Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m URI	Returns: the new `URI`

Makes a copy of uri, considering only the protocol, host, and port

Since: 2.28

decode

uRIDecode Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`part`: a URI part
-> m Text	Returns: the decoded URI part.

Fully %-decodes part.

In the past, this would return Nothing if part contained invalid percent-encoding, but now it just ignores the problem (as uRINew already did).

encode

uRIEncode Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`part`: a URI part
-> Maybe Text	`escapeExtra`: additional reserved characters to escape (or `Nothing`)
-> 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

data URIEqualMethodInfo Source #

Instances

((~) * signature (URI -> m Bool), MonadIO m) => MethodInfo * URIEqualMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIEqualMethodInfo URI -> signature -> s #

uRIEqual Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri1`: a `URI`
-> URI	`uri2`: another `URI`
-> m Bool	Returns: `True` or `False`

Tests whether or not uri1 and uri2 are equal in all parts

free

data URIFreeMethodInfo Source #

Instances

((~) * signature (m ()), MonadIO m) => MethodInfo * URIFreeMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIFreeMethodInfo URI -> signature -> s #

uRIFree Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m ()

Frees uri.

getFragment

data URIGetFragmentMethodInfo Source #

Instances

((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetFragmentMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetFragmentMethodInfo URI -> signature -> s #

uRIGetFragment Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Text	Returns: `uri`'s fragment.

Gets uri's fragment.

Since: 2.32

getHost

data URIGetHostMethodInfo Source #

Instances

((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetHostMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetHostMethodInfo URI -> signature -> s #

uRIGetHost Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Text	Returns: `uri`'s host.

Gets uri's host.

Since: 2.32

getPassword

data URIGetPasswordMethodInfo Source #

Instances

((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetPasswordMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetPasswordMethodInfo URI -> signature -> s #

uRIGetPassword Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Text	Returns: `uri`'s password.

Gets uri's password.

Since: 2.32

getPath

data URIGetPathMethodInfo Source #

Instances

((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetPathMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetPathMethodInfo URI -> signature -> s #

uRIGetPath Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Text	Returns: `uri`'s path.

Gets uri's path.

Since: 2.32

getPort

data URIGetPortMethodInfo Source #

Instances

((~) * signature (m Word32), MonadIO m) => MethodInfo * URIGetPortMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetPortMethodInfo URI -> signature -> s #

uRIGetPort Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Word32	Returns: `uri`'s port.

Gets uri's port.

Since: 2.32

getQuery

data URIGetQueryMethodInfo Source #

Instances

((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetQueryMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetQueryMethodInfo URI -> signature -> s #

uRIGetQuery Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Text	Returns: `uri`'s query.

Gets uri's query.

Since: 2.32

getScheme

data URIGetSchemeMethodInfo Source #

Instances

((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetSchemeMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetSchemeMethodInfo URI -> signature -> s #

uRIGetScheme Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Text	Returns: `uri`'s scheme.

Gets uri's scheme.

Since: 2.32

getUser

data URIGetUserMethodInfo Source #

Instances

((~) * signature (m Text), MonadIO m) => MethodInfo * URIGetUserMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIGetUserMethodInfo URI -> signature -> s #

uRIGetUser Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Text	Returns: `uri`'s user.

Gets uri's user.

Since: 2.32

hostEqual

data URIHostEqualMethodInfo Source #

Instances

((~) * signature (URI -> m Bool), MonadIO m) => MethodInfo * URIHostEqualMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIHostEqualMethodInfo URI -> signature -> s #

uRIHostEqual Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`v1`: a `URI` with a non-`Nothing` `host` member
-> URI	`v2`: a `URI` with a non-`Nothing` `host` member
-> 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

data URIHostHashMethodInfo Source #

Instances

((~) * signature (m Word32), MonadIO m) => MethodInfo * URIHostHashMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIHostHashMethodInfo URI -> signature -> s #

uRIHostHash Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`key`: a `URI` with a non-`Nothing` `host` member
-> m Word32	Returns: a hash

Hashes key, considering only the scheme, host, and port.

Since: 2.28

new

uRINew Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Maybe Text	`uriString`: a URI
-> m (Maybe URI)	Returns: a `URI`, or `Nothing` if the given string was found to be invalid.

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

data URINewWithBaseMethodInfo Source #

Instances

((~) * signature (Text -> m URI), MonadIO m) => MethodInfo * URINewWithBaseMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URINewWithBaseMethodInfo URI -> signature -> s #

uRINewWithBase Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`base`: a base URI
-> Text	`uriString`: the URI
-> m URI	Returns: a parsed `URI`.

Parses uriString relative to base.

normalize

uRINormalize Source #

Arguments

:: (HasCallStack, MonadIO m)
=> Text	`part`: a URI part
-> Maybe Text	`unescapeExtra`: reserved characters to unescape (or `Nothing`)
-> 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

data URISetFragmentMethodInfo Source #

Instances

((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetFragmentMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetFragmentMethodInfo URI -> signature -> s #

uRISetFragment Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Maybe Text	`fragment`: the fragment
-> m ()

Sets uri's fragment to fragment.

setHost

data URISetHostMethodInfo Source #

Instances

((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetHostMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetHostMethodInfo URI -> signature -> s #

uRISetHost Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Maybe Text	`host`: the hostname or IP address, or `Nothing`
-> 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

data URISetPasswordMethodInfo Source #

Instances

((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetPasswordMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetPasswordMethodInfo URI -> signature -> s #

uRISetPassword Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Maybe Text	`password`: the password, or `Nothing`
-> m ()

Sets uri's password to password.

setPath

data URISetPathMethodInfo Source #

Instances

((~) * signature (Text -> m ()), MonadIO m) => MethodInfo * URISetPathMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetPathMethodInfo URI -> signature -> s #

uRISetPath Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Text	`path`: the non-`Nothing` path
-> m ()

Sets uri's path to path.

setPort

data URISetPortMethodInfo Source #

Instances

((~) * signature (Word32 -> m ()), MonadIO m) => MethodInfo * URISetPortMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetPortMethodInfo URI -> signature -> s #

uRISetPort Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Word32	`port`: the port, or 0
-> m ()

Sets uri's port to port. If port is 0, uri will not have an explicitly-specified port.

setQuery

data URISetQueryMethodInfo Source #

Instances

((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetQueryMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetQueryMethodInfo URI -> signature -> s #

uRISetQuery Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Maybe Text	`query`: the query
-> m ()

Sets uri's query to query.

setQueryFromForm

data URISetQueryFromFormMethodInfo Source #

Instances

((~) * signature (Map Text Text -> m ()), MonadIO m) => MethodInfo * URISetQueryFromFormMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetQueryFromFormMethodInfo URI -> signature -> s #

uRISetQueryFromForm Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Map Text Text	`form`: a `HashTable` containing HTML form information
-> m ()

Sets uri's query to the result of encoding form according to the HTML form rules. See formEncodeHash for more information.

setScheme

data URISetSchemeMethodInfo Source #

Instances

((~) * signature (Text -> m ()), MonadIO m) => MethodInfo * URISetSchemeMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetSchemeMethodInfo URI -> signature -> s #

uRISetScheme Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Text	`scheme`: the URI scheme
-> m ()

Sets uri's scheme to scheme. This will also set uri's port to the default port for scheme, if known.

setUser

data URISetUserMethodInfo Source #

Instances

((~) * signature (Maybe Text -> m ()), MonadIO m) => MethodInfo * URISetUserMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URISetUserMethodInfo URI -> signature -> s #

uRISetUser Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Maybe Text	`user`: the username, or `Nothing`
-> m ()

Sets uri's user to user.

toString

data URIToStringMethodInfo Source #

Instances

((~) * signature (Bool -> m Text), MonadIO m) => MethodInfo * URIToStringMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIToStringMethodInfo URI -> signature -> s #

uRIToString Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> Bool	`justPathAndQuery`: if `True`, output just the path and query portions
-> m Text	Returns: a string representing `uri`, which the caller must free.

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

data URIUsesDefaultPortMethodInfo Source #

Instances

((~) * signature (m Bool), MonadIO m) => MethodInfo * URIUsesDefaultPortMethodInfo URI signature Source #
Methods overloadedMethod :: MethodProxy URIUsesDefaultPortMethodInfo URI -> signature -> s #

uRIUsesDefaultPort Source #

Arguments

:: (HasCallStack, MonadIO m)
=> URI	`uri`: a `URI`
-> m Bool	Returns: `True` or `False`

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