Commit 651474ff62b4d928a4431a9d680d0f2190298374

Improvements to the HTTP::Config documentation.
lib/HTTP/Config.pm
(31 / 6)
  
208208 }
209209 @m = sort { $b->{_order} cmp $a->{_order} } @m;
210210 delete $_->{_order} for @m;
211 return @m;
211 return @m if wantarray;
212 return $m[0];
212213}
213214
214215sub add_item {
……
234234
235235=head1 NAME
236236
237HTTP::Config -
237HTTP::Config - Configuration for request and response objects
238238
239239=head1 SYNOPSIS
240240
241241 use HTTP::Config;
242 my $c = HTTP::Config->new;
243 $c->add(m_domain => ".example.com", m_scheme => "http", verbose => 1);
244
245 use HTTP::Request;
246 my $request = HTTP::Request->new(GET => "http://www.example.com");
247
248 if (my @m = $c->matching($request)) {
249 print "Yadayada\n" if $m[0]->{verbose};
250 }
242251
243252=head1 DESCRIPTION
244253
245An C<HTTP::Config> object is basically a list of entries (hashes) that
246can be matched against requests or request/response pairs. It's
254An C<HTTP::Config> object is a list of entries that
255can be matched against request or request/response pairs. Its
247256purpose is to hold configuration data that can be looked up given a
248257request or response object.
249258
……
266266
267267=item $conf = HTTP::Config->new
268268
269Constructor
269Constructs a new empty C<HTTP::Config> object and returns it.
270270
271271=item $conf->entries
272272
273273Returns the list of entries in the configuration object.
274In scalar context returns the number of entries.
274275
275276=item $conf->empty
276277
277278Return true if there are no entries in the configuration object.
279This is just a shorthand for C<< not $conf->entries >>.
278280
279281=item $conf->add( %matchspec, %other )
280282
281283=item $conf->add( \%entry )
282284
283285Adds a new entry to the configuration.
286You can either pass separate key/value pairs or a hash reference.
284287
285288=item $conf->remove( %spec )
286289
287Removes (and returns) the entries that match.
290Removes (and returns) the entries that have matches for all the key/value pairs in %spec.
291If %spec is empty this will match all entries; so it will empty the configuation object.
288292
289293=item $conf->matching( $uri, $request, $response )
290294
……
300300
301301Returns the entries that match the given $uri, $request and $response triplet.
302302
303If called with a single $request object then the $uri is obtained by calling its 'uri_canonical' method.
304If called with a single $response object, then the request object is obtained by calling its 'request' method;
305and then the $uri is obtained as if a single $request was provided.
306
303307The entries are returned with the most specific matches first.
308In scalar context returns the most specific match or C<undef> in none match.
304309
305310=item $conf->add_item( $item, %matchspec )
306311
……
323323of these you can provide an array of values instead of a single value.
324324The entry matches if at least one of the values in the array matches.
325325
326Entries that require match against a response object attribute will never match
327unless a response object was provided.
328
326329=over
327330
328331=item m_scheme => $scheme
……
395395=item m_media_type => "text/html"
396396
397397Matches if the response media type matches.
398
399With a value of "html" matches if $response->content_is_html returns TRUE.
400With a value of "xhtml" matches if $response->content_is_xhtml returns TRUE.
398401
399402=item m_uri__I<$method> => undef
400403