URI - Uniform Resource Identifiers (absolute and relative)


SYNOPSIS

        $u1 = URI->new("http://www.perl.com");
        $u2 = URI->new("foo", "http");
        $u3 = $u2->abs($u1);
        $u4 = $u3->clone;
        $u5 = URI->new("HTTP://WWW.perl.com:80")->canonical;

        $str = $u->as_string;
        $str = "$u";

        $scheme = $u->scheme;
        $opaque = $u->opaque;
        $path   = $u->path;
        $frag   = $u->fragment;

        $u->scheme("ftp");
        $u->host("ftp.perl.com");
        $u->path("cpan/");


DESCRIPTION

       This module implements the `URI' class.  Objects of this
       class represent "Uniform Resource Identifier references"
       as specified in RFC 2396.

       A Uniform Resource Identifier is a compact string of char­
       acters for identifying an abstract or physical resource.
       A Uniform Resource Identifier can be further classified
       either a Uniform Resource Locator (URL) or a Uniform
       Resource Name (URN).  The distinction between URL and URN
       does not matter to the `URI' class interface. A "URI-ref­
       erence" is a URI that may have additional information
       attached in the form of a fragment identifier.

       An absolute URI reference consists of three parts.  A
       scheme, a scheme specific part and a fragment identifier.
       A subset of URI references share a common syntax for hier­
       archical namespaces.  For these the scheme specific part
       is further broken down into authority, path and query com­
       ponents.  These URI can also take the form of relative URI
       references, where the scheme (and usually also the author­
       ity) component is missing, but implied by the context of
       the URI reference.  The three forms of URI reference syn­
       tax are summarized as follows:

         <scheme>:<scheme-specific-part>#<fragment>
         <scheme>://<authority><path>?<query>#<fragment>
         <path>?<query>#<fragment>

       The components that a URI reference can be divided into
       depend on the scheme.  The `URI' class provides methods to

       able for a specific `URI' object depend on the scheme.


CONSTRUCTORS

       The following methods construct new `URI' objects:

       $uri = URI->new( $str, [$scheme] )
           This class method constructs a new URI object.  The
           string representation of a URI is given as argument
           together with an optional scheme specification.  Com­
           mon URI wrappers like "" and <>, as well as leading
           and trailing white space, are automatically removed
           from the $str argument before it is processed further.

           The constructor determines the scheme, maps this to an
           appropriate URI subclass, constructs a new object of
           that class and returns it.

           The $scheme argument is only used when $str is a rela­
           tive URI.  It can either be a simple string that
           denotes the scheme, a string containing an absolute
           URI reference or an absolute `URI' object.  If no
           $scheme is specified for a relative URI $str, then
           $str is simply treated as a generic URI (no scheme
           specific methods available).

           The set of characters available for building URI ref­
           erences is restricted (see the URI::Escape manpage).
           Characters outside this set are automatically escaped
           by the URI constructor.

       $uri = URI->new_abs( $str, $base_uri )
           This constructs a new absolute URI object.  The $str
           argument can denote a relative or absolute URI.  If
           relative, then it will be absolutized using $base_uri
           as base. The $base_uri must be an absolute URI.

       $uri = URI::file->new( $filename, [$os] )
           This constructs a new file URI from a file name.  See
           the URI::file manpage.

       $uri = URI::file->new_abs( $filename, [$os] )
           This constructs a new absolute file URI from a file
           name.  See the URI::file manpage.

       $uri = URI::file->cwd
           This returns the current working directory as a file
           URI.  See the URI::file manpage.

       $uri->clone
           This method returns a copy of the $uri.


