1HTTP::Headers::ActionPaUcske(r3)Contributed Perl DocumenHtTaTtPi:o:nHeaders::ActionPack(3)
2
3
4

NAME

6       HTTP::Headers::ActionPack - HTTP Action, Adventure and Excitement
7

VERSION

9       version 0.09
10

SYNOPSIS

12         use HTTP::Headers::ActionPack;
13
14         my $pack       = HTTP::Headers::ActionPack->new;
15         my $media_type = $pack->create_header( 'Content-Type' => 'application/xml;charset=UTF-8' );
16         my $link       = $pack->create( 'LinkHeader' => [ '</test/tree>', rel => "up" ] );
17
18         # auto-magic header inflation
19         # for multiple types
20         $pack->inflate( $http_headers_instance );
21         $pack->inflate( $http_request_instance );
22         $pack->inflate( $plack_request_instance );
23

DESCRIPTION

25       This is a module to handle the inflation and deflation of complex HTTP
26       header types. In many cases header values are simple strings, but in
27       some cases they are complex values with a lot of information encoded in
28       them. The goal of this module is to make the parsing and analysis of
29       these headers as easy as calling "inflate" on a compatible object (see
30       below for a list).
31
32       This top-level class is basically a Factory for creating instances of
33       the other classes in this module. It contains a number of convenience
34       methods to help make common cases easy to write.
35

DEFAULT MAPPINGS

37       This class provides a set of default mappings between HTTP headers and
38       the classes which can inflate them. Here is the list of default
39       mappings this class provides.
40
41         Link                HTTP::Headers::ActionPack::LinkList
42         Content-Type        HTTP::Headers::ActionPack::MediaType
43         Accept              HTTP::Headers::ActionPack::MediaTypeList
44         Accept-Charset      HTTP::Headers::ActionPack::PriorityList
45         Accept-Encoding     HTTP::Headers::ActionPack::PriorityList
46         Accept-Language     HTTP::Headers::ActionPack::PriorityList
47         Date                HTTP::Headers::ActionPack::DateHeader
48         Client-Date         HTTP::Headers::ActionPack::DateHeader
49         Expires             HTTP::Headers::ActionPack::DateHeader
50         Last-Modified       HTTP::Headers::ActionPack::DateHeader
51         If-Unmodified-Since HTTP::Headers::ActionPack::DateHeader
52         If-Modified-Since   HTTP::Headers::ActionPack::DateHeader
53         WWW-Authenticate    HTTP::Headers::ActionPack::WWWAuthenticate
54         Authentication-Info HTTP::Headers::ActionPack::AuthenticationInfo
55         Authorization       HTTP::Headers::ActionPack::Authorization
56
57       NOTE: The 'Client-Date' header is often added by LWP on HTTP::Response
58       objects.
59

METHODS

61       new( ?%mappings )
62           The constructor takes an option hash of header-name to class
63           mappings to add too (or override) the default mappings (see above
64           for details). Each class is expected to have a "new_from_string"
65           method which can parse the string representation of the given
66           header and return an object.
67
68       "mapping"
69           This returns the set of mappings in this instance.
70
71       "classes"
72           This returns the list of supported classes, which is by default the
73           list of classes included in this modules, but it also will grab any
74           additionally classes that were specified in the %mappings parameter
75           to "new" (see above).
76
77       "get_content_negotiator"
78           Returns an instance of
79           HTTP::Headers::ActionPack::ContentNegotiation.
80
81       "create( $class_name, $args )"
82           This method, given a $class_name and $args, will inflate the value
83           using the class found in the "classes" list. If $args is a string
84           it will call "new_from_string" on the $class_name, but if $args is
85           an ARRAY ref, it will dereference the ARRAY and pass it to "new".
86
87       "create_header( $header_name, $header_value )"
88           This method, given a $header_name and a $header_value will inflate
89           the value using the class found in the mappings. If $header_value
90           is a string it will call "new_from_string" on the class mapped to
91           the $header_name, but if $header_value is an ARRAY ref, it will
92           dereference the ARRAY and pass it to "new".
93
94       inflate( $http_headers )
95       inflate( $http_request )
96       inflate( $plack_request )
97       inflate( $web_request )
98           Given either a HTTP::Headers instance, a HTTP::Request instance, a
99           Plack::Request instance, or a Web::Request instance, this method
100           will inflate all the relevant headers and store the object in the
101           same instance.
102
103           In theory this should not negatively affect anything since all the
104           header objects overload the stringification operator, and most
105           often the headers are treated as strings. However, this is not for
106           certain and care should be taken.
107

CAVEATS

109   Plack Compatibility
110       We have a test in the suite that checks to make sure that any inflated
111       header objects will pass between HTTP::Request and HTTP::Response
112       objects as well as Plack::Request and Plack::Response objects.
113
114       A simple survey of most of the Plack::Handler subclasses shows that
115       most of them will end up properly stringifying these header objects
116       before sending them out. The notable exceptions were the Apache
117       handlers.
118
119       At the time of this writing, the solution for this would be for you to
120       either stringify these objects prior to returning your Plack::Response,
121       or to write a simple middleware component that would do that for you.
122       In future versions we might provide just such a middleware (it would
123       likely inflate the header objects on the request side as well).
124
125   Stringification
126       As mentioned above, all the header objects overload the stringification
127       operator, so normal usage of them should just do what you would expect
128       (stringify in a sensible way). However this is not certain and so care
129       should be taken when passing object headers onto another library that
130       is expecting strings.
131

AUTHOR

133       Stevan Little <stevan.little@iinteractive.com>
134

CONTRIBUTORS

136       •   Andrew Nelson <anelson@cpan.org>
137
138       •   Dave Rolsky <autarch@urth.org>
139
140       •   Florian Ragwitz <rafl@debian.org>
141
142       •   Jesse Luehrs <doy@tozt.net>
143
144       •   Karen Etheridge <ether@cpan.org>
145
147       This software is copyright (c) 2012 by Infinity Interactive, Inc..
148
149       This is free software; you can redistribute it and/or modify it under
150       the same terms as the Perl 5 programming language system itself.
151
152
153
154perl v5.36.0                      2023-01-20      HTTP::Headers::ActionPack(3)
Impressum