URI::URL objects are created by calling new(), which takes as argument a string representation of the URL or an existing URL object reference to be cloned. Specific individual elements can then be accessed via the scheme(), user(), password(), host(), port(), path(), params(), query() and frag() methods. In addition escaped versions of the path, params and query can be accessed with the epath(), eparams() and equery() methods. Note that some URL schemes will support all these methods.

The object constructor new() must be able to determine the scheme for the URL. If a scheme is not specified in the URL itself, it will use the scheme specified by the base URL. If no base URL scheme is defined then new() will croak if URI::URL::strict(1) has been invoked, otherwise http is silently assumed. Once the scheme has been determined new() then uses the implementor() function to determine which class implements that scheme. If no implementor class is defined for the scheme then new() will croak if URI::URL::strict(1) has been invoked, otherwise the internal generic URL class is assumed.

Internally defined schemes are implemented by the URI::URL::scheme_name module. The URI::URL::implementor() function can be used to explicitly set the class used to implement a scheme if you want to override this.

HOW AND WHEN TO ESCAPE

This is an edited extract from a URI specification:

The printability requirement has been met by specifying a safe set of characters, and a general escaping scheme for encoding "unsafe" characters. This "safe" set is suitable, for example, for use in electronic mail. This is the canonical form of a URI.

There is a conflict between the need to be able to represent many characters including spaces within a URI directly, and the need to be able to use a URI in environments which have limited character sets or in which certain characters are prone to corruption. This conflict has been resolved by use of an hexadecimal escaping method which may be applied to any characters forbidden in a given context. When URLs are moved between contexts, the set of characters escaped may be enlarged or reduced unambiguously. The canonical form for URIs has all white spaces encoded.

The components of a URL string must be individually escaped. Each component of a URL may have a separate requirements regarding what must be escaped, and those requirements are also dependent on the URL scheme.

Never escape an already escaped component string.

This implementation expects an escaped URL string to be passed to new() and will return a fully escaped URL string from as_string() and full_path().

Individual components can be manipulated in unescaped or escaped form. The following methods return/accept unescaped strings:

scheme path
user params
password query
host frag
port

The following methods return/accept partial escaped strings:

netloc eparams
epath equery