COMMON METHODS

       The methods described in this section are available for


       Methods that give access to components of a URI will
       always return the old value of the component.  The value
       returned will be `undef' if the component was not present.
       There is generally a difference between a component that
       is empty (represented as `""') and a component that is
       missing (represented as `undef').  If an accessor method
       is given an argument it will update the corresponding com­
       ponent in addition to returning the old value of the com­
       ponent.  Passing an undefined argument will remove the
       component (if possible).  The description of the various
       accessor methods will tell if the component is passed as
       an escaped or an unescaped string.  Components that can be
       futher divided into sub-parts are usually passed escaped,
       as unescaping might change its semantics.

       The common methods available for all URI are:

       $uri->scheme( [$new_scheme] )
           This method sets and returns the scheme part of the
           $uri.  If the $uri is relative, then $uri->scheme
           returns `undef'.  If called with an argument, it will
           update the scheme of $uri, possibly changing the class
           of $uri, and return the old scheme value.  The method
           croaks if the new scheme name is illegal; scheme names
           must begin with a letter and must consist of only US-
           ASCII letters, numbers, and a few special marks: ".",
           "+", "-".  This restriction effectively means that
           scheme have to be passed unescaped.  Passing an unde­
           fined argument to the scheme method will make the URI
           relative (if possible).

           Letter case does not matter for scheme names.  The
           string returned by $uri->scheme is always lowercase.
           If you want the scheme just as it was written in the
           URI in its original case, you can use the
           $uri->_scheme method instead.

       $uri->opaque( [$new_opaque] )
           This method sets and returns the scheme specific part
           of the $uri (everything between the scheme and the
           fragment) as an escaped string.

       $uri->path( [$new_path] )
           This method sets and returns the same value as
           $uri->opaque unless the URI supports the generic syn­
           tax for hierarchical namespaces.  In that case the
           generic method is overridden to set and return the
           part of the URI between the host name and the frag­
           ment.

       $uri->fragment( [$new_frag] )
           This method returns the fragment identifier of a URI


       $uri->as_string
           This method returns a URI object to a plain string.
           URI objects are also converted to plain strings auto­
           matically by overloading.  This means that $uri
           objects can be used as plain strings in most Perl con­
           structs.

       $uri->canonical
           This method will return a normalized version of the
           URI.  The rules for normalization are scheme depen­
           dent.  It usually involves lowercasing of the scheme
           and the Internet host name components, removing the
           explicit port specification if it matches the default
           port, uppercasing all escape sequences, and unescaping
           octets that can be better represented as plain charac­
           ters.

           For efficiency reasons, if the $uri already was in
           normalized form, then a reference to it is returned
           instead of a copy.

       $uri->eq( $other_uri )

       URI::eq( $first_uri, $other_uri )
           This method tests whether two URI references are
           equal.  URI references that normalize to the same
           string are considered equal.  The method can also be
           used as a plain function which can also test two
           string arguments.

           If you need to test whether two `URI' object refer­
           ences denote the same object, use the '==' operator.

       $uri->abs( $base_uri )
           This method returns an absolute URI reference.  If
           $uri already is absolute, then a reference to it is
           simply returned.  If the $uri is relative, then a new
           absolute URI is constructed by combining the $uri and
           the $base_uri, and returned.

       $uri->rel( $base_uri )
           This method returns a relative URI reference if it is
           possible to make one that denotes the same resource
           relative to $base_uri.  If not, then $uri is simply
           returned.


GENERIC METHODS

       The following methods are available to schemes that use
       the common/generic syntax for hierarchical namespaces.
       The description of schemes below will tell which one these
       are.  Unknown schemes are assumed to support the generic
       syntax, and therefore the following methods:

           This method sets and returns the escaped authority
           component of the $uri.

       $uri->path( [$new_path] )
           This method sets and returns the escaped path compo­
           nent of the $uri (the part between the host name and
           the query or fragment).  The path will never be unde­
           fined, but it can be the empty string.

       $uri->path_query( [$new_path_query] )
           This method sets and returns the escaped path and
           query components as a single entity.  The path and the
           query are separated by a "?" character, but the query
           can itself contain "?".

       $uri->path_segments( [$segment,...] )
           This method sets and returns the path.  In scalar con­
           text it returns the same value as $uri->path.  In list
           context it will return the unescaped path segments
           that make up the path.  Path segments that have param­
           eters are returned as an anonymous array.  The first
           element is the unescaped path segment proper.  Subse­
           quent elements are escaped parameter strings.  Such an
           anonymous array uses overloading so it can be treated
           as a string too, but this string does not include the
           parameters.

       $uri->query( [$new_query] )
           This method sets and returns the escaped query compo­
           nent of the $uri.

       $uri->query_form( [$key => $value,...] )
           This method sets and returns query components that use
           the application/x-www-form-urlencoded format.
           Key/value pairs are separated by "&" and the key is
           separated from the value with a "=" character.

       $uri->query_keywords( [$keywords,...] )
           This method sets and returns query components that use
           the keywords separated by "+" format.


SERVER METHODS

       Schemes where the authority component denotes a Internet
       host will have the following methods available in addition
       to the generic methods.

       $uri->userinfo( [$new_userinfo] )
           This method sets and returns the escaped userinfo part
           of the authority componenent.

           For some schemes this will be a user name and a pass­
           word separated by a colon.  This practice is not rec­
           ommended. Embedding passwords in clear text (such as

           case where it has been used.

       $uri->host( [$new_host] )
           This method sets and returns the unescaped hostname.

           If the $new_host string ends with a colon and a num­
           ber, then this number will also set the port.

       $uri->port( [ $new_port] )
           This method sets and returns the port.  The port is
           simple integer that should be greater than 0.

           If no explicit port is specified in the URI, then the
           default port of the URI scheme is returned. If you
           don't want the default port substituted, then you can
           use the $uri->_port method instead.

       $uri->host_port( [ $new_host_port ] )
           This method sets and returns the host and port as a
           single unit.  The returned value will include a port,
           even if it matches the default port.  The host part
           and the port part is separated with a colon; ":".

       $uri->default_port
           This method returns the default port of the URI scheme
           that $uri belongs to.  For http this will be the num­
           ber 80, for ftp this will be the number 21, etc.  The
           default port for a scheme can not be changed.


SCHEME SPECIFIC SUPPORT

       The following URI schemes are specifically supported.  For
       `URI' objects not belonging to one of these you can only
       use the common and generic methods.

       data:
           The data URI scheme is specified in RFC 2397.  It
           allows inclusion of small data items as "immediate"
           data, as if it had been included externally.

           `URI' objects belonging to the data scheme support the
           common methods and two new methods to access their
           scheme specific components; $uri->media_type and
           $uri->data.  See the URI::data manpage for details.

       file:
           An old specification of the file URI scheme is found
           in RFC 1738.  A new RFC 2396 based specification in
           not available yet, but file URI references are in com­
           mon use.

           `URI' objects belonging to the file scheme support the
           common and generic methods.  In addition they provide
           two methods to map file URI back to local file names;

           for details.

       ftp:
           An old specification of the ftp URI scheme is found in
           RFC 1738.  A new RFC 2396 based specification in not
           available yet, but ftp URI references are in common
           use.

           `URI' objects belonging to the ftp scheme support the
           common, generic and server methods.  In addition they
           provide two methods to access the userinfo sub-compo­
           nents: $uri->user and $uri->password.

       gopher:
           The gopher URI scheme is specified in <draft-murali-
           url-gopher-1996-12-04> and will hopefully be available
           as a RFC 2396 based specification.

           `URI' objects belonging to the gopher scheme support
           the common, generic and server methods. In addition
           they support some methods to access gopher specific
           path components: $uri->gopher_type, $uri->selector,
           $uri->search, $uri->string.

       http:
           The http URI scheme is specified in <draft-ietf-http-
           v11-spec-rev-06> (which will become an RFC soon).  The
           scheme is used to reference resources hosted by HTTP
           servers.

           `URI' objects belonging to the http scheme support the
           common, generic and server methods.

       https:
           The https URI scheme is a Netscape invention which is
           commonly implemented.  The scheme is used to reference
           HTTP servers through SSL connections.  It's syntax is
           the same as http, but the default port is different.

       ldap:
           The ldap URI scheme is specified in RFC 2255.  LDAP is
           the Lightweight Directory Access Protocol.  A ldap URI
           describes an LDAP search operation to perform to
           retrieve information from an LDAP directory.

           `URI' objects belonging to the ldap scheme support the
           common, generic and server methods as well as specific
           ldap methods; $uri->dn, $uri->attributes, $uri->scope,
           $uri->filter, $uri->extensions.  See the URI::ldap
           manpage for details.

       mailto:
           The mailto URI scheme is specified in RFC 2368.  The

           mailing address of an individual or service.  It has
           (in RFC 2368) been extended to allow setting of other
           mail header fields and the message body.

           `URI' objects belonging to the mailto scheme support
           the common methods and the generic query methods.  In
           addition they support the following mailto specific
           methods: $uri->to, $uri->headers.

       news:
           The news, nntp and snews URI schemes are specified in
           <draft-gilman-news-url-01> and will hopefully be
           available as a RFC 2396 based specification soon.

           `URI' objects belonging to the news scheme support the
           common, generic and server methods.  In addition they
           provide some methods to access the path: $uri->group
           and $uri->message.

       nntp:
           See news scheme.

       pop:
           The pop URI scheme is specified in RFC 2384. The
           scheme is used to reference a POP3 mailbox.

           `URI' objects belonging to the pop scheme support the
           common, generic and server methods.  In addition they
           provide two methods to access the userinfo components:
           $uri->user and $uri->auth

       rlogin:
           An old speficication of the rlogin URI scheme is found
           in RFC 1738. `URI' objects belonging to the rlogin
           scheme support the common, generic and server methods.

       rsync:
           Information about rsync is available from
           http://rsync.samba.org.  `URI' objects belonging to
           the rsync scheme support the common, generic and
           server methods.  In addition they provide methods to
           access the userinfo sub-components: $uri->user and
           $uri->password.

       snews:
           See news scheme.  It's syntax is the same as news, but
           the default port is different.

       telnet:
           An old speficication of the telnet URI scheme is found
           in RFC 1738. `URI' objects belonging to the telnet
           scheme support the common, generic and server methods.

       The following configuration variables influence how the
       class and it's methods behave:

       $URI::ABS_ALLOW_RELATIVE_SCHEME
           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.  RFC 2396 says that this should be
           avoided, but you can enable this old behaviour by set­
           ting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a
           TRUE value.  The difference is demonstrated by the
           following examples:

             URI->new("http:foo")->abs("http://host/a/b")
                 ==>  "http:foo"

             local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1;
             URI->new("http:foo")->abs("http://host/a/b")
                 ==>  "http:/host/a/foo"

       $URI::ABS_REMOTE_LEADING_DOTS
           You can also have the abs() method ignore excess ".."
           segments in the relative URI by setting
           $URI::ABS_REMOTE_LEADING_DOTS to a TRUE value.  The
           difference is demonstrated by the following examples:

             URI->new("../../../foo")->abs("http://host/a/b")
                 ==> "http://host/../../foo"

             local $URI::URL::ABS_REMOTE_LEADING_DOTS = 1;
             URI->new("../../../foo")->abs("http://host/a/b")
                 ==> "http://host/foo"


BUGS

       Using regexp variables like $1 directly as argument to the
       URI methods do not work too well with current perl imple­
       mentations.  I would argue that this is actually a bug in
       perl.  The workaround is to quote them. E.g.:

          /(...)/ || die;
          $u->query("$1");


SEE ALSO

       the URI::file manpage, the URI::WithBase manpage, the
       URI::Escape manpage, the URI::Heuristic manpage

       RFC 2396: "Uniform Resource Identifiers (URI): Generic
       Syntax", Berners-Lee, Fielding, Masinter, August 1998.


COPYRIGHT

       Copyright 1995-2001 Gisle Aas.


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


AUTHORS / ACKNOWLEDGMENTS

       This module is based on the `URI::URL' module, which in
       turn was (distantly) based on the `wwwurl.pl' code in the
       libwww-perl for perl4 developed by Roy Fielding, as part
       of the Arcadia project at the University of California,
       Irvine, with contributions from Brooks Cutter.

       `URI::URL' was developed by Gisle Aas, Tim Bunce, Roy
       Fielding and Martijn Koster with input from other people
       on the libwww-perl mailing list.

       `URI' and related subclasses was developed by Gisle Aas.


Man(1) output converted with man2html