lib/URI.pm

   1 package URI;  # $Date: 2003/08/02 23:39:31 $
   2
   3 use strict;
   4 use vars qw($VERSION);
   5 $VERSION = "1.09";
   6
   7 use vars qw($ABS_REMOTE_LEADING_DOTS $ABS_ALLOW_RELATIVE_SCHEME);
   8
   9 my %implements;  # mapping from scheme to implementor class
  10
  11 # Some "official" character classes
  12
  13 use vars qw($reserved $mark $unreserved $uric $scheme_re);
  14 $reserved   = q(;/?:@&=+$,);
  15 $mark       = q(-_.!~*'());                                    #'; emacs
  16 $unreserved = "A-Za-z0-9\Q$mark\E";
  17 $uric       = quotemeta($reserved) . $unreserved . "%";
  18
  19 $scheme_re  = '[a-zA-Z][a-zA-Z0-9.+\-]*';
  20
  21 use Carp ();
  22 use URI::Escape ();
  23
  24 use overload ('""'     => sub { ${$_[0]} },
  25               '=='     => sub { overload::StrVal($_[0]) eq
  26                                 overload::StrVal($_[1])
  27                               },
  28               fallback => 1,
  29              );
  30
  31 sub new
  32 {
  33     my($class, $uri, $scheme) = @_;
  34
  35     $uri = defined ($uri) ? "$uri" : "";   # stringify
  36     # Get rid of potential wrapping
  37     $uri =~ s/^<(?:URL:)?(.*)>$/$1/;  #
  38     $uri =~ s/^"(.*)"$/$1/;
  39     $uri =~ s/^\s+//;
  40     $uri =~ s/\s+$//;
  41
  42     my $impclass;
  43     if ($uri =~ m/^($scheme_re):/so) {
  44         $scheme = $1;
  45     } else {
  46         if (($impclass = ref($scheme))) {
  47             $scheme = $scheme->scheme;
  48         } elsif ($scheme && $scheme =~ m/^($scheme_re)(?::|$)/o) {
  49             $scheme = $1;
  50         }
  51     }
  52     $impclass ||= implementor($scheme) ||
  53         do {
  54             require URI::_foreign;
  55             $impclass = 'URI::_foreign';
  56         };
  57
  58     return $impclass->_init($uri, $scheme);
  59 }
  60
  61
  62 sub new_abs
  63 {
  64     my($class, $uri, $base) = @_;
  65     $uri = $class->new($uri, $base);
  66     $uri->abs($base);
  67 }
  68
  69
  70 sub _init
  71 {
  72     my $class = shift;
  73     my($str, $scheme) = @_;
  74     $str =~ s/([^$uric\#])/$URI::Escape::escapes{$1}/go;
  75     $str = "$scheme:$str" unless $str =~ /^$scheme_re:/o ||
  76                                  $class->_no_scheme_ok;
  77     my $self = bless \$str, $class;
  78     $self;
  79 }
  80
  81
  82 sub implementor
  83 {
  84     my($scheme, $impclass) = @_;
  85     unless ($scheme) {
  86         require URI::_generic;
  87         return "URI::_generic";
  88     }
  89
  90     $scheme = lc($scheme);
  91
  92     if ($impclass) {
  93         # Set the implementor class for a given scheme
  94         my $old = $implements{$scheme};
  95         $impclass->_init_implementor($scheme);
  96         $implements{$scheme} = $impclass;
  97         return $old;
  98     }
  99
 100     my $ic = $implements{$scheme};
 101     return $ic if $ic;
 102
 103     # scheme not yet known, look for internal or
 104     # preloaded (with 'use') implementation
 105     $ic = "URI::$scheme";  # default location
 106
 107     # turn scheme into a valid perl identifier by a simple tranformation...
 108     $ic =~ s/\+/_P/g;
 109     $ic =~ s/\./_O/g;
 110     $ic =~ s/\-/_/g;
 111
 112     no strict 'refs';
 113     # check we actually have one for the scheme:
 114     unless (@{"${ic}::ISA"}) {
 115         # Try to load it
 116         eval "require $ic";
 117         die $@ if $@ && $@ !~ /Can\'t locate.*in \@INC/;
 118         return unless @{"${ic}::ISA"};
 119     }
 120
 121     $ic->_init_implementor($scheme);
 122     $implements{$scheme} = $ic;
 123     $ic;
 124 }
 125
 126
 127 sub _init_implementor
 128 {
 129     my($class, $scheme) = @_;
 130     # Remember that one implementor class may actually
 131     # serve to implement several URI schemes.
 132 }
 133
 134
 135 sub clone
 136 {
 137     my $self = shift;
 138     my $other = $$self;
 139     bless \$other, ref $self;
 140 }
 141
 142
 143 sub _no_scheme_ok { 0 }
 144
 145 sub _scheme
 146 {
 147     my $self = shift;
 148
 149     unless (@_) {
 150         return unless $$self =~ /^($scheme_re):/o;
 151         return $1;
 152     }
 153
 154     my $old;
 155     my $new = shift;
 156     if (defined($new) && length($new)) {
 157         Carp::croak("Bad scheme '$new'") unless $new =~ /^$scheme_re$/o;
 158         $old = $1 if $$self =~ s/^($scheme_re)://o;
 159         my $newself = URI->new("$new:$$self");
 160         $$self = $$newself;
 161         bless $self, ref($newself);
 162     } else {
 163         if ($self->_no_scheme_ok) {
 164             $old = $1 if $$self =~ s/^($scheme_re)://o;
 165             Carp::carp("Oops, opaque part now look like scheme")
 166                 if $^W && $$self =~ m/^$scheme_re:/o
 167         } else {
 168             $old = $1 if $$self =~ m/^($scheme_re):/o;
 169         }
 170     }
 171
 172     return $old;
 173 }
 174
 175 sub scheme
 176 {
 177     my $scheme = shift->_scheme(@_);
 178     return unless defined $scheme;
 179     lc($scheme);
 180 }
 181
 182
 183 sub opaque
 184 {
 185     my $self = shift;
 186
 187     unless (@_) {
 188         $$self =~ /^(?:$scheme_re:)?([^\#]*)/o or die;
 189         return $1;
 190     }
 191
 192     $$self =~ /^($scheme_re:)?    # optional scheme
 193                 ([^\#]*)          # opaque
 194                 (\#.*)?           # optional fragment
 195               $/sx or die;
 196
 197     my $old_scheme = $1;
 198     my $old_opaque = $2;
 199     my $old_frag   = $3;
 200
 201     my $new_opaque = shift;
 202     $new_opaque = "" unless defined $new_opaque;
 203     $new_opaque =~ s/([^$uric])/$URI::Escape::escapes{$1}/go;
 204
 205     $$self = defined($old_scheme) ? $old_scheme : "";
 206     $$self .= $new_opaque;
 207     $$self .= $old_frag if defined $old_frag;
 208
 209     $old_opaque;
 210 }
 211
 212 *path = \&opaque;  # alias
 213
 214
 215 sub fragment
 216 {
 217     my $self = shift;
 218     unless (@_) {
 219         return unless $$self =~ /\#(.*)/s;
 220         return $1;
 221     }
 222
 223     my $old;
 224     $old = $1 if $$self =~ s/\#(.*)//s;
 225
 226     my $new_frag = shift;
 227     if (defined $new_frag) {
 228         $new_frag =~ s/([^$uric])/$URI::Escape::escapes{$1}/go;
 229         $$self .= "#$new_frag";
 230     }
 231     $old;
 232 }
 233
 234
 235 sub as_string
 236 {
 237     my $self = shift;
 238     $$self;
 239 }
 240
 241
 242 sub canonical
 243 {
 244     my $self = shift;
 245
 246     # Make sure scheme is lowercased
 247     my $scheme = $self->_scheme || "";
 248     my $uc_scheme = $scheme =~ /[A-Z]/;
 249     my $lc_esc    = $$self =~ /%(?:[a-f][a-fA-F0-9]|[A-F0-9][a-f])/;
 250     if ($uc_scheme || $lc_esc) {
 251         my $other = $self->clone;
 252         $other->_scheme(lc $scheme) if $uc_scheme;
 253         $$other =~ s/(%(?:[a-f][a-fA-F0-9]|[A-F0-9][a-f]))/uc($1)/ge
 254             if $lc_esc;
 255         return $other;
 256     }
 257     $self;
 258 }
 259
 260 # Compare two URIs, subclasses will provide a more correct implementation
 261 sub eq {
 262     my($self, $other) = @_;
 263     $self  = URI->new($self, $other) unless ref $self;
 264     $other = URI->new($other, $self) unless ref $other;
 265     ref($self) eq ref($other) &&                # same class
 266         $self->canonical->as_string eq $other->canonical->as_string;
 267 }
 268
 269 # generic-URI transformation methods
 270 sub abs { $_[0]; }
 271 sub rel { $_[0]; }
 272
 273 1;
 274
 275 __END__
 276
 277 =head1 NAME
 278
 279 URI - Uniform Resource Identifiers (absolute and relative)
 280
 281 =head1 SYNOPSIS
 282
 283  $u1 = URI->new("http://www.perl.com");
 284  $u2 = URI->new("foo", "http");
 285  $u3 = $u2->abs($u1);
 286  $u4 = $u3->clone;
 287  $u5 = URI->new("HTTP://WWW.perl.com:80")->canonical;
 288
 289  $str = $u->as_string;
 290  $str = "$u";
 291
 292  $scheme = $u->scheme;
 293  $opaque = $u->opaque;
 294  $path   = $u->path;
 295  $frag   = $u->fragment;
 296
 297  $u->scheme("ftp");
 298  $u->host("ftp.perl.com");
 299  $u->path("cpan/");
 300
 301 =head1 DESCRIPTION
 302
 303 This module implements the C<URI> class.  Objects of this class
 304 represent "Uniform Resource Identifier references" as specified in RFC
 305 2396.
 306
 307 A Uniform Resource Identifier is a compact string of characters for
 308 identifying an abstract or physical resource.  A Uniform Resource
 309 Identifier can be further classified either a Uniform Resource Locator
 310 (URL) or a Uniform Resource Name (URN).  The distinction between URL
 311 and URN does not matter to the C<URI> class interface. A
 312 "URI-reference" is a URI that may have additional information attached
 313 in the form of a fragment identifier.
 314
 315 An absolute URI reference consists of three parts.  A I<scheme>, a
 316 I<scheme specific part> and a I<fragment> identifier.  A subset of URI
 317 references share a common syntax for hierarchical namespaces.  For
 318 these the scheme specific part is further broken down into
 319 I<authority>, I<path> and I<query> components.  These URI can also
 320 take the form of relative URI references, where the scheme (and
 321 usually also the authority) component is missing, but implied by the
 322 context of the URI reference.  The three forms of URI reference
 323 syntax are summarized as follows:
 324
 325   <scheme>:<scheme-specific-part>#<fragment>
 326   <scheme>://<authority><path>?<query>#<fragment>
 327   <path>?<query>#<fragment>
 328
 329 The components that a URI reference can be divided into depend on the
 330 I<scheme>.  The C<URI> class provides methods to get and set the
 331 individual components.  The methods available for a specific
 332 C<URI> object depend on the scheme.
 333
 334 =head1 CONSTRUCTORS
 335
 336 The following methods construct new C<URI> objects:
 337
 338 =over 4
 339
 340 =item $uri = URI->new( $str, [$scheme] )
 341
 342 This class method constructs a new URI object.  The string
 343 representation of a URI is given as argument together with an optional
 344 scheme specification.  Common URI wrappers like "" and <>, as well as
 345 leading and trailing white space, are automatically removed from
 346 the $str argument before it is processed further.
 347
 348 The constructor determines the scheme, maps this to an appropriate
 349 URI subclass, constructs a new object of that class and returns it.
 350
 351 The $scheme argument is only used when $str is a
 352 relative URI.  It can either be a simple string that
 353 denotes the scheme, a string containing an absolute URI reference or
 354 an absolute C<URI> object.  If no $scheme is specified for a relative
 355 URI $str, then $str is simply treated as a generic URI (no scheme
 356 specific methods available).
 357
 358 The set of characters available for building URI references is
 359 restricted (see L<URI::Escape>).  Characters outside this set are
 360 automatically escaped by the URI constructor.
 361
 362 =item $uri = URI->new_abs( $str, $base_uri )
 363
 364 This constructs a new absolute URI object.  The $str argument can
 365 denote a relative or absolute URI.  If relative, then it will be
 366 absolutized using $base_uri as base. The $base_uri must be an absolute
 367 URI.
 368
 369 =item $uri = URI::file->new( $filename, [$os] )
 370
 371 This constructs a new I<file> URI from a file name.  See L<URI::file>.
 372
 373 =item $uri = URI::file->new_abs( $filename, [$os] )
 374
 375 This constructs a new absolute I<file> URI from a file name.  See
 376 L<URI::file>.
 377
 378 =item $uri = URI::file->cwd
 379
 380 This returns the current working directory as a I<file> URI.  See
 381 L<URI::file>.
 382
 383 =item $uri->clone
 384
 385 This method returns a copy of the $uri.
 386
 387 =back
 388
 389 =head1 COMMON METHODS
 390
 391 The methods described in this section are available for all C<URI>
 392 objects.
 393
 394 Methods that give access to components of a URI will always return the
 395 old value of the component.  The value returned will be C<undef> if the
 396 component was not present.  There is generally a difference between a
 397 component that is empty (represented as C<"">) and a component that is
 398 missing (represented as C<undef>).  If an accessor method is given an
 399 argument it will update the corresponding component in addition to
 400 returning the old value of the component.  Passing an undefined
 401 argument will remove the component (if possible).  The description of
 402 the various accessor methods will tell if the component is passed as
 403 an escaped or an unescaped string.  Components that can be futher
 404 divided into sub-parts are usually passed escaped, as unescaping might
 405 change its semantics.
 406
 407 The common methods available for all URI are:
 408
 409 =over 4
 410
 411 =item $uri->scheme( [$new_scheme] )
 412
 413 This method sets and returns the scheme part of the $uri.  If the $uri is
 414 relative, then $uri->scheme returns C<undef>.  If called with an
 415 argument, it will update the scheme of $uri, possibly changing the
 416 class of $uri, and return the old scheme value.  The method croaks
 417 if the new scheme name is illegal; scheme names must begin with a
 418 letter and must consist of only US-ASCII letters, numbers, and a few
 419 special marks: ".", "+", "-".  This restriction effectively means
 420 that scheme have to be passed unescaped.  Passing an undefined
 421 argument to the scheme method will make the URI relative (if possible).
 422
 423 Letter case does not matter for scheme names.  The string
 424 returned by $uri->scheme is always lowercase.  If you want the scheme
 425 just as it was written in the URI in its original case,
 426 you can use the $uri->_scheme method instead.
 427
 428 =item $uri->opaque( [$new_opaque] )
 429
 430 This method sets and returns the scheme specific part of the $uri
 431 (everything between the scheme and the fragment)
 432 as an escaped string.
 433
 434 =item $uri->path( [$new_path] )
 435
 436 This method sets and returns the same value as $uri->opaque unless the URI
 437 supports the generic syntax for hierarchical namespaces.
 438 In that case the generic method is overridden to set and return
 439 the part of the URI between the I<host name> and the I<fragment>.
 440
 441 =item $uri->fragment( [$new_frag] )
 442
 443 This method returns the fragment identifier of a URI reference
 444 as an escaped string.
 445
 446 =item $uri->as_string
 447
 448 This method returns a URI object to a plain string.  URI objects are
 449 also converted to plain strings automatically by overloading.  This
 450 means that $uri objects can be used as plain strings in most Perl
 451 constructs.
 452
 453 =item $uri->canonical
 454
 455 This method will return a normalized version of the URI.  The rules
 456 for normalization are scheme dependent.  It usually involves
 457 lowercasing of the scheme and the Internet host name components,
 458 removing the explicit port specification if it matches the default port,
 459 uppercasing all escape sequences, and unescaping octets that can be
 460 better represented as plain characters.
 461
 462 For efficiency reasons, if the $uri already was in normalized form,
 463 then a reference to it is returned instead of a copy.
 464
 465 =item $uri->eq( $other_uri )
 466
 467 =item URI::eq( $first_uri, $other_uri )
 468
 469 This method tests whether two URI references are equal.  URI references
 470 that normalize to the same string are considered equal.  The method
 471 can also be used as a plain function which can also test two string
 472 arguments.
 473
 474 If you need to test whether two C<URI> object references denote the
 475 same object, use the '==' operator.
 476
 477 =item $uri->abs( $base_uri )
 478
 479 This method returns an absolute URI reference.  If $uri already is
 480 absolute, then a reference to it is simply returned.  If the $uri
 481 is relative, then a new absolute URI is constructed by combining the
 482 $uri and the $base_uri, and returned.
 483
 484 =item $uri->rel( $base_uri )
 485
 486 This method returns a relative URI reference if it is possible to
 487 make one that denotes the same resource relative to $base_uri.
 488 If not, then $uri is simply returned.
 489
 490 =back
 491
 492 =head1 GENERIC METHODS
 493
 494 The following methods are available to schemes that use the
 495 common/generic syntax for hierarchical namespaces.  The description of
 496 schemes below will tell which one these are.  Unknown schemes are
 497 assumed to support the generic syntax, and therefore the following
 498 methods:
 499
 500 =over 4
 501
 502 =item $uri->authority( [$new_authority] )
 503
 504 This method sets and returns the escaped authority component
 505 of the $uri.
 506
 507 =item $uri->path( [$new_path] )
 508
 509 This method sets and returns the escaped path component of
 510 the $uri (the part between the host name and the query or fragment).
 511 The path will never be undefined, but it can be the empty string.
 512
 513 =item $uri->path_query( [$new_path_query] )
 514
 515 This method sets and returns the escaped path and query
 516 components as a single entity.  The path and the query are
 517 separated by a "?" character, but the query can itself contain "?".
 518
 519 =item $uri->path_segments( [$segment,...] )
 520
 521 This method sets and returns the path.  In scalar context it returns
 522 the same value as $uri->path.  In list context it will return the
 523 unescaped path segments that make up the path.  Path segments that
 524 have parameters are returned as an anonymous array.  The first element
 525 is the unescaped path segment proper.  Subsequent elements are escaped
 526 parameter strings.  Such an anonymous array uses overloading so it can
 527 be treated as a string too, but this string does not include the
 528 parameters.
 529
 530 =item $uri->query( [$new_query] )
 531
 532 This method sets and returns the escaped query component of
 533 the $uri.
 534
 535 =item $uri->query_form( [$key => $value,...] )
 536
 537 This method sets and returns query components that use the
 538 I<application/x-www-form-urlencoded> format.  Key/value pairs are
 539 separated by "&" and the key is separated from the value with a "="
 540 character.
 541
 542 =item $uri->query_keywords( [$keywords,...] )
 543
 544 This method sets and returns query components that use the
 545 keywords separated by "+" format.
 546
 547 =back
 548
 549 =head1 SERVER METHODS
 550
 551 Schemes where the I<authority> component denotes a Internet host will
 552 have the following methods available in addition to the generic
 553 methods.
 554
 555 =over 4
 556
 557 =item $uri->userinfo( [$new_userinfo] )
 558
 559 This method sets and returns the escaped userinfo part of the
 560 authority componenent.
 561
 562 For some schemes this will be a user name and a password separated by
 563 a colon.  This practice is not recommended. Embedding passwords in
 564 clear text (such as URI) has proven to be a security risk in almost
 565 every case where it has been used.
 566
 567 =item $uri->host( [$new_host] )
 568
 569 This method sets and returns the unescaped hostname.
 570
 571 If the $new_host string ends with a colon and a number, then this
 572 number will also set the port.
 573
 574 =item $uri->port( [ $new_port] )
 575
 576 This method sets and returns the port.  The port is simple integer
 577 that should be greater than 0.
 578
 579 If no explicit port is specified in the URI, then the default port of
 580 the URI scheme is returned. If you don't want the default port
 581 substituted, then you can use the $uri->_port method instead.
 582
 583 =item $uri->host_port( [ $new_host_port ] )
 584
 585 This method sets and returns the host and port as a single
 586 unit.  The returned value will include a port, even if it matches the
 587 default port.  The host part and the port part is separated with a
 588 colon; ":".
 589
 590 =item $uri->default_port
 591
 592 This method returns the default port of the URI scheme that $uri
 593 belongs to.  For I<http> this will be the number 80, for I<ftp> this
 594 will be the number 21, etc.  The default port for a scheme can not be
 595 changed.
 596
 597 =back
 598
 599 =head1 SCHEME SPECIFIC SUPPORT
 600
 601 The following URI schemes are specifically supported.  For C<URI>
 602 objects not belonging to one of these you can only use the common and
 603 generic methods.
 604
 605 =over 4
 606
 607 =item B<data>:
 608
 609 The I<data> URI scheme is specified in RFC 2397.  It allows inclusion
 610 of small data items as "immediate" data, as if it had been included
 611 externally.
 612
 613 C<URI> objects belonging to the data scheme support the common methods
 614 and two new methods to access their scheme specific components;
 615 $uri->media_type and $uri->data.  See L<URI::data> for details.
 616
 617 =item B<file>:
 618
 619 An old specification of the I<file> URI scheme is found in RFC 1738.
 620 A new RFC 2396 based specification in not available yet, but file URI
 621 references are in common use.
 622
 623 C<URI> objects belonging to the file scheme support the common and
 624 generic methods.  In addition they provide two methods to map file URI
 625 back to local file names; $uri->file and $uri->dir.  See L<URI::file>
 626 for details.
 627
 628 =item B<ftp>:
 629
 630 An old specification of the I<ftp> URI scheme is found in RFC 1738.  A
 631 new RFC 2396 based specification in not available yet, but ftp URI
 632 references are in common use.
 633
 634 C<URI> objects belonging to the ftp scheme support the common,
 635 generic and server methods.  In addition they provide two methods to
 636 access the userinfo sub-components: $uri->user and $uri->password.
 637
 638 =item B<gopher>:
 639
 640 The I<gopher> URI scheme is specified in
 641 <draft-murali-url-gopher-1996-12-04> and will hopefully be available
 642 as a RFC 2396 based specification.
 643
 644 C<URI> objects belonging to the gopher scheme support the common,
 645 generic and server methods. In addition they support some methods to
 646 access gopher specific path components: $uri->gopher_type,
 647 $uri->selector, $uri->search, $uri->string.
 648
 649 =item B<http>:
 650
 651 The I<http> URI scheme is specified in
 652 <draft-ietf-http-v11-spec-rev-06> (which will become an RFC soon).
 653 The scheme is used to reference resources hosted by HTTP servers.
 654
 655 C<URI> objects belonging to the http scheme support the common,
 656 generic and server methods.
 657
 658 =item B<https>:
 659
 660 The I<https> URI scheme is a Netscape invention which is commonly
 661 implemented.  The scheme is used to reference HTTP servers through SSL
 662 connections.  It's syntax is the same as http, but the default
 663 port is different.
 664
 665 =item B<ldap>:
 666
 667 The I<ldap> URI scheme is specified in RFC 2255.  LDAP is the
 668 Lightweight Directory Access Protocol.  A ldap URI describes an LDAP
 669 search operation to perform to retrieve information from an LDAP
 670 directory.
 671
 672 C<URI> objects belonging to the ldap scheme support the common,
 673 generic and server methods as well as specific ldap methods; $uri->dn,
 674 $uri->attributes, $uri->scope, $uri->filter, $uri->extensions.  See
 675 L<URI::ldap> for details.
 676
 677 =item B<mailto>:
 678
 679 The I<mailto> URI scheme is specified in RFC 2368.  The scheme was
 680 originally used to designate the Internet mailing address of an
 681 individual or service.  It has (in RFC 2368) been extended to allow
 682 setting of other mail header fields and the message body.
 683
 684 C<URI> objects belonging to the mailto scheme support the common
 685 methods and the generic query methods.  In addition they support the
 686 following mailto specific methods: $uri->to, $uri->headers.
 687
 688 =item B<news>:
 689
 690 The I<news>, I<nntp> and I<snews> URI schemes are specified in
 691 <draft-gilman-news-url-01> and will hopefully be available as a RFC
 692 2396 based specification soon.
 693
 694 C<URI> objects belonging to the news scheme support the common,
 695 generic and server methods.  In addition they provide some methods to
 696 access the path: $uri->group and $uri->message.
 697
 698 =item B<nntp>:
 699
 700 See I<news> scheme.
 701
 702 =item B<pop>:
 703
 704 The I<pop> URI scheme is specified in RFC 2384. The scheme is used to
 705 reference a POP3 mailbox.
 706
 707 C<URI> objects belonging to the pop scheme support the common, generic
 708 and server methods.  In addition they provide two methods to access the
 709 userinfo components: $uri->user and $uri->auth
 710
 711 =item B<rlogin>:
 712
 713 An old speficication of the I<rlogin> URI scheme is found in RFC
 714 1738. C<URI> objects belonging to the rlogin scheme support the
 715 common, generic and server methods.
 716
 717 =item B<rsync>:
 718
 719 Information about rsync is available from http://rsync.samba.org.
 720 C<URI> objects belonging to the rsync scheme support the common,
 721 generic and server methods.  In addition they provide methods to
 722 access the userinfo sub-components: $uri->user and $uri->password.
 723
 724 =item B<snews>:
 725
 726 See I<news> scheme.  It's syntax is the same as news, but the default
 727 port is different.
 728
 729 =item B<telnet>:
 730
 731 An old speficication of the I<telnet> URI scheme is found in RFC
 732 1738. C<URI> objects belonging to the telnet scheme support the
 733 common, generic and server methods.
 734
 735 =back
 736
 737
 738 =head1 CONFIGURATION VARIABLES
 739
 740 The following configuration variables influence how the class and it's
 741 methods behave:
 742
 743 =over 4
 744
 745 =item $URI::ABS_ALLOW_RELATIVE_SCHEME
 746
 747 Some older parsers used to allow the scheme name to be present in the
 748 relative URL if it was the same as the base URL scheme.  RFC 2396 says
 749 that this should be avoided, but you can enable this old behaviour by
 750 setting the $URI::ABS_ALLOW_RELATIVE_SCHEME variable to a TRUE value.
 751 The difference is demonstrated by the following examples:
 752
 753   URI->new("http:foo")->abs("http://host/a/b")
 754       ==>  "http:foo"
 755
 756   local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1;
 757   URI->new("http:foo")->abs("http://host/a/b")
 758       ==>  "http:/host/a/foo"
 759
 760
 761 =item $URI::ABS_REMOTE_LEADING_DOTS
 762
 763 You can also have the abs() method ignore excess ".."
 764 segments in the relative URI by setting $URI::ABS_REMOTE_LEADING_DOTS
 765 to a TRUE value.  The difference is demonstrated by the following
 766 examples:
 767
 768   URI->new("../../../foo")->abs("http://host/a/b")
 769       ==> "http://host/../../foo"
 770
 771   local $URI::URL::ABS_REMOTE_LEADING_DOTS = 1;
 772   URI->new("../../../foo")->abs("http://host/a/b")
 773       ==> "http://host/foo"
 774
 775 =back
 776
 777
 778
 779 =head1 SEE ALSO
 780
 781 L<URI::file>, L<URI::WithBase>, L<URI::Escape>, L<URI::Heuristic>
 782
 783 RFC 2396: "Uniform Resource Identifiers (URI): Generic Syntax",
 784 Berners-Lee, Fielding, Masinter, August 1998.
 785
 786 =head1 COPYRIGHT
 787
 788 Copyright 1995-2000 Gisle Aas.
 789
 790 Copyright 1995 Martijn Koster.
 791
 792 This program is free software; you can redistribute it and/or modify
 793 it under the same terms as Perl itself.
 794
 795 =head1 AUTHORS / ACKNOWLEDGMENTS
 796
 797 This module is based on the C<URI::URL> module, which in turn was
 798 (distantly) based on the C<wwwurl.pl> code in the libwww-perl for
 799 perl4 developed by Roy Fielding, as part of the Arcadia project at the
 800 University of California, Irvine, with contributions from Brooks
 801 Cutter.
 802
 803 C<URI::URL> was developed by Gisle Aas, Tim Bunce, Roy Fielding and
 804 Martijn Koster with input from other people on the libwww-perl mailing
 805 list.
 806
 807 C<URI> and related subclasses was developed by Gisle Aas.
 808
 809 =cut