Partial escaped means that only reserved characters (i.e. ':', '@', '/', ';', '?', '=', '&' in addition to '%', '.' and '#') needs to be escaped when they are to be treated as normal characters. Fully escaped means that all unsafe characters are escaped. Unsafe characters are all all control characters (%00-%1F and %7F), all 8-bit characters (%80-%FF) as well as '{', '}', '|', '\', '^', '[', ']' '`', '"', '<' and '>'. Note that the character '~' is not considered unsafe by this library as it is common practice to use it to reference personal home pages, but it is still unsafe according to RFC 1738.

ADDING NEW URL SCHEMES

New URL schemes or alternative implementations for existing schemes can be added to your own code. To create a new scheme class use code like:

The 'URI::URL::implementor()' function call with no parameters returns the name of the class which implements the generic URL scheme behaviour (typically URI::URL::_generic). All hierarchical schemes should be derived from this class.

To register your new class as the implementor for a specific scheme use code like:

URI::URL::implementor('x-foo', 'MYURL::foo');

Any new URL created for scheme 'x-foo' will be implemented by your MYURL::foo class. Existing URLs will not be affected.

FUNCTIONS

new URI::URL $url_string [, $base_url]

This is the object constructor. It will create a new URI::URL object, initialized from the URL string. To trap bad or unknown URL schemes use:

$obj = eval { new URI::URL "snews:comp.lang.perl.misc" };

or set URI::URL::strict(0) if you do not care about bad or unknown schemes.

newlocal URI::URL $path;

Returns an URL object that denotes a path within the local filesystem. Paths not starting with '/' are interpreted relative to the current working directory. This constructor always return an absolute 'file' URL.

url($url_string, [, $base_url])

Alternative constructor function. The url() function is exported by the URI::URL module and is easier both to type and read than calling URI::URL->new directly. Useful for constructs like this:

$h = url($str)->host;

This function is just a wrapper for URI::URL->new.

URI::URL::strict($bool)

If strict is true then we croak on errors. The function returns the previous value.

URI::URL::implementor([$scheme, [$class]])

Use this function to get or set implementor class for a scheme. Returns '' if specified scheme is not supported. Returns generic URL class if no scheme specified.

METHODS

This section describes the methods available for an URI::URL object. Note that some URL schemes will disallow some of these methods and will croak if they are used. Some URL schemes add additional methods that are described in the sections to follow.

Attribute access methods marked with (*) can take an optional argument to set the value of the attribute, and they always return the old value.

$url->abs([$base, [$allow_scheme_in_relative_urls]])

The abs() method attempts to return a new absolute URI::URL object for a given URL. In order to convert a relative URL into an absolute one, a base URL is required. You can associate a default base with a URL either by passing a base to the new() constructor when a URI::URL is created or using the base() method on the object later. Alternatively you can specify a one-off base as a parameter to the abs() method.

Some older parsers used to allow the scheme name to be present in the relative URL if it was the same as the base URL scheme. RFC1808 says that this should be avoided, but you can enable this old behaviour by passing a TRUE value as the second argument to the abs() method. The difference is demonstrated by the following examples:

Returns a string representing the URL in its canonical form. All unsafe characters will be escaped. This method is overloaded as the perl "stringify" operator, which means that URLs can be used as strings in many contexts.

$url->base (*)

Get/set the base URL associated with the current URI::URL object. The base URL matters when you call the abs() method.

All elements except scheme will be undefined if the corresponding URL part is not available.

Note: The scheme (first element) returned by crack will aways be defined. This is different from what the $url->scheme returns, since it will return undef for relative URLs.

$url->default_port

Returns the default port number for the URL scheme that the URI::URL belongs too.

$url->eparams (*)

Get/set the URL parameters in escaped form.

$url->epath (*)

Get/set the URL path in escaped form.

$url->eq($other_url)

Compare two URLs to decide if they match or not. The rules for how comparison is made varies for different parts of the URLs; scheme and netloc comparison is case-insensitive, and escaped chars match their %XX encoding unless they are "reserved" or "unsafe".

$url->equery (*)

Get/set the URL query string in escaped form.

$url->full_path

Returns the string "/path;params?query". This is the string that is passed to a remote server in order to access the document.

Get/set the path (unescaped). This method will croak if any of the path components in the return value contain the "/" character. You should use the epath() method to be safe.

$url->path_components (*)

Get/set the path using a list of unescaped path components. The return value will loose the distinction beween '.' and '%2E'. When setting a value, a '.' is converted to be a literal '.' and is therefore encoded as '%2E'.

$url->port (*)

Get/set the network port (unescaped)

$url->rel([$base])

Return a relative URL if possible. This is the opposite of what the abs() method does. For instance:

FILE METHODS

The file URLs implement the local_path() method that returns a path suitable for access to files within the current filesystem. These methods can not be used to set the path of the URL.

$url->local_path

This method is really just an alias for one of the methods below depending on what system you run on.

$url->unix_path

Returns a path suitable for use on a Unix system. This method will croak if any of the path segments contains a "/" or a NULL character.

$url->dos_path

Returns a path suitable for use on a MS-DOS or MS-Windows system.

$url->mac_path

Returns a path suitable for use on a Macintosh system.

$url->vms_path

Returns a path suitable for use on a VMS system. VMS is a trademark of Digital.

GOPHER METHODS

The methods access the parts that are specific for the gopher URLs. These methods access different parts of the $url->path.

$url->gtype (*)

$url->selector (*)

$url->search (*)

$url->string (*)

NEWS METHODS

$url->group (*)

$url->article (*)

WAIS METHODS

The methods access the parts that are specific for the wais URLs. These methods access different parts of the $url->path.

$url->database (*)

$url->wtype (*)

$url->wpath (*)

MAILTO METHODS

$url->address (*)

The mail address can also be accessed with the netloc() method.

WHAT A URL IS NOT

URL objects do not, and should not, know how to 'get' or 'put' the resources they specify locations for, anymore than a postal address 'knows' anything about the postal system. The actual access/transfer should be achieved by some form of transport agent class (see LWP::UserAgent). The agent class can use the URL class, but should not be a subclass of it.

COMPATIBILITY

This is a listing incompatibilities with URI::URL version 3.x:

unsafe(), escape() and unescape()

These methods not supported any more.

full_path() and as_string()

These methods does no longer take a second argument which specify the set of characters to consider as unsafe.

'+' in the query-string

The '+' character in the query part of the URL was earlier considered to be an encoding of a space. This was just bad influence from Mosaic. Space is now encoded as '%20'.

path() and query()

This methods will croak if they loose information. Use epath() or equery() instead. The path() method will for instance loose information if any path segment contain an (encoded) '/' character.

The path() now consider a leading '/' to be part of the path. If the path is empty it will default to '/'. You can get the old behaviour by setting $URI::URL::COMPAT_VER_3 to TRUE before accessing the path() method.

netloc()

The string passed to netloc is now assumed to be escaped. The string returned will also be (partially) escaped.

sub-classing

The path, params and query is now stored internally in unescaped form. This might affect sub-classes of the URL scheme classes.

AUTHORS / ACKNOWLEDGMENTS

This module is (distantly) based on the wwwurl.pl code in the libwww-perl distribution developed by Roy Fielding <fielding@ics.uci.edu>, as part of the Arcadia project at the University of California, Irvine, with contributions from Brooks Cutter.

Gisle Aas <aas@sn.no>, Tim Bunce <Tim.Bunce@ig.co.uk>, Roy Fielding <fielding@ics.uci.edu> and Martijn Koster <m.koster@webcrawler.com> (in English alphabetical order) have collaborated on the complete rewrite for Perl 5, with input from other people on the libwww-perl mailing list.

If you have any suggestions, bug reports, fixes, or enhancements, send them to the libwww-perl mailing list at <libwww-perl@ics.uci.edu>.

COPYRIGHT

Copyright 1995-1996 Gisle Aas. Copyright 1995 Martijn Koster.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.