local-lib5/man/man3/URI.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "URI 3"
 132 .TH URI 3 "2009-11-23" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 URI \- Uniform Resource Identifiers (absolute and relative)
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 5
 138 \& $u1 = URI\->new("http://www.perl.com");
 139 \& $u2 = URI\->new("foo", "http");
 140 \& $u3 = $u2\->abs($u1);
 141 \& $u4 = $u3\->clone;
 142 \& $u5 = URI\->new("HTTP://WWW.perl.com:80")\->canonical;
 143 .Ve
 144 .PP
 145 .Vb 2
 146 \& $str = $u\->as_string;
 147 \& $str = "$u";
 148 .Ve
 149 .PP
 150 .Vb 4
 151 \& $scheme = $u\->scheme;
 152 \& $opaque = $u\->opaque;
 153 \& $path   = $u\->path;
 154 \& $frag   = $u\->fragment;
 155 .Ve
 156 .PP
 157 .Vb 3
 158 \& $u\->scheme("ftp");
 159 \& $u\->host("ftp.perl.com");
 160 \& $u\->path("cpan/");
 161 .Ve
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 This module implements the \f(CW\*(C`URI\*(C'\fR class.  Objects of this class
 165 represent \*(L"Uniform Resource Identifier references\*(R" as specified in \s-1RFC\s0
 166 2396 (and updated by \s-1RFC\s0 2732).
 167 .PP
 168 A Uniform Resource Identifier is a compact string of characters that
 169 identifies an abstract or physical resource.  A Uniform Resource
 170 Identifier can be further classified as either a Uniform Resource Locator
 171 (\s-1URL\s0) or a Uniform Resource Name (\s-1URN\s0).  The distinction between \s-1URL\s0
 172 and \s-1URN\s0 does not matter to the \f(CW\*(C`URI\*(C'\fR class interface. A
 173 \&\*(L"URI\-reference\*(R" is a \s-1URI\s0 that may have additional information attached
 174 in the form of a fragment identifier.
 175 .PP
 176 An absolute \s-1URI\s0 reference consists of three parts:  a \fIscheme\fR, a
 177 \&\fIscheme-specific part\fR and a \fIfragment\fR identifier.  A subset of \s-1URI\s0
 178 references share a common syntax for hierarchical namespaces.  For
 179 these, the scheme-specific part is further broken down into
 180 \&\fIauthority\fR, \fIpath\fR and \fIquery\fR components.  These URIs can also
 181 take the form of relative \s-1URI\s0 references, where the scheme (and
 182 usually also the authority) component is missing, but implied by the
 183 context of the \s-1URI\s0 reference.  The three forms of \s-1URI\s0 reference
 184 syntax are summarized as follows:
 185 .PP
 186 .Vb 3
 187 \&  <scheme>:<scheme\-specific\-part>#<fragment>
 188 \&  <scheme>://<authority><path>?<query>#<fragment>
 189 \&  <path>?<query>#<fragment>
 190 .Ve
 191 .PP
 192 The components into which a \s-1URI\s0 reference can be divided depend on the
 193 \&\fIscheme\fR.  The \f(CW\*(C`URI\*(C'\fR class provides methods to get and set the
 194 individual components.  The methods available for a specific
 195 \&\f(CW\*(C`URI\*(C'\fR object depend on the scheme.
 196 .SH "CONSTRUCTORS"
 197 .IX Header "CONSTRUCTORS"
 198 The following methods construct new \f(CW\*(C`URI\*(C'\fR objects:
 199 .ie n .IP "$uri = \s-1URI\-\s0>new( $str )" 4
 200 .el .IP "$uri = \s-1URI\-\s0>new( \f(CW$str\fR )" 4
 201 .IX Item "$uri = URI->new( $str )"
 202 .PD 0
 203 .ie n .IP "$uri = \s-1URI\-\s0>new( $str\fR, \f(CW$scheme )" 4
 204 .el .IP "$uri = \s-1URI\-\s0>new( \f(CW$str\fR, \f(CW$scheme\fR )" 4
 205 .IX Item "$uri = URI->new( $str, $scheme )"
 206 .PD
 207 Constructs a new \s-1URI\s0 object.  The string
 208 representation of a \s-1URI\s0 is given as argument, together with an optional
 209 scheme specification.  Common \s-1URI\s0 wrappers like "" and <>, as well as
 210 leading and trailing white space, are automatically removed from
 211 the \f(CW$str\fR argument before it is processed further.
 212 .Sp
 213 The constructor determines the scheme, maps this to an appropriate
 214 \&\s-1URI\s0 subclass, constructs a new object of that class and returns it.
 215 .Sp
 216 The \f(CW$scheme\fR argument is only used when \f(CW$str\fR is a
 217 relative \s-1URI\s0.  It can be either a simple string that
 218 denotes the scheme, a string containing an absolute \s-1URI\s0 reference, or
 219 an absolute \f(CW\*(C`URI\*(C'\fR object.  If no \f(CW$scheme\fR is specified for a relative
 220 \&\s-1URI\s0 \f(CW$str\fR, then \f(CW$str\fR is simply treated as a generic \s-1URI\s0 (no scheme-specific
 221 methods available).
 222 .Sp
 223 The set of characters available for building \s-1URI\s0 references is
 224 restricted (see URI::Escape).  Characters outside this set are
 225 automatically escaped by the \s-1URI\s0 constructor.
 226 .ie n .IP "$uri = \s-1URI\-\s0>new_abs( $str\fR, \f(CW$base_uri )" 4
 227 .el .IP "$uri = \s-1URI\-\s0>new_abs( \f(CW$str\fR, \f(CW$base_uri\fR )" 4
 228 .IX Item "$uri = URI->new_abs( $str, $base_uri )"
 229 Constructs a new absolute \s-1URI\s0 object.  The \f(CW$str\fR argument can
 230 denote a relative or absolute \s-1URI\s0.  If relative, then it is
 231 absolutized using \f(CW$base_uri\fR as base. The \f(CW$base_uri\fR must be an absolute
 232 \&\s-1URI\s0.
 233 .ie n .IP "$uri = URI::file\->new( $filename )" 4
 234 .el .IP "$uri = URI::file\->new( \f(CW$filename\fR )" 4
 235 .IX Item "$uri = URI::file->new( $filename )"
 236 .PD 0
 237 .ie n .IP "$uri = URI::file\->new( $filename\fR, \f(CW$os )" 4
 238 .el .IP "$uri = URI::file\->new( \f(CW$filename\fR, \f(CW$os\fR )" 4
 239 .IX Item "$uri = URI::file->new( $filename, $os )"
 240 .PD
 241 Constructs a new \fIfile\fR \s-1URI\s0 from a file name.  See URI::file.
 242 .ie n .IP "$uri = URI::file\->new_abs( $filename )" 4
 243 .el .IP "$uri = URI::file\->new_abs( \f(CW$filename\fR )" 4
 244 .IX Item "$uri = URI::file->new_abs( $filename )"
 245 .PD 0
 246 .ie n .IP "$uri = URI::file\->new_abs( $filename\fR, \f(CW$os )" 4
 247 .el .IP "$uri = URI::file\->new_abs( \f(CW$filename\fR, \f(CW$os\fR )" 4
 248 .IX Item "$uri = URI::file->new_abs( $filename, $os )"
 249 .PD
 250 Constructs a new absolute \fIfile\fR \s-1URI\s0 from a file name.  See
 251 URI::file.
 252 .IP "$uri = URI::file\->cwd" 4
 253 .IX Item "$uri = URI::file->cwd"
 254 Returns the current working directory as a \fIfile\fR \s-1URI\s0.  See
 255 URI::file.
 256 .IP "$uri\->clone" 4
 257 .IX Item "$uri->clone"
 258 Returns a copy of the \f(CW$uri\fR.
 259 .SH "COMMON METHODS"
 260 .IX Header "COMMON METHODS"
 261 The methods described in this section are available for all \f(CW\*(C`URI\*(C'\fR
 262 objects.
 263 .PP
 264 Methods that give access to components of a \s-1URI\s0 always return the
 265 old value of the component.  The value returned is \f(CW\*(C`undef\*(C'\fR if the
 266 component was not present.  There is generally a difference between a
 267 component that is empty (represented as \f(CW""\fR) and a component that is
 268 missing (represented as \f(CW\*(C`undef\*(C'\fR).  If an accessor method is given an
 269 argument, it updates the corresponding component in addition to
 270 returning the old value of the component.  Passing an undefined
 271 argument removes the component (if possible).  The description of
 272 each accessor method indicates whether the component is passed as
 273 an escaped or an unescaped string.  A component that can be further
 274 divided into sub-parts are usually passed escaped, as unescaping might
 275 change its semantics.
 276 .PP
 277 The common methods available for all \s-1URI\s0 are:
 278 .IP "$uri\->scheme" 4
 279 .IX Item "$uri->scheme"
 280 .PD 0
 281 .ie n .IP "$uri\->scheme( $new_scheme )" 4
 282 .el .IP "$uri\->scheme( \f(CW$new_scheme\fR )" 4
 283 .IX Item "$uri->scheme( $new_scheme )"
 284 .PD
 285 Sets and returns the scheme part of the \f(CW$uri\fR.  If the \f(CW$uri\fR is
 286 relative, then \f(CW$uri\fR\->scheme returns \f(CW\*(C`undef\*(C'\fR.  If called with an
 287 argument, it updates the scheme of \f(CW$uri\fR, possibly changing the
 288 class of \f(CW$uri\fR, and returns the old scheme value.  The method croaks
 289 if the new scheme name is illegal; a scheme name must begin with a
 290 letter and must consist of only US-ASCII letters, numbers, and a few
 291 special marks: \*(L".\*(R", \*(L"+\*(R", \*(L"\-\*(R".  This restriction effectively means
 292 that the scheme must be passed unescaped.  Passing an undefined
 293 argument to the scheme method makes the \s-1URI\s0 relative (if possible).
 294 .Sp
 295 Letter case does not matter for scheme names.  The string
 296 returned by \f(CW$uri\fR\->scheme is always lowercase.  If you want the scheme
 297 just as it was written in the \s-1URI\s0 in its original case,
 298 you can use the \f(CW$uri\fR\->_scheme method instead.
 299 .IP "$uri\->opaque" 4
 300 .IX Item "$uri->opaque"
 301 .PD 0
 302 .ie n .IP "$uri\->opaque( $new_opaque )" 4
 303 .el .IP "$uri\->opaque( \f(CW$new_opaque\fR )" 4
 304 .IX Item "$uri->opaque( $new_opaque )"
 305 .PD
 306 Sets and returns the scheme-specific part of the \f(CW$uri\fR
 307 (everything between the scheme and the fragment)
 308 as an escaped string.
 309 .IP "$uri\->path" 4
 310 .IX Item "$uri->path"
 311 .PD 0
 312 .ie n .IP "$uri\->path( $new_path )" 4
 313 .el .IP "$uri\->path( \f(CW$new_path\fR )" 4
 314 .IX Item "$uri->path( $new_path )"
 315 .PD
 316 Sets and returns the same value as \f(CW$uri\fR\->opaque unless the \s-1URI\s0
 317 supports the generic syntax for hierarchical namespaces.
 318 In that case the generic method is overridden to set and return
 319 the part of the \s-1URI\s0 between the \fIhost name\fR and the \fIfragment\fR.
 320 .IP "$uri\->fragment" 4
 321 .IX Item "$uri->fragment"
 322 .PD 0
 323 .ie n .IP "$uri\->fragment( $new_frag )" 4
 324 .el .IP "$uri\->fragment( \f(CW$new_frag\fR )" 4
 325 .IX Item "$uri->fragment( $new_frag )"
 326 .PD
 327 Returns the fragment identifier of a \s-1URI\s0 reference
 328 as an escaped string.
 329 .IP "$uri\->as_string" 4
 330 .IX Item "$uri->as_string"
 331 Returns a \s-1URI\s0 object to a plain \s-1ASCII\s0 string.  \s-1URI\s0 objects are
 332 also converted to plain strings automatically by overloading.  This
 333 means that \f(CW$uri\fR objects can be used as plain strings in most Perl
 334 constructs.
 335 .IP "$uri\->as_iri" 4
 336 .IX Item "$uri->as_iri"
 337 Returns a Unicode string representing the \s-1URI\s0.  Escaped \s-1UTF\-8\s0 sequences
 338 representing non-ASCII characters are turned into their corresponding Unicode
 339 code point.
 340 .IP "$uri\->canonical" 4
 341 .IX Item "$uri->canonical"
 342 Returns a normalized version of the \s-1URI\s0.  The rules
 343 for normalization are scheme\-dependent.  They usually involve
 344 lowercasing the scheme and Internet host name components,
 345 removing the explicit port specification if it matches the default port,
 346 uppercasing all escape sequences, and unescaping octets that can be
 347 better represented as plain characters.
 348 .Sp
 349 For efficiency reasons, if the \f(CW$uri\fR is already in normalized form,
 350 then a reference to it is returned instead of a copy.
 351 .ie n .IP "$uri\->eq( $other_uri )" 4
 352 .el .IP "$uri\->eq( \f(CW$other_uri\fR )" 4
 353 .IX Item "$uri->eq( $other_uri )"
 354 .PD 0
 355 .ie n .IP "URI::eq( $first_uri\fR, \f(CW$other_uri )" 4
 356 .el .IP "URI::eq( \f(CW$first_uri\fR, \f(CW$other_uri\fR )" 4
 357 .IX Item "URI::eq( $first_uri, $other_uri )"
 358 .PD
 359 Tests whether two \s-1URI\s0 references are equal.  \s-1URI\s0 references
 360 that normalize to the same string are considered equal.  The method
 361 can also be used as a plain function which can also test two string
 362 arguments.
 363 .Sp
 364 If you need to test whether two \f(CW\*(C`URI\*(C'\fR object references denote the
 365 same object, use the '==' operator.
 366 .ie n .IP "$uri\->abs( $base_uri )" 4
 367 .el .IP "$uri\->abs( \f(CW$base_uri\fR )" 4
 368 .IX Item "$uri->abs( $base_uri )"
 369 Returns an absolute \s-1URI\s0 reference.  If \f(CW$uri\fR is already
 370 absolute, then a reference to it is simply returned.  If the \f(CW$uri\fR
 371 is relative, then a new absolute \s-1URI\s0 is constructed by combining the
 372 \&\f(CW$uri\fR and the \f(CW$base_uri\fR, and returned.
 373 .ie n .IP "$uri\->rel( $base_uri )" 4
 374 .el .IP "$uri\->rel( \f(CW$base_uri\fR )" 4
 375 .IX Item "$uri->rel( $base_uri )"
 376 Returns a relative \s-1URI\s0 reference if it is possible to
 377 make one that denotes the same resource relative to \f(CW$base_uri\fR.
 378 If not, then \f(CW$uri\fR is simply returned.
 379 .SH "GENERIC METHODS"
 380 .IX Header "GENERIC METHODS"
 381 The following methods are available to schemes that use the
 382 common/generic syntax for hierarchical namespaces.  The descriptions of
 383 schemes below indicate which these are.  Unknown schemes are
 384 assumed to support the generic syntax, and therefore the following
 385 methods:
 386 .IP "$uri\->authority" 4
 387 .IX Item "$uri->authority"
 388 .PD 0
 389 .ie n .IP "$uri\->authority( $new_authority )" 4
 390 .el .IP "$uri\->authority( \f(CW$new_authority\fR )" 4
 391 .IX Item "$uri->authority( $new_authority )"
 392 .PD
 393 Sets and returns the escaped authority component
 394 of the \f(CW$uri\fR.
 395 .IP "$uri\->path" 4
 396 .IX Item "$uri->path"
 397 .PD 0
 398 .ie n .IP "$uri\->path( $new_path )" 4
 399 .el .IP "$uri\->path( \f(CW$new_path\fR )" 4
 400 .IX Item "$uri->path( $new_path )"
 401 .PD
 402 Sets and returns the escaped path component of
 403 the \f(CW$uri\fR (the part between the host name and the query or fragment).
 404 The path can never be undefined, but it can be the empty string.
 405 .IP "$uri\->path_query" 4
 406 .IX Item "$uri->path_query"
 407 .PD 0
 408 .ie n .IP "$uri\->path_query( $new_path_query )" 4
 409 .el .IP "$uri\->path_query( \f(CW$new_path_query\fR )" 4
 410 .IX Item "$uri->path_query( $new_path_query )"
 411 .PD
 412 Sets and returns the escaped path and query
 413 components as a single entity.  The path and the query are
 414 separated by a \*(L"?\*(R" character, but the query can itself contain \*(L"?\*(R".
 415 .IP "$uri\->path_segments" 4
 416 .IX Item "$uri->path_segments"
 417 .PD 0
 418 .ie n .IP "$uri\->path_segments( $segment, ... )" 4
 419 .el .IP "$uri\->path_segments( \f(CW$segment\fR, ... )" 4
 420 .IX Item "$uri->path_segments( $segment, ... )"
 421 .PD
 422 Sets and returns the path.  In a scalar context, it returns
 423 the same value as \f(CW$uri\fR\->path.  In a list context, it returns the
 424 unescaped path segments that make up the path.  Path segments that
 425 have parameters are returned as an anonymous array.  The first element
 426 is the unescaped path segment proper;  subsequent elements are escaped
 427 parameter strings.  Such an anonymous array uses overloading so it can
 428 be treated as a string too, but this string does not include the
 429 parameters.
 430 .Sp
 431 Note that absolute paths have the empty string as their first
 432 \&\fIpath_segment\fR, i.e. the \fIpath\fR \f(CW\*(C`/foo/bar\*(C'\fR have 3
 433 \&\fIpath_segments\fR; "\*(L", \*(R"foo\*(L" and \*(R"bar".
 434 .IP "$uri\->query" 4
 435 .IX Item "$uri->query"
 436 .PD 0
 437 .ie n .IP "$uri\->query( $new_query )" 4
 438 .el .IP "$uri\->query( \f(CW$new_query\fR )" 4
 439 .IX Item "$uri->query( $new_query )"
 440 .PD
 441 Sets and returns the escaped query component of
 442 the \f(CW$uri\fR.
 443 .IP "$uri\->query_form" 4
 444 .IX Item "$uri->query_form"
 445 .PD 0
 446 .ie n .IP "$uri\->query_form( $key1\fR => \f(CW$val1\fR, \f(CW$key2\fR => \f(CW$val2, ... )" 4
 447 .el .IP "$uri\->query_form( \f(CW$key1\fR => \f(CW$val1\fR, \f(CW$key2\fR => \f(CW$val2\fR, ... )" 4
 448 .IX Item "$uri->query_form( $key1 => $val1, $key2 => $val2, ... )"
 449 .ie n .IP "$uri\->query_form( $key1\fR => \f(CW$val1\fR, \f(CW$key2\fR => \f(CW$val2\fR, ..., \f(CW$delim )" 4
 450 .el .IP "$uri\->query_form( \f(CW$key1\fR => \f(CW$val1\fR, \f(CW$key2\fR => \f(CW$val2\fR, ..., \f(CW$delim\fR )" 4
 451 .IX Item "$uri->query_form( $key1 => $val1, $key2 => $val2, ..., $delim )"
 452 .IP "$uri\->query_form( \e@key_value_pairs )" 4
 453 .IX Item "$uri->query_form( @key_value_pairs )"
 454 .ie n .IP "$uri\->query_form( \e@key_value_pairs, $delim )" 4
 455 .el .IP "$uri\->query_form( \e@key_value_pairs, \f(CW$delim\fR )" 4
 456 .IX Item "$uri->query_form( @key_value_pairs, $delim )"
 457 .IP "$uri\->query_form( \e%hash )" 4
 458 .IX Item "$uri->query_form( %hash )"
 459 .ie n .IP "$uri\->query_form( \e%hash, $delim )" 4
 460 .el .IP "$uri\->query_form( \e%hash, \f(CW$delim\fR )" 4
 461 .IX Item "$uri->query_form( %hash, $delim )"
 462 .PD
 463 Sets and returns query components that use the
 464 \&\fIapplication/x\-www\-form\-urlencoded\fR format.  Key/value pairs are
 465 separated by \*(L"&\*(R", and the key is separated from the value by a \*(L"=\*(R"
 466 character.
 467 .Sp
 468 The form can be set either by passing separate key/value pairs, or via
 469 an array or hash reference.  Passing an empty array or an empty hash
 470 removes the query component, whereas passing no arguments at all leaves
 471 the component unchanged.  The order of keys is undefined if a hash
 472 reference is passed.  The old value is always returned as a list of
 473 separate key/value pairs.  Assigning this list to a hash is unwise as
 474 the keys returned might repeat.
 475 .Sp
 476 The values passed when setting the form can be plain strings or
 477 references to arrays of strings.  Passing an array of values has the
 478 same effect as passing the key repeatedly with one value at a time.
 479 All the following statements have the same effect:
 480 .Sp
 481 .Vb 5
 482 \&    $uri\->query_form(foo => 1, foo => 2);
 483 \&    $uri\->query_form(foo => [1, 2]);
 484 \&    $uri\->query_form([ foo => 1, foo => 2 ]);
 485 \&    $uri\->query_form([ foo => [1, 2] ]);
 486 \&    $uri\->query_form({ foo => [1, 2] });
 487 .Ve
 488 .Sp
 489 The \f(CW$delim\fR parameter can be passed as \*(L";\*(R" to force the key/value pairs
 490 to be delimited by \*(L";\*(R" instead of \*(L"&\*(R" in the query string.  This
 491 practice is often recommended for URLs embedded in \s-1HTML\s0 or \s-1XML\s0
 492 documents as this avoids the trouble of escaping the \*(L"&\*(R" character.
 493 You might also set the \f(CW$URI::DEFAULT_QUERY_FORM_DELIMITER\fR variable to
 494 \&\*(L";\*(R" for the same global effect.
 495 .Sp
 496 The \f(CW\*(C`URI::QueryParam\*(C'\fR module can be loaded to add further methods to
 497 manipulate the form of a \s-1URI\s0.  See URI::QueryParam for details.
 498 .IP "$uri\->query_keywords" 4
 499 .IX Item "$uri->query_keywords"
 500 .PD 0
 501 .ie n .IP "$uri\->query_keywords( $keywords, ... )" 4
 502 .el .IP "$uri\->query_keywords( \f(CW$keywords\fR, ... )" 4
 503 .IX Item "$uri->query_keywords( $keywords, ... )"
 504 .IP "$uri\->query_keywords( \e@keywords )" 4
 505 .IX Item "$uri->query_keywords( @keywords )"
 506 .PD
 507 Sets and returns query components that use the
 508 keywords separated by \*(L"+\*(R" format.
 509 .Sp
 510 The keywords can be set either by passing separate keywords directly
 511 or by passing a reference to an array of keywords.  Passing an empty
 512 array removes the query component, whereas passing no arguments at
 513 all leaves the component unchanged.  The old value is always returned
 514 as a list of separate words.
 515 .SH "SERVER METHODS"
 516 .IX Header "SERVER METHODS"
 517 For schemes where the \fIauthority\fR component denotes an Internet host,
 518 the following methods are available in addition to the generic
 519 methods.
 520 .IP "$uri\->userinfo" 4
 521 .IX Item "$uri->userinfo"
 522 .PD 0
 523 .ie n .IP "$uri\->userinfo( $new_userinfo )" 4
 524 .el .IP "$uri\->userinfo( \f(CW$new_userinfo\fR )" 4
 525 .IX Item "$uri->userinfo( $new_userinfo )"
 526 .PD
 527 Sets and returns the escaped userinfo part of the
 528 authority component.
 529 .Sp
 530 For some schemes this is a user name and a password separated by
 531 a colon.  This practice is not recommended. Embedding passwords in
 532 clear text (such as \s-1URI\s0) has proven to be a security risk in almost
 533 every case where it has been used.
 534 .IP "$uri\->host" 4
 535 .IX Item "$uri->host"
 536 .PD 0
 537 .ie n .IP "$uri\->host( $new_host )" 4
 538 .el .IP "$uri\->host( \f(CW$new_host\fR )" 4
 539 .IX Item "$uri->host( $new_host )"
 540 .PD
 541 Sets and returns the unescaped hostname.
 542 .Sp
 543 If the \f(CW$new_host\fR string ends with a colon and a number, then this
 544 number also sets the port.
 545 .Sp
 546 For IPv6 addresses the brackets around the raw address is removed in the return
 547 value from \f(CW$uri\fR\->host.  When setting the host attribute to an IPv6 address you
 548 can use a raw address or one enclosed in brackets.  The address needs to be
 549 enclosed in brackets if you want to pass in a new port value as well.
 550 .IP "$uri\->ihost" 4
 551 .IX Item "$uri->ihost"
 552 Returns the host in Unicode form.  Any \s-1IDNA\s0 A\-labels are turned into U\-labels.
 553 .IP "$uri\->port" 4
 554 .IX Item "$uri->port"
 555 .PD 0
 556 .ie n .IP "$uri\->port( $new_port )" 4
 557 .el .IP "$uri\->port( \f(CW$new_port\fR )" 4
 558 .IX Item "$uri->port( $new_port )"
 559 .PD
 560 Sets and returns the port.  The port is a simple integer
 561 that should be greater than 0.
 562 .Sp
 563 If a port is not specified explicitly in the \s-1URI\s0, then the \s-1URI\s0 scheme's default port
 564 is returned. If you don't want the default port
 565 substituted, then you can use the \f(CW$uri\fR\->_port method instead.
 566 .IP "$uri\->host_port" 4
 567 .IX Item "$uri->host_port"
 568 .PD 0
 569 .ie n .IP "$uri\->host_port( $new_host_port )" 4
 570 .el .IP "$uri\->host_port( \f(CW$new_host_port\fR )" 4
 571 .IX Item "$uri->host_port( $new_host_port )"
 572 .PD
 573 Sets and returns the host and port as a single
 574 unit.  The returned value includes a port, even if it matches the
 575 default port.  The host part and the port part are separated by a
 576 colon: \*(L":\*(R".
 577 .Sp
 578 For IPv6 addresses the bracketing is preserved; thus
 579 \&\s-1URI\-\s0>new(\*(L"http://[::1]/\*(R")\->host_port returns \*(L"[::1]:80\*(R".  Contrast this with
 580 \&\f(CW$uri\fR\->host which will remove the brackets.
 581 .IP "$uri\->default_port" 4
 582 .IX Item "$uri->default_port"
 583 Returns the default port of the \s-1URI\s0 scheme to which \f(CW$uri\fR
 584 belongs.  For \fIhttp\fR this is the number 80, for \fIftp\fR this
 585 is the number 21, etc.  The default port for a scheme can not be
 586 changed.
 587 .SH "SCHEME-SPECIFIC SUPPORT"
 588 .IX Header "SCHEME-SPECIFIC SUPPORT"
 589 Scheme-specific support is provided for the following \s-1URI\s0 schemes.  For \f(CW\*(C`URI\*(C'\fR
 590 objects that do not belong to one of these, you can only use the common and
 591 generic methods.
 592 .IP "\fBdata\fR:" 4
 593 .IX Item "data:"
 594 The \fIdata\fR \s-1URI\s0 scheme is specified in \s-1RFC\s0 2397.  It allows inclusion
 595 of small data items as \*(L"immediate\*(R" data, as if it had been included
 596 externally.
 597 .Sp
 598 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the data scheme support the common methods
 599 and two new methods to access their scheme-specific components:
 600 \&\f(CW$uri\fR\->media_type and \f(CW$uri\fR\->data.  See URI::data for details.
 601 .IP "\fBfile\fR:" 4
 602 .IX Item "file:"
 603 An old specification of the \fIfile\fR \s-1URI\s0 scheme is found in \s-1RFC\s0 1738.
 604 A new \s-1RFC\s0 2396 based specification in not available yet, but file \s-1URI\s0
 605 references are in common use.
 606 .Sp
 607 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the file scheme support the common and
 608 generic methods.  In addition, they provide two methods for mapping file URIs
 609 back to local file names; \f(CW$uri\fR\->file and \f(CW$uri\fR\->dir.  See URI::file
 610 for details.
 611 .IP "\fBftp\fR:" 4
 612 .IX Item "ftp:"
 613 An old specification of the \fIftp\fR \s-1URI\s0 scheme is found in \s-1RFC\s0 1738.  A
 614 new \s-1RFC\s0 2396 based specification in not available yet, but ftp \s-1URI\s0
 615 references are in common use.
 616 .Sp
 617 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the ftp scheme support the common,
 618 generic and server methods.  In addition, they provide two methods for
 619 accessing the userinfo sub\-components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->password.
 620 .IP "\fBgopher\fR:" 4
 621 .IX Item "gopher:"
 622 The \fIgopher\fR \s-1URI\s0 scheme is specified in
 623 <draft\-murali\-url\-gopher\-1996\-12\-04> and will hopefully be available
 624 as a \s-1RFC\s0 2396 based specification.
 625 .Sp
 626 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the gopher scheme support the common,
 627 generic and server methods. In addition, they support some methods for
 628 accessing gopher-specific path components: \f(CW$uri\fR\->gopher_type,
 629 \&\f(CW$uri\fR\->selector, \f(CW$uri\fR\->search, \f(CW$uri\fR\->string.
 630 .IP "\fBhttp\fR:" 4
 631 .IX Item "http:"
 632 The \fIhttp\fR \s-1URI\s0 scheme is specified in \s-1RFC\s0 2616.
 633 The scheme is used to reference resources hosted by \s-1HTTP\s0 servers.
 634 .Sp
 635 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the http scheme support the common,
 636 generic and server methods.
 637 .IP "\fBhttps\fR:" 4
 638 .IX Item "https:"
 639 The \fIhttps\fR \s-1URI\s0 scheme is a Netscape invention which is commonly
 640 implemented.  The scheme is used to reference \s-1HTTP\s0 servers through \s-1SSL\s0
 641 connections.  Its syntax is the same as http, but the default
 642 port is different.
 643 .IP "\fBldap\fR:" 4
 644 .IX Item "ldap:"
 645 The \fIldap\fR \s-1URI\s0 scheme is specified in \s-1RFC\s0 2255.  \s-1LDAP\s0 is the
 646 Lightweight Directory Access Protocol.  An ldap \s-1URI\s0 describes an \s-1LDAP\s0
 647 search operation to perform to retrieve information from an \s-1LDAP\s0
 648 directory.
 649 .Sp
 650 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the ldap scheme support the common,
 651 generic and server methods as well as ldap-specific methods: \f(CW$uri\fR\->dn,
 652 \&\f(CW$uri\fR\->attributes, \f(CW$uri\fR\->scope, \f(CW$uri\fR\->filter, \f(CW$uri\fR\->extensions.  See
 653 URI::ldap for details.
 654 .IP "\fBldapi\fR:" 4
 655 .IX Item "ldapi:"
 656 Like the \fIldap\fR \s-1URI\s0 scheme, but uses a \s-1UNIX\s0 domain socket.  The
 657 server methods are not supported, and the local socket path is
 658 available as \f(CW$uri\fR\->un_path.  The \fIldapi\fR scheme is used by the
 659 OpenLDAP package.  There is no real specification for it, but it is
 660 mentioned in various OpenLDAP manual pages.
 661 .IP "\fBldaps\fR:" 4
 662 .IX Item "ldaps:"
 663 Like the \fIldap\fR \s-1URI\s0 scheme, but uses an \s-1SSL\s0 connection.  This
 664 scheme is deprecated, as the preferred way is to use the \fIstart_tls\fR
 665 mechanism.
 666 .IP "\fBmailto\fR:" 4
 667 .IX Item "mailto:"
 668 The \fImailto\fR \s-1URI\s0 scheme is specified in \s-1RFC\s0 2368.  The scheme was
 669 originally used to designate the Internet mailing address of an
 670 individual or service.  It has (in \s-1RFC\s0 2368) been extended to allow
 671 setting of other mail header fields and the message body.
 672 .Sp
 673 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the mailto scheme support the common
 674 methods and the generic query methods.  In addition, they support the
 675 following mailto-specific methods: \f(CW$uri\fR\->to, \f(CW$uri\fR\->headers.
 676 .Sp
 677 Note that the \*(L"foo@example.com\*(R" part of a mailto is \fInot\fR the
 678 \&\f(CW\*(C`userinfo\*(C'\fR and \f(CW\*(C`host\*(C'\fR but instead the \f(CW\*(C`path\*(C'\fR.  This allowed a
 679 mailto to contain multiple comma-seperated email addresses.
 680 .IP "\fBmms\fR:" 4
 681 .IX Item "mms:"
 682 The \fImms\fR \s-1URL\s0 specification can be found at <http://sdp.ppona.com/>
 683 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the mms scheme support the common,
 684 generic, and server methods, with the exception of userinfo and
 685 query-related sub\-components.
 686 .IP "\fBnews\fR:" 4
 687 .IX Item "news:"
 688 The \fInews\fR, \fInntp\fR and \fIsnews\fR \s-1URI\s0 schemes are specified in
 689 <draft\-gilman\-news\-url\-01> and will hopefully be available as an \s-1RFC\s0
 690 2396 based specification soon.
 691 .Sp
 692 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the news scheme support the common,
 693 generic and server methods.  In addition, they provide some methods to
 694 access the path: \f(CW$uri\fR\->group and \f(CW$uri\fR\->message.
 695 .IP "\fBnntp\fR:" 4
 696 .IX Item "nntp:"
 697 See \fInews\fR scheme.
 698 .IP "\fBpop\fR:" 4
 699 .IX Item "pop:"
 700 The \fIpop\fR \s-1URI\s0 scheme is specified in \s-1RFC\s0 2384. The scheme is used to
 701 reference a \s-1POP3\s0 mailbox.
 702 .Sp
 703 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the pop scheme support the common, generic
 704 and server methods.  In addition, they provide two methods to access the
 705 userinfo components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->auth
 706 .IP "\fBrlogin\fR:" 4
 707 .IX Item "rlogin:"
 708 An old specification of the \fIrlogin\fR \s-1URI\s0 scheme is found in \s-1RFC\s0
 709 1738. \f(CW\*(C`URI\*(C'\fR objects belonging to the rlogin scheme support the
 710 common, generic and server methods.
 711 .IP "\fBrtsp\fR:" 4
 712 .IX Item "rtsp:"
 713 The \fIrtsp\fR \s-1URL\s0 specification can be found in section 3.2 of \s-1RFC\s0 2326.
 714 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the rtsp scheme support the common,
 715 generic, and server methods, with the exception of userinfo and
 716 query-related sub\-components.
 717 .IP "\fBrtspu\fR:" 4
 718 .IX Item "rtspu:"
 719 The \fIrtspu\fR \s-1URI\s0 scheme is used to talk to \s-1RTSP\s0 servers over \s-1UDP\s0
 720 instead of \s-1TCP\s0.  The syntax is the same as rtsp.
 721 .IP "\fBrsync\fR:" 4
 722 .IX Item "rsync:"
 723 Information about rsync is available from http://rsync.samba.org.
 724 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the rsync scheme support the common,
 725 generic and server methods.  In addition, they provide methods to
 726 access the userinfo sub\-components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->password.
 727 .IP "\fBsip\fR:" 4
 728 .IX Item "sip:"
 729 The \fIsip\fR \s-1URI\s0 specification is described in sections 19.1 and 25
 730 of \s-1RFC\s0 3261.  \f(CW\*(C`URI\*(C'\fR objects belonging to the sip scheme support the
 731 common, generic, and server methods with the exception of path related
 732 sub\-components.  In addition, they provide two methods to get and set
 733 \&\fIsip\fR parameters: \f(CW$uri\fR\->params_form and \f(CW$uri\fR\->params.
 734 .IP "\fBsips\fR:" 4
 735 .IX Item "sips:"
 736 See \fIsip\fR scheme.  Its syntax is the same as sip, but the default
 737 port is different.
 738 .IP "\fBsnews\fR:" 4
 739 .IX Item "snews:"
 740 See \fInews\fR scheme.  Its syntax is the same as news, but the default
 741 port is different.
 742 .IP "\fBtelnet\fR:" 4
 743 .IX Item "telnet:"
 744 An old specification of the \fItelnet\fR \s-1URI\s0 scheme is found in \s-1RFC\s0
 745 1738. \f(CW\*(C`URI\*(C'\fR objects belonging to the telnet scheme support the
 746 common, generic and server methods.
 747 .IP "\fBtn3270\fR:" 4
 748 .IX Item "tn3270:"
 749 These URIs are used like \fItelnet\fR URIs but for connections to \s-1IBM\s0
 750 mainframes.  \f(CW\*(C`URI\*(C'\fR objects belonging to the tn3270 scheme support the
 751 common, generic and server methods.
 752 .IP "\fBssh\fR:" 4
 753 .IX Item "ssh:"
 754 Information about ssh is available at http://www.openssh.com/.
 755 \&\f(CW\*(C`URI\*(C'\fR objects belonging to the ssh scheme support the common,
 756 generic and server methods. In addition, they provide methods to
 757 access the userinfo sub\-components: \f(CW$uri\fR\->user and \f(CW$uri\fR\->password.
 758 .IP "\fBurn\fR:" 4
 759 .IX Item "urn:"
 760 The syntax of Uniform Resource Names is specified in \s-1RFC\s0 2141.  \f(CW\*(C`URI\*(C'\fR
 761 objects belonging to the urn scheme provide the common methods, and also the
 762 methods \f(CW$uri\fR\->nid and \f(CW$uri\fR\->nss, which return the Namespace Identifier
 763 and the Namespace-Specific String respectively.
 764 .Sp
 765 The Namespace Identifier basically works like the Scheme identifier of
 766 URIs, and further divides the \s-1URN\s0 namespace.  Namespace Identifier
 767 assignments are maintained at
 768 <http://www.iana.org/assignments/urn\-namespaces>.
 769 .Sp
 770 Letter case is not significant for the Namespace Identifier.  It is
 771 always returned in lower case by the \f(CW$uri\fR\->nid method.  The \f(CW$uri\fR\->_nid
 772 method can be used if you want it in its original case.
 773 .IP "\fBurn\fR:\fBisbn\fR:" 4
 774 .IX Item "urn:isbn:"
 775 The \f(CW\*(C`urn:isbn:\*(C'\fR namespace contains International Standard Book
 776 Numbers (ISBNs) and is described in \s-1RFC\s0 3187.  A \f(CW\*(C`URI\*(C'\fR object belonging
 777 to this namespace has the following extra methods (if the
 778 Business::ISBN module is available): \f(CW$uri\fR\->isbn,
 779 \&\f(CW$uri\fR\->isbn_publisher_code, \f(CW$uri\fR\->isbn_group_code (formerly isbn_country_code,
 780 which is still supported by issues a deprecation warning), \f(CW$uri\fR\->isbn_as_ean.
 781 .IP "\fBurn\fR:\fBoid\fR:" 4
 782 .IX Item "urn:oid:"
 783 The \f(CW\*(C`urn:oid:\*(C'\fR namespace contains Object Identifiers (OIDs) and is
 784 described in \s-1RFC\s0 3061.  An object identifier consists of sequences of digits
 785 separated by dots.  A \f(CW\*(C`URI\*(C'\fR object belonging to this namespace has an
 786 additional method called \f(CW$uri\fR\->oid that can be used to get/set the oid
 787 value.  In a list context, oid numbers are returned as separate elements.
 788 .SH "CONFIGURATION VARIABLES"
 789 .IX Header "CONFIGURATION VARIABLES"
 790 The following configuration variables influence how the class and its
 791 methods behave:
 792 .IP "$URI::ABS_ALLOW_RELATIVE_SCHEME" 4
 793 .IX Item "$URI::ABS_ALLOW_RELATIVE_SCHEME"
 794 Some older parsers used to allow the scheme name to be present in the
 795 relative \s-1URL\s0 if it was the same as the base \s-1URL\s0 scheme.  \s-1RFC\s0 2396 says
 796 that this should be avoided, but you can enable this old behaviour by
 797 setting the \f(CW$URI::ABS_ALLOW_RELATIVE_SCHEME\fR variable to a \s-1TRUE\s0 value.
 798 The difference is demonstrated by the following examples:
 799 .Sp
 800 .Vb 2
 801 \&  URI\->new("http:foo")\->abs("http://host/a/b")
 802 \&      ==>  "http:foo"
 803 .Ve
 804 .Sp
 805 .Vb 3
 806 \&  local $URI::ABS_ALLOW_RELATIVE_SCHEME = 1;
 807 \&  URI\->new("http:foo")\->abs("http://host/a/b")
 808 \&      ==>  "http:/host/a/foo"
 809 .Ve
 810 .IP "$URI::ABS_REMOTE_LEADING_DOTS" 4
 811 .IX Item "$URI::ABS_REMOTE_LEADING_DOTS"
 812 You can also have the \fIabs()\fR method ignore excess \*(L"..\*(R"
 813 segments in the relative \s-1URI\s0 by setting \f(CW$URI::ABS_REMOTE_LEADING_DOTS\fR
 814 to a \s-1TRUE\s0 value.  The difference is demonstrated by the following
 815 examples:
 816 .Sp
 817 .Vb 2
 818 \&  URI\->new("../../../foo")\->abs("http://host/a/b")
 819 \&      ==> "http://host/../../foo"
 820 .Ve
 821 .Sp
 822 .Vb 3
 823 \&  local $URI::ABS_REMOTE_LEADING_DOTS = 1;
 824 \&  URI\->new("../../../foo")\->abs("http://host/a/b")
 825 \&      ==> "http://host/foo"
 826 .Ve
 827 .IP "$URI::DEFAULT_QUERY_FORM_DELIMITER" 4
 828 .IX Item "$URI::DEFAULT_QUERY_FORM_DELIMITER"
 829 This value can be set to \*(L";\*(R" to have the query form \f(CW\*(C`key=value\*(C'\fR pairs
 830 delimited by \*(L";\*(R" instead of \*(L"&\*(R" which is the default.
 831 .SH "BUGS"
 832 .IX Header "BUGS"
 833 Using regexp variables like \f(CW$1\fR directly as arguments to the \s-1URI\s0 methods
 834 does not work too well with current perl implementations.  I would argue
 835 that this is actually a bug in perl.  The workaround is to quote
 836 them. Example:
 837 .PP
 838 .Vb 2
 839 \&   /(...)/ || die;
 840 \&   $u\->query("$1");
 841 .Ve
 842 .SH "PARSING URIs WITH REGEXP"
 843 .IX Header "PARSING URIs WITH REGEXP"
 844 As an alternative to this module, the following (official) regular
 845 expression can be used to decode a \s-1URI:\s0
 846 .PP
 847 .Vb 2
 848 \&  my($scheme, $authority, $path, $query, $fragment) =
 849 \&  $uri =~ m|(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\e?([^#]*))?(?:#(.*))?|;
 850 .Ve
 851 .PP
 852 The \f(CW\*(C`URI::Split\*(C'\fR module provides the function \fIuri_split()\fR as a
 853 readable alternative.
 854 .SH "SEE ALSO"
 855 .IX Header "SEE ALSO"
 856 URI::file, URI::WithBase, URI::QueryParam, URI::Escape,
 857 URI::Split, URI::Heuristic
 858 .PP
 859 \&\s-1RFC\s0 2396: \*(L"Uniform Resource Identifiers (\s-1URI\s0): Generic Syntax\*(R",
 860 Berners\-Lee, Fielding, Masinter, August 1998.
 861 .PP
 862 http://www.iana.org/assignments/uri\-schemes
 863 .PP
 864 http://www.iana.org/assignments/urn\-namespaces
 865 .PP
 866 http://www.w3.org/Addressing/
 867 .SH "COPYRIGHT"
 868 .IX Header "COPYRIGHT"
 869 Copyright 1995\-2009 Gisle Aas.
 870 .PP
 871 Copyright 1995 Martijn Koster.
 872 .PP
 873 This program is free software; you can redistribute it and/or modify
 874 it under the same terms as Perl itself.
 875 .SH "AUTHORS / ACKNOWLEDGMENTS"
 876 .IX Header "AUTHORS / ACKNOWLEDGMENTS"
 877 This module is based on the \f(CW\*(C`URI::URL\*(C'\fR module, which in turn was
 878 (distantly) based on the \f(CW\*(C`wwwurl.pl\*(C'\fR code in the libwww-perl for
 879 perl4 developed by Roy Fielding, as part of the Arcadia project at the
 880 University of California, Irvine, with contributions from Brooks
 881 Cutter.
 882 .PP
 883 \&\f(CW\*(C`URI::URL\*(C'\fR was developed by Gisle Aas, Tim Bunce, Roy Fielding and
 884 Martijn Koster with input from other people on the libwww-perl mailing
 885 list.
 886 .PP
 887 \&\f(CW\*(C`URI\*(C'\fR and related subclasses was developed by Gisle Aas.