.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mojo::Message 3pm"
.TH Mojo::Message 3pm "2019-02-05" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojo::Message \- HTTP message base class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  package Mojo::Message::MyMessage;
\&  use Mojo::Base \*(AqMojo::Message\*(Aq;
\&
\&  sub cookies              {...}
\&  sub extract_start_line   {...}
\&  sub get_start_line_chunk {...}
\&  sub start_line_size      {...}
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojo::Message is an abstract base class for \s-1HTTP\s0 message containers, based on
\&\s-1RFC 7230\s0 <http://tools.ietf.org/html/rfc7230>,
\&\s-1RFC 7231\s0 <http://tools.ietf.org/html/rfc7231> and
\&\s-1RFC 2388\s0 <http://tools.ietf.org/html/rfc2388>, like Mojo::Message::Request
and Mojo::Message::Response.
.SH "EVENTS"
.IX Header "EVENTS"
Mojo::Message inherits all events from Mojo::EventEmitter and can emit
the following new ones.
.SS "finish"
.IX Subsection "finish"
.Vb 4
\&  $msg\->on(finish => sub {
\&    my $msg = shift;
\&    ...
\&  });
.Ve
.PP
Emitted after message building or parsing is finished.
.PP
.Vb 5
\&  my $before = time;
\&  $msg\->on(finish => sub {
\&    my $msg = shift;
\&    $msg\->headers\->header(\*(AqX\-Parser\-Time\*(Aq => time \- $before);
\&  });
.Ve
.SS "progress"
.IX Subsection "progress"
.Vb 4
\&  $msg\->on(progress => sub {
\&    my $msg = shift;
\&    ...
\&  });
.Ve
.PP
Emitted when message building or parsing makes progress.
.PP
.Vb 5
\&  # Building
\&  $msg\->on(progress => sub {
\&    my ($msg, $state, $offset) = @_;
\&    say qq{Building "$state" at offset $offset};
\&  });
\&
\&  # Parsing
\&  $msg\->on(progress => sub {
\&    my $msg = shift;
\&    return unless my $len = $msg\->headers\->content_length;
\&    my $size = $msg\->content\->progress;
\&    say \*(AqProgress: \*(Aq, $size == $len ? 100 : int($size / ($len / 100)), \*(Aq%\*(Aq;
\&  });
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Mojo::Message implements the following attributes.
.SS "content"
.IX Subsection "content"
.Vb 2
\&  my $msg = $msg\->content;
\&  $msg    = $msg\->content(Mojo::Content::Single\->new);
.Ve
.PP
Message content, defaults to a Mojo::Content::Single object.
.SS "default_charset"
.IX Subsection "default_charset"
.Vb 2
\&  my $charset = $msg\->default_charset;
\&  $msg        = $msg\->default_charset(\*(AqUTF\-8\*(Aq);
.Ve
.PP
Default charset used by \*(L"text\*(R" and to extract data from
\&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR or \f(CW\*(C`multipart/form\-data\*(C'\fR message body,
defaults to \f(CW\*(C`UTF\-8\*(C'\fR.
.SS "max_line_size"
.IX Subsection "max_line_size"
.Vb 2
\&  my $size = $msg\->max_line_size;
\&  $msg     = $msg\->max_line_size(1024);
.Ve
.PP
Maximum start-line size in bytes, defaults to the value of the
\&\f(CW\*(C`MOJO_MAX_LINE_SIZE\*(C'\fR environment variable or \f(CW8192\fR (8KiB).
.SS "max_message_size"
.IX Subsection "max_message_size"
.Vb 2
\&  my $size = $msg\->max_message_size;
\&  $msg     = $msg\->max_message_size(1024);
.Ve
.PP
Maximum message size in bytes, defaults to the value of the
\&\f(CW\*(C`MOJO_MAX_MESSAGE_SIZE\*(C'\fR environment variable or \f(CW16777216\fR (16MiB). Setting
the value to \f(CW0\fR will allow messages of indefinite size.
.SS "version"
.IX Subsection "version"
.Vb 2
\&  my $version = $msg\->version;
\&  $msg        = $msg\->version(\*(Aq1.1\*(Aq);
.Ve
.PP
\&\s-1HTTP\s0 version of message, defaults to \f(CW1.1\fR.
.SH "METHODS"
.IX Header "METHODS"
Mojo::Message inherits all methods from Mojo::EventEmitter and implements
the following new ones.
.SS "body"
.IX Subsection "body"
.Vb 2
\&  my $bytes = $msg\->body;
\&  $msg      = $msg\->body(\*(AqHello!\*(Aq);
.Ve
.PP
Slurp or replace \*(L"content\*(R".
.SS "body_params"
.IX Subsection "body_params"
.Vb 1
\&  my $params = $msg\->body_params;
.Ve
.PP
\&\f(CW\*(C`POST\*(C'\fR parameters extracted from \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR or
\&\f(CW\*(C`multipart/form\-data\*(C'\fR message body, usually a Mojo::Parameters object. Note
that this method caches all data, so it should not be called before the entire
message body has been received. Parts of the message body need to be loaded
into memory to parse \f(CW\*(C`POST\*(C'\fR parameters, so you have to make sure it is not
excessively large. There's a 16MiB limit for requests and a 2GiB limit for
responses by default.
.PP
.Vb 2
\&  # Get POST parameter names and values
\&  my $hash = $msg\->body_params\->to_hash;
.Ve
.SS "body_size"
.IX Subsection "body_size"
.Vb 1
\&  my $size = $msg\->body_size;
.Ve
.PP
Content size in bytes.
.SS "build_body"
.IX Subsection "build_body"
.Vb 1
\&  my $bytes = $msg\->build_body;
.Ve
.PP
Render whole body with \*(L"get_body_chunk\*(R".
.SS "build_headers"
.IX Subsection "build_headers"
.Vb 1
\&  my $bytes = $msg\->build_headers;
.Ve
.PP
Render all headers with \*(L"get_header_chunk\*(R".
.SS "build_start_line"
.IX Subsection "build_start_line"
.Vb 1
\&  my $bytes = $msg\->build_start_line;
.Ve
.PP
Render start-line with \*(L"get_start_line_chunk\*(R".
.SS "cookie"
.IX Subsection "cookie"
.Vb 1
\&  my $cookie = $msg\->cookie(\*(Aqfoo\*(Aq);
.Ve
.PP
Access message cookies, usually Mojo::Cookie::Request or
Mojo::Cookie::Response objects. If there are multiple cookies sharing the
same name, and you want to access more than just the last one, you can use
\&\*(L"every_cookie\*(R". Note that this method caches all data, so it should not be
called before all headers have been received.
.PP
.Vb 2
\&  # Get cookie value
\&  say $msg\->cookie(\*(Aqfoo\*(Aq)\->value;
.Ve
.SS "cookies"
.IX Subsection "cookies"
.Vb 1
\&  my $cookies = $msg\->cookies;
.Ve
.PP
Access message cookies. Meant to be overloaded in a subclass.
.SS "dom"
.IX Subsection "dom"
.Vb 2
\&  my $dom        = $msg\->dom;
\&  my $collection = $msg\->dom(\*(Aqa[href]\*(Aq);
.Ve
.PP
Retrieve message body from \*(L"text\*(R" and turn it into a Mojo::DOM object,
an optional selector can be used to call the method \*(L"find\*(R" in Mojo::DOM on it
right away, which then returns a Mojo::Collection object. Note that this
method caches all data, so it should not be called before the entire message
body has been received. The whole message body needs to be loaded into memory
to parse it, so you have to make sure it is not excessively large. There's a
16MiB limit for requests and a 2GiB limit for responses by default.
.PP
.Vb 2
\&  # Perform "find" right away
\&  say $msg\->dom(\*(Aqh1, h2, h3\*(Aq)\->map(\*(Aqtext\*(Aq)\->join("\en");
\&
\&  # Use everything else Mojo::DOM has to offer
\&  say $msg\->dom\->at(\*(Aqtitle\*(Aq)\->text;
\&  say $msg\->dom\->at(\*(Aqbody\*(Aq)\->children\->map(\*(Aqtag\*(Aq)\->uniq\->join("\en");
.Ve
.SS "error"
.IX Subsection "error"
.Vb 2
\&  my $err = $msg\->error;
\&  $msg    = $msg\->error({message => \*(AqParser error\*(Aq});
.Ve
.PP
Get or set message error, an \f(CW\*(C`undef\*(C'\fR return value indicates that there is no
error.
.PP
.Vb 2
\&  # Connection or parser error
\&  $msg\->error({message => \*(AqConnection refused\*(Aq});
\&
\&  # 4xx/5xx response
\&  $msg\->error({message => \*(AqInternal Server Error\*(Aq, code => 500});
.Ve
.SS "every_cookie"
.IX Subsection "every_cookie"
.Vb 1
\&  my $cookies = $msg\->every_cookie(\*(Aqfoo\*(Aq);
.Ve
.PP
Similar to \*(L"cookie\*(R", but returns all message cookies sharing the same name
as an array reference.
.PP
.Vb 2
\&  # Get first cookie value
\&  say $msg\->every_cookie(\*(Aqfoo\*(Aq)\->[0]\->value;
.Ve
.SS "every_upload"
.IX Subsection "every_upload"
.Vb 1
\&  my $uploads = $msg\->every_upload(\*(Aqfoo\*(Aq);
.Ve
.PP
Similar to \*(L"upload\*(R", but returns all file uploads sharing the same name as
an array reference.
.PP
.Vb 2
\&  # Get content of first uploaded file
\&  say $msg\->every_upload(\*(Aqfoo\*(Aq)\->[0]\->asset\->slurp;
.Ve
.SS "extract_start_line"
.IX Subsection "extract_start_line"
.Vb 1
\&  my $bool = $msg\->extract_start_line(\e$str);
.Ve
.PP
Extract start-line from string. Meant to be overloaded in a subclass.
.SS "finish"
.IX Subsection "finish"
.Vb 1
\&  $msg = $msg\->finish;
.Ve
.PP
Finish message parser/generator.
.SS "fix_headers"
.IX Subsection "fix_headers"
.Vb 1
\&  $msg = $msg\->fix_headers;
.Ve
.PP
Make sure message has all required headers.
.SS "get_body_chunk"
.IX Subsection "get_body_chunk"
.Vb 1
\&  my $bytes = $msg\->get_body_chunk($offset);
.Ve
.PP
Get a chunk of body data starting from a specific position. Note that it might
not be possible to get the same chunk twice if content was generated
dynamically.
.SS "get_header_chunk"
.IX Subsection "get_header_chunk"
.Vb 1
\&  my $bytes = $msg\->get_header_chunk($offset);
.Ve
.PP
Get a chunk of header data, starting from a specific position. Note that this
method finalizes the message.
.SS "get_start_line_chunk"
.IX Subsection "get_start_line_chunk"
.Vb 1
\&  my $bytes = $msg\->get_start_line_chunk($offset);
.Ve
.PP
Get a chunk of start-line data starting from a specific position. Meant to be
overloaded in a subclass.
.SS "header_size"
.IX Subsection "header_size"
.Vb 1
\&  my $size = $msg\->header_size;
.Ve
.PP
Size of headers in bytes. Note that this method finalizes the message.
.SS "headers"
.IX Subsection "headers"
.Vb 1
\&  my $headers = $msg\->headers;
.Ve
.PP
Message headers, usually a Mojo::Headers object.
.PP
.Vb 2
\&  # Longer version
\&  my $headers = $msg\->content\->headers;
.Ve
.SS "is_finished"
.IX Subsection "is_finished"
.Vb 1
\&  my $bool = $msg\->is_finished;
.Ve
.PP
Check if message parser/generator is finished.
.SS "is_limit_exceeded"
.IX Subsection "is_limit_exceeded"
.Vb 1
\&  my $bool = $msg\->is_limit_exceeded;
.Ve
.PP
Check if message has exceeded \*(L"max_line_size\*(R", \*(L"max_message_size\*(R",
\&\*(L"max_buffer_size\*(R" in Mojo::Content or \*(L"max_line_size\*(R" in Mojo::Headers.
.SS "json"
.IX Subsection "json"
.Vb 2
\&  my $value = $msg\->json;
\&  my $value = $msg\->json(\*(Aq/foo/bar\*(Aq);
.Ve
.PP
Decode \s-1JSON\s0 message body directly using Mojo::JSON if possible, an \f(CW\*(C`undef\*(C'\fR
return value indicates a bare \f(CW\*(C`null\*(C'\fR or that decoding failed. An optional \s-1JSON\s0
Pointer can be used to extract a specific value with Mojo::JSON::Pointer.
Note that this method caches all data, so it should not be called before the
entire message body has been received. The whole message body needs to be
loaded into memory to parse it, so you have to make sure it is not excessively
large. There's a 16MiB limit for requests and a 2GiB limit for responses by
default.
.PP
.Vb 3
\&  # Extract JSON values
\&  say $msg\->json\->{foo}{bar}[23];
\&  say $msg\->json(\*(Aq/foo/bar/23\*(Aq);
.Ve
.SS "parse"
.IX Subsection "parse"
.Vb 1
\&  $msg = $msg\->parse(\*(AqHTTP/1.1 200 OK...\*(Aq);
.Ve
.PP
Parse message chunk.
.SS "save_to"
.IX Subsection "save_to"
.Vb 1
\&  $msg = $msg\->save_to(\*(Aq/some/path/index.html\*(Aq);
.Ve
.PP
Save message body to a file.
.SS "start_line_size"
.IX Subsection "start_line_size"
.Vb 1
\&  my $size = $msg\->start_line_size;
.Ve
.PP
Size of the start-line in bytes. Meant to be overloaded in a subclass.
.SS "text"
.IX Subsection "text"
.Vb 1
\&  my $str = $msg\->text;
.Ve
.PP
Retrieve \*(L"body\*(R" and try to decode it with \*(L"charset\*(R" in Mojo::Content or
\&\*(L"default_charset\*(R".
.SS "to_string"
.IX Subsection "to_string"
.Vb 1
\&  my $str = $msg\->to_string;
.Ve
.PP
Render whole message. Note that this method finalizes the message, and that it
might not be possible to render the same message twice if content was generated
dynamically.
.SS "upload"
.IX Subsection "upload"
.Vb 1
\&  my $upload = $msg\->upload(\*(Aqfoo\*(Aq);
.Ve
.PP
Access \f(CW\*(C`multipart/form\-data\*(C'\fR file uploads, usually Mojo::Upload objects. If
there are multiple uploads sharing the same name, and you want to access more
than just the last one, you can use \*(L"every_upload\*(R". Note that this method
caches all data, so it should not be called before the entire message body has
been received.
.PP
.Vb 2
\&  # Get content of uploaded file
\&  say $msg\->upload(\*(Aqfoo\*(Aq)\->asset\->slurp;
.Ve
.SS "uploads"
.IX Subsection "uploads"
.Vb 1
\&  my $uploads = $msg\->uploads;
.Ve
.PP
All \f(CW\*(C`multipart/form\-data\*(C'\fR file uploads, usually Mojo::Upload objects.
.PP
.Vb 2
\&  # Names of all uploads
\&  say $_\->name for @{$msg\->uploads};
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.