URI::URL man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

NAME
       URI::URL - Uniform Resource Locators (absolute and
       relative)

SYNOPSIS
	use URI::URL;

	# Constructors
	$url1 = new URI::URL 'http://www.perl.com/%7Euser/gisle.gif';
	$url2 = new URI::URL 'gisle.gif', 'http://www.com/%7Euser';
	$url3 = url 'http://www.sn.no/'; # handy constructor
	$url4 = $url2->abs;	  # get absolute url using base
	$url5 = $url2->abs('http:/other/path');
	$url6 = newlocal URI::URL 'test';

	# Stringify URL
	$str1 = $url->as_string;  # complete escaped URL string
	$str2 = $url->full_path;  # escaped path+params+query
	$str3 = "$url";		  # use operator overloading

	# Retrieving Generic-RL components:
	$scheme	  = $url->scheme;
	$netloc	  = $url->netloc; # see user,password,host,port below
	$path	  = $url->path;
	$params	  = $url->params;
	$query	  = $url->query;
	$frag	  = $url->frag;

	# Accessing elements in their escaped form
	$path	  = $url->epath;
	$params	  = $url->eparams;
	$query	  = $url->equery;

	# Retrieving Network location (netloc) components:
	$user	  = $url->user;
	$password = $url->password;
	$host	  = $url->host;
	$port	  = $url->port;	  # returns default if not defined

	# Retrieve escaped path components as an array
	@path	  = $url->path_components;

	# HTTP query-string access methods
	@keywords = $url->keywords;
	@form	  = $url->query_form;

	# All methods above can set the field values, e.g:
	$url->scheme('http');
	$url->host('www.w3.org');
	$url->port($url->default_port);
	$url->base($url5);			# use string or object
	$url->keywords(qw(dog bones));

24/Aug/1997	       perl 5.005, patch 03			1

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

	# File methods
	$url = new URI::URL "file:/foo/bar";
	open(F, $url->local_path) or die;

	# Compare URLs
	if ($url->eq("http://www.sn.no")) or die;

DESCRIPTION
       This module implements the URI::URL class representing
       Uniform Resource Locators (URL). URLs provide a compact
       string representation for resources available via the
       Internet. Both absolute (RFC 1738) and relative (RFC 1808)
       URLs are supported.

       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

24/Aug/1997	       perl 5.005, patch 03			2

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

	  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.

       Notes:
	  A URL string must, by definition, consist of escaped
	  components. Complete URLs are always escaped.

	  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

24/Aug/1997	       perl 5.005, patch 03			3

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

       a new scheme class use code like:

	  package MYURL::foo;
	  @ISA = (URI::URL::implementor());   # inherit from generic scheme

       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.

       Your class can then define overriding methods (e.g.,
       new(), _parse() as required).

       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.

24/Aug/1997	       perl 5.005, patch 03			4

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

       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:

	    url("http:foo")->abs("http://host/a/b")	==>  "http:foo"
	    url("http:foo")->abs("http://host/a/b", 1)	==>  "http:/host/a/foo"

	  The rel() method will do the opposite transformation.

       $url->as_string
	  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.

       $url->clone
	  Returns a copy of the current URI::URL object.

24/Aug/1997	       perl 5.005, patch 03			5

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

       $url->crack
	  Return a 9 element array with the following content:

	     0: $url->scheme *)
	     1: $url->user
	     2: $url->password
	     3: $url->host
	     4: $url->port
	     5: $url->epath
	     6: $url->eparams
	     7: $url->equery
	     8: $url->frag

	  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.

       $url->frag (*)
	  Get/set the fragment (unescaped)

       $url->host (*)
	  Get/set the host (unescaped)

       $url->netloc (*)
	  Get/set the network location in escaped form.	 Setting

24/Aug/1997	       perl 5.005, patch 03			6

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

	  the network location will affect 'user', 'password',
	  'host' and 'port'.

       $url->params (*)
	  Get/set the URL parameters (unescaped)

       $url->password (*)
	  Get/set the password (unescaped)

       $url->path (*)
	  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:

	     url("http://www.math.uio.no/doc/mail/top.html",
		 "http://www.math.uio.no/doc/linux/")->rel

	  will return a relative URL with path set to
	  "../mail/top.html" and with the same base as the
	  original URL.

	  If the original URL already is relative or the scheme
	  or netloc does not match the base, then a copy of the
	  original URL is returned.

       $url->print_on(*FILEHANDLE);
	  Prints a verbose presentation of the contents of the
	  URL object to the specified file handle (default
	  STDOUT).  Mainly useful for debugging.

       $url->scheme (*)
	  Get/set the scheme for the URL.

       $url->query (*)
	  Get/set the query string (unescaped).	 This method will
	  croak if the string returned contains both '+' and
	  '%2B' or '=' together with '%3D' or '%26'.  You should
	  use the equery() method to be safe.

24/Aug/1997	       perl 5.005, patch 03			7

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

       $url->user (*)
	  Get/set the URL user name (unescaped)

HTTP METHODS
       For http URLs you may also access the query string using
       the keywords() and the query_form() methods.  Both will
       croak if the query is not of the correct format.	 The
       encodings look like this:

	 word1+word2+word3..	    # keywords
	 key1=val1&key2=val2...	    # query_form

       Note: These functions does not return the old value when
       they are used to set a value of the query string.

       $url->keywords (*)
	  The keywords() method returns a list of unescaped
	  strings.  The method can also be used to set the query
	  string by passing in the keywords as individual
	  arguments to the method.

       $url->query_form (*)
	  The query_form() method return a list of unescaped
	  key/value pairs.  If you assign the return value to a
	  hash you might loose some values if the key is repeated
	  (which it is allowed to do).

	  This method can also be used to set the query sting of
	  the URL like this:

	    $url->query_form(foo => 'bar', foo => 'baz', equal => '=');

	  If the value part of a key/value pair is a reference to
	  an array, then it will be converted to separate
	  key/value pairs for each value.  This means that these
	  two calls are equal:

	    $url->query_form(foo => 'bar', foo => 'baz');
	    $url->query_form(foo => ['bar', 'baz']);

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

24/Aug/1997	       perl 5.005, patch 03			8

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

	  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 the LWP::UserAgent
       manpage). The agent class can use the URL class, but

24/Aug/1997	       perl 5.005, patch 03			9

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

       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.

24/Aug/1997	       perl 5.005, patch 03		       10

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

       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.

24/Aug/1997	       perl 5.005, patch 03		       11

lib::URI::URL(3User Contributed Perl Documentatiolib::URI::URL(3)

24/Aug/1997	       perl 5.005, patch 03		       12

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net