This is a complete list of the methods you can call on a generic "URI" object once created by calling
"new". Some URIs are created in more specific classes (listed in the URIschemes section), which may
have additional methods. Arguments shown in square brackets below are optional.
Note that all the accessor methods, like "path" and "uri", can be used just to return the current value
(if they are called without an argument), or can set a new value while returning the old value. Passing
nil as the argument is generally different from not passing an argument at all, or to passing an empty
string.
uri:default_port()
Returns the default port used for this type of URI when no port number is supplied in the authority
part. This will be nil if the standard for the URI's current scheme doesn't specify a default port,
or if the scheme is one which this library doesn't have any special understanding of.
local uri = assert(URI:new("http://example.com:123/"))
print(uri:default_port()) -- 80
uri:eq(other)
Returns true if the two URI objects contain the same URI. "other" can also be a string, which will
be converted to a URI object (in order for the normalization to be done).
This can also be called as a stand-alone function if you don't know whether either URI is an object
or a string. For example:
print(URI.eq("http://example.com",
"HTTP://EXAMPLE.COM/"))
If either value is a string which isn't a valid URI, this will throw an exception. It will however
accept relative URIs, and they will be compared as normal. A relative URI is never equal to an
absolute one.
There is no less-than comparison function, as URIs don't have any particular ordering. If you want
to sort URI objects you're best bet is probably just to compare the string versions:
function urisort (a, b)
return a:uri() < b:uri()
end
table.sort(t, urisort)
uri:fragment([newvalue])
Returns the current fragment part of the URI (the part after the "#" character), or nil if the URI
has no fragment part. Note that an empty fragment (zero characters long) is different from one which
is completely missing.
If "newvalue" is supplied, changes the fragment to the new value, percent encoding any characters
which would not be valid in a fragment part. Any percent encoding already done on the string will be
left in place (not double encoded). If "newvalue" is nil then any existing fragment will be removed.
The syntax of fragments are meaningful only for particular media types of resources, so there is no
special behaviour for different URI schemes.
uri:host([newvalue])
Get and set the host part of the authority in a URI. This can be a domain name, an IPv4 address
(four numbers separated by dots), or an IPv6 address (which must include the enclosing square
brackets used in URIs).
When setting a new host, the value is normalized to lowercase. An invalid value will cause an
exception to be thrown. The value can be an empty string to indicate the default host.
Setting the value to nil will cause the host to be removed altogether, leaving the URI with no
authority component. This will throw an exception if there is a userinfo or port component in the
URI, because it is impossible to represent a URI with no host when there is an authority component.
Some URI schemes may throw an exception when setting the host to nil or the empty string, and others
when setting it to anything other than nil, if those schemes require or disallow authority
components.
uri:init()
This method is called internally to make a URI object belong to the right class and do any scheme-
specific validation an normalization. It is only of interest if you want to write a new "uri"
subclass for particular types of URIs.
The implementation in the "uri" class itself changes the class of the object to the one appropriate
to the scheme (if there is a more specific class available). It also removes the port number from
the authority component if it is unnecessary because the scheme defines it as the default port.
Finally, if there is a more specific class available it calls the "init" method in that.
"init" is called after the URI has been split into components according to the generic syntax, so it
can use the accessor methods to get at them. It should return the same values as "new", either the
new URI object (the object it was called on), or nil and an error message.
uri:is_relative()
Returns true if this is a relative URI reference, false otherwise. All relative URIs belong to the
class "uri._relative". All the other URI classes are for absolute URIs.
uri:path([newvalue])
Get or set the path component of the URI. Throws an exception if the new value is not valid in the
context of the rest of the URI.
local uri = assert(URI:new("http://example.com/foo"))
local old = uri:path("/bar/")
print(old) -- /foo
print(uri:path()) -- /bar/
When a new path value is supplied, it can already be percent encoded, but any characters which aren't
allowed are encoded as well. Percent characters are not encoded themselves, because they are assumed
to be part of the existing encoding. The existing percent encoding is normalized, and any invalid
encoding will cause an exception.
There are certain paths which cannot be expressed in the URI syntax. A path which does not start
with a "/" character (unless it's completely empty) cannot be represented when there is an authority
component, so this will cause an exception to be thrown. A path which starts with "//" when there is
no authority component would be misinterpreted, so the second slash is percent encoded.
Some URI schemes may impose further restrictions on what is allowed in a path, so other path values
may cause exceptions in certain cases.
uri:port([newvalue])
Get or set the port number in a URI. The value returned is always an integer number or nil.
If "newvalue" is supplied it should be a non-negative integer number, or a string containing only
digits, or nil to remove any existing port number. An exception is thrown if it is an invalid value,
or if the URI scheme doesn't allow port numbers to be specified. If there is currently no authority
part in the URI, then an empty host will be added to create one.
If the port number is the default for a URI scheme (the same as the number returned from the
"default_port" method), then the "port" method will return that number, but the number won't actually
be shown in the URI when it is represented as a string, because it would be redundant. Setting the
port number to nil has the same effect as setting it to the default port number.
uri:query([newvalue])
Get or set the query part of a URI.
If "newvalue" is supplied it should be the new string, or nil to remove any existing query part. The
query part can be an empty string, which is different from it not being present at all (the "?"
character will still be included to indicate that there is a query part, even if it is not followed
by anything else). Any characters which would not be valid in a query part will be percent encoded,
but any percent encoding already done on the string will be left in place (not double encoded).
The base-class implementation of this method never throws exceptions, but some scheme-specific
classes may throw exceptions if they impose constraints on the syntax of query parts.
uri:resolve(base)
Given an object representing a relative URI, resolve it against the base URI "base" (which can be a
URI object or string) and update the "uri" object to contain an absolute URI.
Has no effect if "uri" is already an absolute URI. Throws an exception if "base" is not an absolute
URI, or if the new URI formed by combining them would be invalid for the given scheme.
See also the section RelativeURIs and the "uri:relativize(base)" method.
uri:scheme([newvalue])
Get and set the scheme of the URI. Altering the scheme of an existing URI is very unlikely to be
useful.
Throws an exception if "newvalue" is nil or not a valid scheme, or if the rest of the URI is not
valid when interpreted with the new scheme. After calling this method the class of the object may
have been changed, if the old class is not appropriate for the new value.
uri:relativize(base)
If possible, update the absolute URI "uri" to contain a relative URI which, when resolved again
against "base", will yield the original URI value. This doesn't return anything, just modifies the
object.
Has no effect if "uri" is already relative, or if there is no way to create an appropriate relative
URI (so the URI will remain absolute for example if "base" has a different scheme from "uri").
Throws an exception if "base" is not absolute.
This method will never result in a network-path reference (a relative URI which includes an authority
part). In cases where that would be possible the value in "uri" will be left as an absolute URI,
which is less likely to cause problems.
See also the section RelativeURIs and the "uri:resolve(base)" method.
uri:uri([newvalue])
Returns the URI value as a string. The return value is the same as you'll get from "tostring(uri)".
If an argument is supplied, this replaces the URI in the "uri" object with a different one.
"newvalue" must be a complete new URI or relative URI reference in a string, or a URI object.
This is equivalent to creating a new URI object by calling "URI:new", except that instead of creating
a new object the existing object is updated with the new information. It is also not possible to
pass a base URI to the "uri" method.
Throws an exception if "newvalue" is nil or if there is any error in parsing the new URI string.
After calling this method the class of the object may have been changed, if the old class is not
appropriate for the new value.
uri:userinfo([newvalue])
Get or set the userinfo part of the URI. If "newvalue" is supplied then it is expected to be percent
encoded already. Percent encoding is normalized. An exception will be thrown if the new value is
invalid, or if the URI scheme does not allow a userinfo part (for example if it is an HTTP URI). If
there is currently no authority part in the URI, then an empty host will be added to create one.
If "newvalue" is nil then any existing userinfo part is removed.
Install Now
PNG Icons
