--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "HTTP::Message 3"
+.TH HTTP::Message 3 "2009-11-21" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+HTTP::Message \- HTTP style message (base class)
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use base 'HTTP::Message';
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+An \f(CW\*(C`HTTP::Message\*(C'\fR object contains some headers and a content body.
+The following methods are available:
+.IP "$mess = HTTP::Message\->new" 4
+.IX Item "$mess = HTTP::Message->new"
+.PD 0
+.ie n .IP "$mess = HTTP::Message\->new( $headers )" 4
+.el .IP "$mess = HTTP::Message\->new( \f(CW$headers\fR )" 4
+.IX Item "$mess = HTTP::Message->new( $headers )"
+.ie n .IP "$mess = HTTP::Message\->new( $headers\fR, \f(CW$content )" 4
+.el .IP "$mess = HTTP::Message\->new( \f(CW$headers\fR, \f(CW$content\fR )" 4
+.IX Item "$mess = HTTP::Message->new( $headers, $content )"
+.PD
+This constructs a new message object. Normally you would want
+construct \f(CW\*(C`HTTP::Request\*(C'\fR or \f(CW\*(C`HTTP::Response\*(C'\fR objects instead.
+.Sp
+The optional \f(CW$header\fR argument should be a reference to an
+\&\f(CW\*(C`HTTP::Headers\*(C'\fR object or a plain array reference of key/value pairs.
+If an \f(CW\*(C`HTTP::Headers\*(C'\fR object is provided then a copy of it will be
+embedded into the constructed message, i.e. it will not be owned and
+can be modified afterwards without affecting the message.
+.Sp
+The optional \f(CW$content\fR argument should be a string of bytes.
+.ie n .IP "$mess = HTTP::Message\->parse( $str )" 4
+.el .IP "$mess = HTTP::Message\->parse( \f(CW$str\fR )" 4
+.IX Item "$mess = HTTP::Message->parse( $str )"
+This constructs a new message object by parsing the given string.
+.IP "$mess\->headers" 4
+.IX Item "$mess->headers"
+Returns the embedded \f(CW\*(C`HTTP::Headers\*(C'\fR object.
+.IP "$mess\->headers_as_string" 4
+.IX Item "$mess->headers_as_string"
+.PD 0
+.ie n .IP "$mess\->headers_as_string( $eol )" 4
+.el .IP "$mess\->headers_as_string( \f(CW$eol\fR )" 4
+.IX Item "$mess->headers_as_string( $eol )"
+.PD
+Call the \fIas_string()\fR method for the headers in the
+message. This will be the same as
+.Sp
+.Vb 1
+\& $mess\->headers\->as_string
+.Ve
+.Sp
+but it will make your program a whole character shorter :\-)
+.IP "$mess\->content" 4
+.IX Item "$mess->content"
+.PD 0
+.ie n .IP "$mess\->content( $bytes )" 4
+.el .IP "$mess\->content( \f(CW$bytes\fR )" 4
+.IX Item "$mess->content( $bytes )"
+.PD
+The \fIcontent()\fR method sets the raw content if an argument is given. If no
+argument is given the content is not touched. In either case the
+original raw content is returned.
+.Sp
+Note that the content should be a string of bytes. Strings in perl
+can contain characters outside the range of a byte. The \f(CW\*(C`Encode\*(C'\fR
+module can be used to turn such strings into a string of bytes.
+.ie n .IP "$mess\->add_content( $bytes )" 4
+.el .IP "$mess\->add_content( \f(CW$bytes\fR )" 4
+.IX Item "$mess->add_content( $bytes )"
+The \fIadd_content()\fR methods appends more data bytes to the end of the
+current content buffer.
+.ie n .IP "$mess\->add_content_utf8( $string )" 4
+.el .IP "$mess\->add_content_utf8( \f(CW$string\fR )" 4
+.IX Item "$mess->add_content_utf8( $string )"
+The \fIadd_content_utf8()\fR method appends the \s-1UTF\-8\s0 bytes representing the
+string to the end of the current content buffer.
+.IP "$mess\->content_ref" 4
+.IX Item "$mess->content_ref"
+.PD 0
+.IP "$mess\->content_ref( \e$bytes )" 4
+.IX Item "$mess->content_ref( $bytes )"
+.PD
+The \fIcontent_ref()\fR method will return a reference to content buffer string.
+It can be more efficient to access the content this way if the content
+is huge, and it can even be used for direct manipulation of the content,
+for instance:
+.Sp
+.Vb 1
+\& ${$res\->content_ref} =~ s/\ebfoo\eb/bar/g;
+.Ve
+.Sp
+This example would modify the content buffer in\-place.
+.Sp
+If an argument is passed it will setup the content to reference some
+external source. The \fIcontent()\fR and \fIadd_content()\fR methods
+will automatically dereference scalar references passed this way. For
+other references \fIcontent()\fR will return the reference itself and
+\&\fIadd_content()\fR will refuse to do anything.
+.IP "$mess\->content_charset" 4
+.IX Item "$mess->content_charset"
+This returns the charset used by the content in the message. The
+charset is either found as the charset attribute of the
+\&\f(CW\*(C`Content\-Type\*(C'\fR header or by guessing.
+.Sp
+See <http://www.w3.org/TR/REC\-html40/charset.html#spec\-char\-encoding>
+for details about how charset is determined.
+.ie n .IP "$mess\->decoded_content( %options )" 4
+.el .IP "$mess\->decoded_content( \f(CW%options\fR )" 4
+.IX Item "$mess->decoded_content( %options )"
+Returns the content with any \f(CW\*(C`Content\-Encoding\*(C'\fR undone and the raw
+content encoded to perl's Unicode strings. If the \f(CW\*(C`Content\-Encoding\*(C'\fR
+or \f(CW\*(C`charset\*(C'\fR of the message is unknown this method will fail by
+returning \f(CW\*(C`undef\*(C'\fR.
+.Sp
+The following options can be specified.
+.RS 4
+.ie n .IP """charset""" 4
+.el .IP "\f(CWcharset\fR" 4
+.IX Item "charset"
+This override the charset parameter for text content. The value
+\&\f(CW\*(C`none\*(C'\fR can used to suppress decoding of the charset.
+.ie n .IP """default_charset""" 4
+.el .IP "\f(CWdefault_charset\fR" 4
+.IX Item "default_charset"
+This override the default charset guessed by \fIcontent_charset()\fR or
+if that fails \*(L"\s-1ISO\-8859\-1\s0\*(R".
+.ie n .IP """charset_strict""" 4
+.el .IP "\f(CWcharset_strict\fR" 4
+.IX Item "charset_strict"
+Abort decoding if malformed characters is found in the content. By
+default you get the substitution character (\*(L"\ex{\s-1FFFD\s0}\*(R") in place of
+malformed characters.
+.ie n .IP """raise_error""" 4
+.el .IP "\f(CWraise_error\fR" 4
+.IX Item "raise_error"
+If \s-1TRUE\s0 then raise an exception if not able to decode content. Reason
+might be that the specified \f(CW\*(C`Content\-Encoding\*(C'\fR or \f(CW\*(C`charset\*(C'\fR is not
+supported. If this option is \s-1FALSE\s0, then \fIdecoded_content()\fR will return
+\&\f(CW\*(C`undef\*(C'\fR on errors, but will still set $@.
+.ie n .IP """ref""" 4
+.el .IP "\f(CWref\fR" 4
+.IX Item "ref"
+If \s-1TRUE\s0 then a reference to decoded content is returned. This might
+be more efficient in cases where the decoded content is identical to
+the raw content as no data copying is required in this case.
+.RE
+.RS 4
+.RE
+.IP "$mess\->decodable" 4
+.IX Item "$mess->decodable"
+.PD 0
+.IP "\fIHTTP::Message::decodable()\fR" 4
+.IX Item "HTTP::Message::decodable()"
+.PD
+This returns the encoding identifiers that \fIdecoded_content()\fR can
+process. In scalar context returns a comma separated string of
+identifiers.
+.Sp
+This value is suitable for initializing the \f(CW\*(C`Accept\-Encoding\*(C'\fR request
+header field.
+.IP "$mess\->decode" 4
+.IX Item "$mess->decode"
+This method tries to replace the content of the message with the
+decoded version and removes the \f(CW\*(C`Content\-Encoding\*(C'\fR header. Returns
+\&\s-1TRUE\s0 if successful and \s-1FALSE\s0 if not.
+.Sp
+If the message does not have a \f(CW\*(C`Content\-Encoding\*(C'\fR header this method
+does nothing and returns \s-1TRUE\s0.
+.Sp
+Note that the content of the message is still bytes after this method
+has been called and you still need to call \fIdecoded_content()\fR if you
+want to process its content as a string.
+.ie n .IP "$mess\->encode( $encoding, ... )" 4
+.el .IP "$mess\->encode( \f(CW$encoding\fR, ... )" 4
+.IX Item "$mess->encode( $encoding, ... )"
+Apply the given encodings to the content of the message. Returns \s-1TRUE\s0
+if successful. The \*(L"identity\*(R" (non\-)encoding is always supported; other
+currently supported encodings, subject to availability of required
+additional modules, are \*(L"gzip\*(R", \*(L"deflate\*(R", \*(L"x\-bzip2\*(R" and \*(L"base64\*(R".
+.Sp
+A successful call to this function will set the \f(CW\*(C`Content\-Encoding\*(C'\fR
+header.
+.Sp
+Note that \f(CW\*(C`multipart/*\*(C'\fR or \f(CW\*(C`message/*\*(C'\fR messages can't be encoded and
+this method will croak if you try.
+.IP "$mess\->parts" 4
+.IX Item "$mess->parts"
+.PD 0
+.ie n .IP "$mess\->parts( @parts )" 4
+.el .IP "$mess\->parts( \f(CW@parts\fR )" 4
+.IX Item "$mess->parts( @parts )"
+.IP "$mess\->parts( \e@parts )" 4
+.IX Item "$mess->parts( @parts )"
+.PD
+Messages can be composite, i.e. contain other messages. The composite
+messages have a content type of \f(CW\*(C`multipart/*\*(C'\fR or \f(CW\*(C`message/*\*(C'\fR. This
+method give access to the contained messages.
+.Sp
+The argumentless form will return a list of \f(CW\*(C`HTTP::Message\*(C'\fR objects.
+If the content type of \f(CW$msg\fR is not \f(CW\*(C`multipart/*\*(C'\fR or \f(CW\*(C`message/*\*(C'\fR then
+this will return the empty list. In scalar context only the first
+object is returned. The returned message parts should be regarded as
+read-only (future versions of this library might make it possible
+to modify the parent by modifying the parts).
+.Sp
+If the content type of \f(CW$msg\fR is \f(CW\*(C`message/*\*(C'\fR then there will only be
+one part returned.
+.Sp
+If the content type is \f(CW\*(C`message/http\*(C'\fR, then the return value will be
+either an \f(CW\*(C`HTTP::Request\*(C'\fR or an \f(CW\*(C`HTTP::Response\*(C'\fR object.
+.Sp
+If an \f(CW@parts\fR argument is given, then the content of the message will be
+modified. The array reference form is provided so that an empty list
+can be provided. The \f(CW@parts\fR array should contain \f(CW\*(C`HTTP::Message\*(C'\fR
+objects. The \f(CW@parts\fR objects are owned by \f(CW$mess\fR after this call and
+should not be modified or made part of other messages.
+.Sp
+When updating the message with this method and the old content type of
+\&\f(CW$mess\fR is not \f(CW\*(C`multipart/*\*(C'\fR or \f(CW\*(C`message/*\*(C'\fR, then the content type is
+set to \f(CW\*(C`multipart/mixed\*(C'\fR and all other content headers are cleared.
+.Sp
+This method will croak if the content type is \f(CW\*(C`message/*\*(C'\fR and more
+than one part is provided.
+.ie n .IP "$mess\->add_part( $part )" 4
+.el .IP "$mess\->add_part( \f(CW$part\fR )" 4
+.IX Item "$mess->add_part( $part )"
+This will add a part to a message. The \f(CW$part\fR argument should be
+another \f(CW\*(C`HTTP::Message\*(C'\fR object. If the previous content type of
+\&\f(CW$mess\fR is not \f(CW\*(C`multipart/*\*(C'\fR then the old content (together with all
+content headers) will be made part #1 and the content type made
+\&\f(CW\*(C`multipart/mixed\*(C'\fR before the new part is added. The \f(CW$part\fR object is
+owned by \f(CW$mess\fR after this call and should not be modified or made part
+of other messages.
+.Sp
+There is no return value.
+.IP "$mess\->clear" 4
+.IX Item "$mess->clear"
+Will clear the headers and set the content to the empty string. There
+is no return value
+.IP "$mess\->protocol" 4
+.IX Item "$mess->protocol"
+.PD 0
+.ie n .IP "$mess\->protocol( $proto )" 4
+.el .IP "$mess\->protocol( \f(CW$proto\fR )" 4
+.IX Item "$mess->protocol( $proto )"
+.PD
+Sets the \s-1HTTP\s0 protocol used for the message. The \fIprotocol()\fR is a string
+like \f(CW\*(C`HTTP/1.0\*(C'\fR or \f(CW\*(C`HTTP/1.1\*(C'\fR.
+.IP "$mess\->clone" 4
+.IX Item "$mess->clone"
+Returns a copy of the message object.
+.IP "$mess\->as_string" 4
+.IX Item "$mess->as_string"
+.PD 0
+.ie n .IP "$mess\->as_string( $eol )" 4
+.el .IP "$mess\->as_string( \f(CW$eol\fR )" 4
+.IX Item "$mess->as_string( $eol )"
+.PD
+Returns the message formatted as a single string.
+.Sp
+The optional \f(CW$eol\fR parameter specifies the line ending sequence to use.
+The default is \*(L"\en\*(R". If no \f(CW$eol\fR is given then as_string will ensure
+that the returned string is newline terminated (even when the message
+content is not). No extra newline is appended if an explicit \f(CW$eol\fR is
+passed.
+.ie n .IP "$mess\->dump( %opt )" 4
+.el .IP "$mess\->dump( \f(CW%opt\fR )" 4
+.IX Item "$mess->dump( %opt )"
+Returns the message formatted as a string. In void context print the string.
+.Sp
+This differs from \f(CW\*(C`$mess\->as_string\*(C'\fR in that it escapes the bytes
+of the content so that it's safe to print them and it limits how much
+content to print. The escapes syntax used is the same as for Perl's
+double quoted strings. If there is no content the string \*(L"(no
+content)\*(R" is shown in its place.
+.Sp
+Options to influence the output can be passed as key/value pairs. The
+following options are recognized:
+.RS 4
+.ie n .IP "maxlength => $num" 4
+.el .IP "maxlength => \f(CW$num\fR" 4
+.IX Item "maxlength => $num"
+How much of the content to show. The default is 512. Set this to 0
+for unlimited.
+.Sp
+If the content is longer then the string is chopped at the limit and
+the string \*(L"...\en(### more bytes not shown)\*(R" appended.
+.ie n .IP "prefix => $str" 4
+.el .IP "prefix => \f(CW$str\fR" 4
+.IX Item "prefix => $str"
+A string that will be prefixed to each line of the dump.
+.RE
+.RS 4
+.RE
+.PP
+All methods unknown to \f(CW\*(C`HTTP::Message\*(C'\fR itself are delegated to the
+\&\f(CW\*(C`HTTP::Headers\*(C'\fR object that is part of every message. This allows
+convenient access to these methods. Refer to HTTP::Headers for
+details of these methods:
+.PP
+.Vb 7
+\& $mess\->header( $field => $val )
+\& $mess\->push_header( $field => $val )
+\& $mess\->init_header( $field => $val )
+\& $mess\->remove_header( $field )
+\& $mess\->remove_content_headers
+\& $mess\->header_field_names
+\& $mess\->scan( \e&doit )
+.Ve
+.PP
+.Vb 19
+\& $mess\->date
+\& $mess\->expires
+\& $mess\->if_modified_since
+\& $mess\->if_unmodified_since
+\& $mess\->last_modified
+\& $mess\->content_type
+\& $mess\->content_encoding
+\& $mess\->content_length
+\& $mess\->content_language
+\& $mess\->title
+\& $mess\->user_agent
+\& $mess\->server
+\& $mess\->from
+\& $mess\->referer
+\& $mess\->www_authenticate
+\& $mess\->authorization
+\& $mess\->proxy_authorization
+\& $mess\->authorization_basic
+\& $mess\->proxy_authorization_basic
+.Ve
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 1995\-2004 Gisle Aas.
+.PP
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
projects / catagits/Gitalist.git / blobdiff