local-lib5/man/man3/URI::QueryParam.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::QueryParam 3"
 132 .TH URI::QueryParam 3 "2009-05-28" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 URI::QueryParam \- Additional query methods for URIs
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  use URI;
 139 \&  use URI::QueryParam;
 140 .Ve
 141 .PP
 142 .Vb 3
 143 \&  $u = URI\->new("", "http");
 144 \&  $u\->query_param(foo => 1, 2, 3);
 145 \&  print $u\->query;    # prints foo=1&foo=2&foo=3
 146 .Ve
 147 .PP
 148 .Vb 3
 149 \&  for my $key ($u\->query_param) {
 150 \&      print "$key: ", join(", ", $u\->query_param($key)), "\en";
 151 \&  }
 152 .Ve
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 Loading the \f(CW\*(C`URI::QueryParam\*(C'\fR module adds some extra methods to
 156 URIs that support query methods.  These methods provide an alternative
 157 interface to the \f(CW$u\fR\->query_form data.
 158 .PP
 159 The query_param_* methods have deliberately been made identical to the
 160 interface of the corresponding \f(CW\*(C`CGI.pm\*(C'\fR methods.
 161 .PP
 162 The following additional methods are made available:
 163 .ie n .IP "@keys = $u\->query_param" 4
 164 .el .IP "@keys = \f(CW$u\fR\->query_param" 4
 165 .IX Item "@keys = $u->query_param"
 166 .PD 0
 167 .ie n .IP "@values = $u\fR\->query_param( \f(CW$key )" 4
 168 .el .IP "@values = \f(CW$u\fR\->query_param( \f(CW$key\fR )" 4
 169 .IX Item "@values = $u->query_param( $key )"
 170 .ie n .IP "$first_value = $u\fR\->query_param( \f(CW$key )" 4
 171 .el .IP "$first_value = \f(CW$u\fR\->query_param( \f(CW$key\fR )" 4
 172 .IX Item "$first_value = $u->query_param( $key )"
 173 .ie n .IP "$u\->query_param( $key\fR, \f(CW$value,... )" 4
 174 .el .IP "$u\->query_param( \f(CW$key\fR, \f(CW$value\fR,... )" 4
 175 .IX Item "$u->query_param( $key, $value,... )"
 176 .PD
 177 If \f(CW$u\fR\->query_param is called with no arguments, it returns all the
 178 distinct parameter keys of the \s-1URI\s0.  In a scalar context it returns the
 179 number of distinct keys.
 180 .Sp
 181 When a \f(CW$key\fR argument is given, the method returns the parameter values with the
 182 given key.  In a scalar context, only the first parameter value is
 183 returned.
 184 .Sp
 185 If additional arguments are given, they are used to update successive
 186 parameters with the given key.  If any of the values provided are
 187 array references, then the array is dereferenced to get the actual
 188 values.
 189 .ie n .IP "$u\->query_param_append($key, $value,...)" 4
 190 .el .IP "$u\->query_param_append($key, \f(CW$value\fR,...)" 4
 191 .IX Item "$u->query_param_append($key, $value,...)"
 192 Adds new parameters with the given
 193 key without touching any old parameters with the same key.  It
 194 can be explained as a more efficient version of:
 195 .Sp
 196 .Vb 3
 197 \&   $u\->query_param($key,
 198 \&                   $u\->query_param($key),
 199 \&                   $value,...);
 200 .Ve
 201 .Sp
 202 One difference is that this expression would return the old values
 203 of \f(CW$key\fR, whereas the \fIquery_param_append()\fR method does not.
 204 .ie n .IP "@values = $u\->query_param_delete($key)" 4
 205 .el .IP "@values = \f(CW$u\fR\->query_param_delete($key)" 4
 206 .IX Item "@values = $u->query_param_delete($key)"
 207 .PD 0
 208 .ie n .IP "$first_value = $u\->query_param_delete($key)" 4
 209 .el .IP "$first_value = \f(CW$u\fR\->query_param_delete($key)" 4
 210 .IX Item "$first_value = $u->query_param_delete($key)"
 211 .PD
 212 Deletes all key/value pairs with the given key.
 213 The old values are returned.  In a scalar context, only the first value
 214 is returned.
 215 .Sp
 216 Using the \fIquery_param_delete()\fR method is slightly more efficient than
 217 the equivalent:
 218 .Sp
 219 .Vb 1
 220 \&   $u\->query_param($key, []);
 221 .Ve
 222 .ie n .IP "$hashref = $u\->query_form_hash" 4
 223 .el .IP "$hashref = \f(CW$u\fR\->query_form_hash" 4
 224 .IX Item "$hashref = $u->query_form_hash"
 225 .PD 0
 226 .IP "$u\->query_form_hash( \e%new_form )" 4
 227 .IX Item "$u->query_form_hash( %new_form )"
 228 .PD
 229 Returns a reference to a hash that represents the
 230 query form's key/value pairs.  If a key occurs multiple times, then the hash
 231 value becomes an array reference.
 232 .Sp
 233 Note that sequence information is lost.  This means that:
 234 .Sp
 235 .Vb 1
 236 \&   $u\->query_form_hash($u\->query_form_hash);
 237 .Ve
 238 .Sp
 239 is not necessarily a no\-op, as it may reorder the key/value pairs.
 240 The values returned by the \fIquery_param()\fR method should stay the same
 241 though.
 242 .SH "SEE ALSO"
 243 .IX Header "SEE ALSO"
 244 \&\s-1URI\s0, \s-1CGI\s0
 245 .SH "COPYRIGHT"
 246 .IX Header "COPYRIGHT"
 247 Copyright 2002 Gisle Aas.