1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
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<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
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.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
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
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
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'
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 \
129 .\" ========================================================================
131 .IX Title "HTTP::Config 3"
132 .TH HTTP::Config 3 "2008-10-20" "perl v5.8.7" "User Contributed Perl Documentation"
134 HTTP::Config \- Configuration for request and response objects
136 .IX Header "SYNOPSIS"
139 \& my $c = HTTP::Config\->new;
140 \& $c\->add(m_domain => ".example.com", m_scheme => "http", verbose => 1);
144 \& use HTTP::Request;
145 \& my $request = HTTP::Request\->new(GET => "http://www.example.com");
149 \& if (my @m = $c\->matching($request)) {
150 \& print "Yadayada\en" if $m[0]\->{verbose};
154 .IX Header "DESCRIPTION"
155 An \f(CW\*(C`HTTP::Config\*(C'\fR object is a list of entries that
156 can be matched against request or request/response pairs. Its
157 purpose is to hold configuration data that can be looked up given a
158 request or response object.
160 Each configuration entry is a hash. Some keys specify matching to
161 occur against attributes of request/response objects. Other keys can
162 be used to hold user data.
164 The following methods are provided:
165 .IP "$conf = HTTP::Config\->new" 4
166 .IX Item "$conf = HTTP::Config->new"
167 Constructs a new empty \f(CW\*(C`HTTP::Config\*(C'\fR object and returns it.
168 .IP "$conf\->entries" 4
169 .IX Item "$conf->entries"
170 Returns the list of entries in the configuration object.
171 In scalar context returns the number of entries.
172 .IP "$conf\->empty" 4
173 .IX Item "$conf->empty"
174 Return true if there are no entries in the configuration object.
175 This is just a shorthand for \f(CW\*(C`not $conf\->entries\*(C'\fR.
176 .ie n .IP "$conf\->add( %matchspec\fR, \f(CW%other )" 4
177 .el .IP "$conf\->add( \f(CW%matchspec\fR, \f(CW%other\fR )" 4
178 .IX Item "$conf->add( %matchspec, %other )"
180 .IP "$conf\->add( \e%entry )" 4
181 .IX Item "$conf->add( %entry )"
183 Adds a new entry to the configuration.
184 You can either pass separate key/value pairs or a hash reference.
185 .ie n .IP "$conf\->remove( %spec )" 4
186 .el .IP "$conf\->remove( \f(CW%spec\fR )" 4
187 .IX Item "$conf->remove( %spec )"
188 Removes (and returns) the entries that have matches for all the key/value pairs in \f(CW%spec\fR.
189 If \f(CW%spec\fR is empty this will match all entries; so it will empty the configuation object.
190 .ie n .IP "$conf\->matching( $uri\fR, \f(CW$request\fR, \f(CW$response )" 4
191 .el .IP "$conf\->matching( \f(CW$uri\fR, \f(CW$request\fR, \f(CW$response\fR )" 4
192 .IX Item "$conf->matching( $uri, $request, $response )"
194 .ie n .IP "$conf\->matching( $uri )" 4
195 .el .IP "$conf\->matching( \f(CW$uri\fR )" 4
196 .IX Item "$conf->matching( $uri )"
197 .ie n .IP "$conf\->matching( $request )" 4
198 .el .IP "$conf\->matching( \f(CW$request\fR )" 4
199 .IX Item "$conf->matching( $request )"
200 .ie n .IP "$conf\->matching( $response )" 4
201 .el .IP "$conf\->matching( \f(CW$response\fR )" 4
202 .IX Item "$conf->matching( $response )"
204 Returns the entries that match the given \f(CW$uri\fR, \f(CW$request\fR and \f(CW$response\fR triplet.
206 If called with a single \f(CW$request\fR object then the \f(CW$uri\fR is obtained by calling its 'uri_canonical' method.
207 If called with a single \f(CW$response\fR object, then the request object is obtained by calling its 'request' method;
208 and then the \f(CW$uri\fR is obtained as if a single \f(CW$request\fR was provided.
210 The entries are returned with the most specific matches first.
211 In scalar context returns the most specific match or \f(CW\*(C`undef\*(C'\fR in none match.
212 .ie n .IP "$conf\->add_item( $item\fR, \f(CW%matchspec )" 4
213 .el .IP "$conf\->add_item( \f(CW$item\fR, \f(CW%matchspec\fR )" 4
214 .IX Item "$conf->add_item( $item, %matchspec )"
216 .ie n .IP "$conf\->remove_items( %spec )" 4
217 .el .IP "$conf\->remove_items( \f(CW%spec\fR )" 4
218 .IX Item "$conf->remove_items( %spec )"
219 .ie n .IP "$conf\->matching_items( $uri\fR, \f(CW$request\fR, \f(CW$response )" 4
220 .el .IP "$conf\->matching_items( \f(CW$uri\fR, \f(CW$request\fR, \f(CW$response\fR )" 4
221 .IX Item "$conf->matching_items( $uri, $request, $response )"
223 Wrappers that hides the entries themselves.
225 .IX Subsection "Matching"
226 The following keys on a configuration entry specify matching. For all
227 of these you can provide an array of values instead of a single value.
228 The entry matches if at least one of the values in the array matches.
230 Entries that require match against a response object attribute will never match
231 unless a response object was provided.
232 .ie n .IP "m_scheme => $scheme" 4
233 .el .IP "m_scheme => \f(CW$scheme\fR" 4
234 .IX Item "m_scheme => $scheme"
235 Matches if the \s-1URI\s0 uses the specified scheme; e.g. \*(L"http\*(R".
236 .ie n .IP "m_secure => $bool" 4
237 .el .IP "m_secure => \f(CW$bool\fR" 4
238 .IX Item "m_secure => $bool"
239 If \f(CW$bool\fR is \s-1TRUE\s0; matches if the \s-1URI\s0 uses a secure scheme. If \f(CW$bool\fR
240 is \s-1FALSE\s0; matches if the \s-1URI\s0 does not use a secure scheme. An example
241 of a secure scheme is \*(L"https\*(R".
242 .ie n .IP "m_host_port => ""$hostname:$port""" 4
243 .el .IP "m_host_port => ``$hostname:$port''" 4
244 .IX Item "m_host_port => $hostname:$port"
245 Matches if the \s-1URI\s0's host_port method return the specified value.
246 .ie n .IP "m_host => $hostname" 4
247 .el .IP "m_host => \f(CW$hostname\fR" 4
248 .IX Item "m_host => $hostname"
249 Matches if the \s-1URI\s0's host method returns the specified value.
250 .ie n .IP "m_port => $port" 4
251 .el .IP "m_port => \f(CW$port\fR" 4
252 .IX Item "m_port => $port"
253 Matches if the \s-1URI\s0's port method returns the specified value.
254 .ie n .IP "m_domain => "".$domain""" 4
255 .el .IP "m_domain => ``.$domain''" 4
256 .IX Item "m_domain => .$domain"
257 Matches if the \s-1URI\s0's host method return a value that within the given
258 domain. The hostname \*(L"www.example.com\*(R" will for instance match the
259 domain \*(L".com\*(R".
260 .ie n .IP "m_path => $path" 4
261 .el .IP "m_path => \f(CW$path\fR" 4
262 .IX Item "m_path => $path"
263 Matches if the \s-1URI\s0's path method returns the specified value.
264 .ie n .IP "m_path_prefix => $path" 4
265 .el .IP "m_path_prefix => \f(CW$path\fR" 4
266 .IX Item "m_path_prefix => $path"
267 Matches if the \s-1URI\s0's path is the specified path or has the specified
269 .ie n .IP "m_path_match => $Regexp" 4
270 .el .IP "m_path_match => \f(CW$Regexp\fR" 4
271 .IX Item "m_path_match => $Regexp"
272 Matches if the regular expression matches the \s-1URI\s0's path. Eg. qr/\e.html$/.
273 .ie n .IP "m_method => $method" 4
274 .el .IP "m_method => \f(CW$method\fR" 4
275 .IX Item "m_method => $method"
276 Matches if the request method matches the specified value. Eg. \*(L"\s-1GET\s0\*(R" or \*(L"\s-1POST\s0\*(R".
277 .ie n .IP "m_code => $digit" 4
278 .el .IP "m_code => \f(CW$digit\fR" 4
279 .IX Item "m_code => $digit"
281 .ie n .IP "m_code => $status_code" 4
282 .el .IP "m_code => \f(CW$status_code\fR" 4
283 .IX Item "m_code => $status_code"
285 Matches if the response status code matches. If a single digit is
286 specified; matches for all response status codes beginning with that digit.
287 .ie n .IP "m_proxy => $url" 4
288 .el .IP "m_proxy => \f(CW$url\fR" 4
289 .IX Item "m_proxy => $url"
290 Matches if the request is to be sent to the given Proxy server.
291 .ie n .IP "m_media_type => ""*/*""" 4
292 .el .IP "m_media_type => ``*/*''" 4
293 .IX Item "m_media_type => */*"
295 .ie n .IP "m_media_type => ""text/*""" 4
296 .el .IP "m_media_type => ``text/*''" 4
297 .IX Item "m_media_type => text/*"
298 .ie n .IP "m_media_type => ""html""" 4
299 .el .IP "m_media_type => ``html''" 4
300 .IX Item "m_media_type => html"
301 .ie n .IP "m_media_type => ""xhtml""" 4
302 .el .IP "m_media_type => ``xhtml''" 4
303 .IX Item "m_media_type => xhtml"
304 .ie n .IP "m_media_type => ""text/html""" 4
305 .el .IP "m_media_type => ``text/html''" 4
306 .IX Item "m_media_type => text/html"
308 Matches if the response media type matches.
310 With a value of \*(L"html\*(R" matches if \f(CW$response\fR\->content_is_html returns \s-1TRUE\s0.
311 With a value of \*(L"xhtml\*(R" matches if \f(CW$response\fR\->content_is_xhtml returns \s-1TRUE\s0.
312 .IP "m_uri_\|_\fI$method\fR => undef" 4
313 .IX Item "m_uri__$method => undef"
314 Matches if the \s-1URI\s0 object provide the method
315 .ie n .IP "m_uri_\|_\fI$method\fR => $string" 4
316 .el .IP "m_uri_\|_\fI$method\fR => \f(CW$string\fR" 4
317 .IX Item "m_uri__$method => $string"
318 Matches if the \s-1URI\s0's \f(CW$method\fR method returns the given value.
319 .ie n .IP "m_header_\|_\fI$field\fR => $string" 4
320 .el .IP "m_header_\|_\fI$field\fR => \f(CW$string\fR" 4
321 .IX Item "m_header__$field => $string"
322 Matches if either the request or the response have a header \f(CW$field\fR with the given value.
323 .IP "m_response_attr_\|_\fI$key\fR => undef" 4
324 .IX Item "m_response_attr__$key => undef"
326 .ie n .IP "m_response_attr_\|_\fI$key\fR => $string" 4
327 .el .IP "m_response_attr_\|_\fI$key\fR => \f(CW$string\fR" 4
328 .IX Item "m_response_attr__$key => $string"
330 Matches if the response object has a that key; or the entry has the given value.
332 .IX Header "SEE ALSO"
333 \&\s-1URI\s0, HTTP::Request, HTTP::Response
335 .IX Header "COPYRIGHT"
336 Copyright 2008, Gisle Aas
338 This library is free software; you can redistribute it and/or
339 modify it under the same terms as Perl itself.