cro-uri
Cro::Uri
The Cro::Uri
class supports working with Uniform Resource Identifiers, as
specified in RFC 3986. A Cro::Uri
instance is immutable.
Parsing methods
There are a number of methods that parse a string into a Cro::Uri
instance.
They may all be called on the Cro::Uri
type object.
parse
Takes a string and attempts to parse it as an absolute URI.
Cro::Uri.parse("http://example.com");
By default this method uses an internal parser and action class that acts according to RFC 3986, however different parsers may be specified as a named parameter:
Cro::Uri.parse("http://example.com",
grammar => $custom-grammar,
actions => $custom-actions);
In case of parsing failure, the X::Cro::Uri::ParseError
exception will be
thrown. This exception has uri-string
field that contains the erroneous
string.
parse-relative
Takes a string and tries to parse it as a relative URI. Functions like parse
in terms of customization and error handling.
parse-ref
Takes a string and parses it as a URI reference (that is, either an absolute
or a relative URI). Functions like parse
in terms of customization and error
handling.
Getting URI parts
schema
Returns the schema of the URI. For example, given http://example.com/
, it
will return http
. For a relative URI, this will return a type object.
authority
Gets the authority part of the URI, if it has one. For example, given
http://[email protected]:42/baz
, it would return [email protected]:42
. If not present,
returns a type object.
userinfo
Gets the userinfo part of the authority, if it has one. For example, given
http://[email protected]:42/baz
, it would return foo
. If not present, returns a
type object.
user
Gets the user part of userinfo
, if present. Decodes any percent escape
sequences.
password
Gets the password part of userinfo
, if present. (Note that use of this is
deprecated by the URI specification. The functionality is provided here for
the convenience of those who need to work with such URIs, and will remain in
Cro for the foreseeable future.) Decodes any percent escape sequences.
host
Returns the host part of the authority, if it has one. For example, given
http://[email protected]:42/baz
, it would return bar
. If not present, returns a
type object. Any percent escape sequences in the host name will be decoded.
host-class
Provided there is a host, returns its class. This is returned as a member of
the Cro::Uri::Host
enumeration, which is defined as:
enum Cro::Uri::Host <RegName IPv4 IPv6 IPvFuture>;
If not present, returns a type object.
port
Returns the port
part of the authority, if present. For example, given
http://[email protected]:42/baz
it would return 42.
path
Returns the path part of the URI. URIs with an empty path part will return the
empty string. No percent decoding is performed by this method. For example,
given http://[email protected]:42/baz/oh%20wow
, it would return /baz/oh%20wow
.
path-segments
Returns a list of URI decoded path segments. Sequences outside of the ASCII
range will be decoded as UTF-8. Given http://[email protected]:42/baz/oh%20wow
,
this method would return the list ('baz', 'oh wow')
.
query
Returns the query string part of the URI. For example, given
http://bar.com:42/baz?x=1&y=2
, it would return x=1&y=2
. No percent
sequence decoding is performed. (For parsing of the query string as it is used
in HTTP applications, use Cro::Uri::HTTP
, which adds this functionality).
fragment
Returns the fragment part of the URI. For example, given
http://bar.com/baz#abc
, it would return abc
.
Stringifying a URI
The Str
method turns the URI back into a Str
.
Resolving relative URIs
The add
method implements resolution of a relative URI, taking the Cro::Uri
instance it is called on as the base. It may be called with either a string,
which will be parsed as a URI reference, or another Cro::Uri
object. Returns
a new Cro::Uri
instance representing the result of the resolution. Any .
and ..
sequences will be processed as part of the resolution.
my $base = Cro::Uri.parse('http://foo.com/bar/baz/wat.html');
say ~$base.add('../eek.html'); # http://foo.com/bar/eek.html
Percent decoding
The decode-percents
subroutine takes a string, and returns a new string
where all percent escape sequences are converted to Unicode characters
(assuming UTF-8 decoding).
This subroutine is not exported by default, but can be obtained by using the
decode-percents
tag:
use Cro::Uri :decode-percents;
Percent encoding
The encode-percents
subroutine takes a string, and returns a new string
where all characters that are not considered unreserved are percent encoded.
Non-ASCII characters will be encoding using UTF-8, and each byte percent
encoded.
This subroutine is not exported by default, but can be obtained by using the
encode-percents
tag:
use Cro::Uri :encode-percents;