Skip to content

Commit

Permalink
Merge pull request #1913 from karenetheridge/ether/header-docs
Browse files Browse the repository at this point in the history 
separate header shortcuts from other accessors
  • Loading branch information
@mergify
mergify[bot] committed Sep 20, 2023
2 parents 2c8d1b6 + fab6ab9 commit d11b23e
Showing 1 changed file with 120 additions and 115 deletions.
235 changes: 120 additions & 115 deletions lib/Mojo/Headers.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,126 @@ Maximum number of header lines, defaults to the value of the C<MOJO_MAX_LINES> e
L<Mojo::Headers> inherits all methods from L<Mojo::Base> and implements the following new ones.
=head2 add
$headers = $headers->add(Foo => 'one value');
$headers = $headers->add(Foo => 'first value', 'second value');
Add header with one or more lines.
# "Vary: Accept
# Vary: Accept-Encoding"
$headers->add(Vary => 'Accept')->add(Vary => 'Accept-Encoding')->to_string;
=head2 append
$headers = $headers->append(Vary => 'Accept-Encoding');
Append value to header and flatten it if necessary.
# "Vary: Accept"
$headers->append(Vary => 'Accept')->to_string;
# "Vary: Accept, Accept-Encoding"
$headers->vary('Accept')->append(Vary => 'Accept-Encoding')->to_string;
=head2 clone
my $clone = $headers->clone;
Return a new L<Mojo::Headers> object cloned from these headers.
=head2 dehop
$headers = $headers->dehop;
Remove hop-by-hop headers that should not be retransmitted.
=head2 every_header
my $all = $headers->every_header('Location');
Similar to L</"header">, but returns all headers sharing the same name as an array reference.
# Get first header value
say $headers->every_header('Location')->[0];
=head2 from_hash
$headers = $headers->from_hash({'Cookie' => 'a=b'});
$headers = $headers->from_hash({'Cookie' => ['a=b', 'c=d']});
$headers = $headers->from_hash({});
Parse headers from a hash reference, an empty hash removes all headers.
=head2 header
my $value = $headers->header('Foo');
$headers = $headers->header(Foo => 'one value');
$headers = $headers->header(Foo => 'first value', 'second value');
Get or replace the current header values.
=head2 is_finished
my $bool = $headers->is_finished;
Check if header parser is finished.
=head2 is_limit_exceeded
my $bool = $headers->is_limit_exceeded;
Check if headers have exceeded L</"max_line_size"> or L</"max_lines">.
=head2 leftovers
my $bytes = $headers->leftovers;
Get and remove leftover data from header parser.
=head2 names
my $names = $headers->names;
Return an array reference with all currently defined headers.
# Names of all headers
say for @{$headers->names};
=head2 parse
$headers = $headers->parse("Content-Type: text/plain\x0d\x0a\x0d\x0a");
Parse formatted headers.
=head2 remove
$headers = $headers->remove('Foo');
Remove a header.
=head2 to_hash
my $single = $headers->to_hash;
my $multi = $headers->to_hash(1);
Turn headers into hash reference, array references to represent multiple headers with the same name are disabled by
default.
say $headers->to_hash->{DNT};
=head2 to_string
my $str = $headers->to_string;
Turn headers into a string, suitable for HTTP messages.
=head1 ADDITIONAL METHODS
Additionally, the following shortcuts are available, for accessing and manipulating commonly-used headers:
=head2 accept
my $accept = $headers->accept;
Expand Down Expand Up @@ -279,36 +399,13 @@ Get or replace current header value, shortcut for the C<Accept-Ranges> header.
Get or replace current header value, shortcut for the C<Access-Control-Allow-Origin> header from L<Cross-Origin
Resource Sharing|https://www.w3.org/TR/cors/>.
=head2 add
$headers = $headers->add(Foo => 'one value');
$headers = $headers->add(Foo => 'first value', 'second value');
Add header with one or more lines.
# "Vary: Accept
# Vary: Accept-Encoding"
$headers->add(Vary => 'Accept')->add(Vary => 'Accept-Encoding')->to_string;
=head2 allow
my $allow = $headers->allow;
$headers = $headers->allow('GET, POST');
Get or replace current header value, shortcut for the C<Allow> header.
=head2 append
$headers = $headers->append(Vary => 'Accept-Encoding');
Append value to header and flatten it if necessary.
# "Vary: Accept"
$headers->append(Vary => 'Accept')->to_string;
# "Vary: Accept, Accept-Encoding"
$headers->vary('Accept')->append(Vary => 'Accept-Encoding')->to_string;
=head2 authorization
my $authorization = $headers->authorization;
Expand All @@ -323,12 +420,6 @@ Get or replace current header value, shortcut for the C<Authorization> header.
Get or replace current header value, shortcut for the C<Cache-Control> header.
=head2 clone
my $clone = $headers->clone;
Return a new L<Mojo::Headers> object cloned from these headers.
=head2 connection
my $connection = $headers->connection;
Expand Down Expand Up @@ -408,12 +499,6 @@ Get or replace current header value, shortcut for the C<Cookie> header from L<RF
Get or replace current header value, shortcut for the C<Date> header.
=head2 dehop
$headers = $headers->dehop;
Remove hop-by-hop headers that should not be retransmitted.
=head2 dnt
my $dnt = $headers->dnt;
Expand All @@ -429,15 +514,6 @@ is very commonly used.
Get or replace current header value, shortcut for the C<ETag> header.
=head2 every_header
my $all = $headers->every_header('Location');
Similar to L</"header">, but returns all headers sharing the same name as an array reference.
# Get first header value
say $headers->every_header('Location')->[0];
=head2 expect
my $expect = $headers->expect;
Expand All @@ -452,22 +528,6 @@ Get or replace current header value, shortcut for the C<Expect> header.
Get or replace current header value, shortcut for the C<Expires> header.
=head2 from_hash
$headers = $headers->from_hash({'Cookie' => 'a=b'});
$headers = $headers->from_hash({'Cookie' => ['a=b', 'c=d']});
$headers = $headers->from_hash({});
Parse headers from a hash reference, an empty hash removes all headers.
=head2 header
my $value = $headers->header('Foo');
$headers = $headers->header(Foo => 'one value');
$headers = $headers->header(Foo => 'first value', 'second value');
Get or replace the current header values.
=head2 host
my $host = $headers->host;
Expand All @@ -489,31 +549,13 @@ Get or replace current header value, shortcut for the C<If-Modified-Since> heade
Get or replace current header value, shortcut for the C<If-None-Match> header.
=head2 is_finished
my $bool = $headers->is_finished;
Check if header parser is finished.
=head2 is_limit_exceeded
my $bool = $headers->is_limit_exceeded;
Check if headers have exceeded L</"max_line_size"> or L</"max_lines">.
=head2 last_modified
my $date = $headers->last_modified;
$headers = $headers->last_modified('Sun, 17 Aug 2008 16:27:35 GMT');
Get or replace current header value, shortcut for the C<Last-Modified> header.
=head2 leftovers
my $bytes = $headers->leftovers;
Get and remove leftover data from header parser.
=head2 link
my $link = $headers->link;
Expand All @@ -540,15 +582,6 @@ Get or set web links from or to C<Link> header according to L<RFC 5988|http://to
Get or replace current header value, shortcut for the C<Location> header.
=head2 names
my $names = $headers->names;
Return an array reference with all currently defined headers.
# Names of all headers
say for @{$headers->names};
=head2 origin
my $origin = $headers->origin;
Expand All @@ -557,12 +590,6 @@ Return an array reference with all currently defined headers.
Get or replace current header value, shortcut for the C<Origin> header from L<RFC
6454|https://tools.ietf.org/html/rfc6454>.
=head2 parse
$headers = $headers->parse("Content-Type: text/plain\x0d\x0a\x0d\x0a");
Parse formatted headers.
=head2 proxy_authenticate
my $authenticate = $headers->proxy_authenticate;
Expand Down Expand Up @@ -599,12 +626,6 @@ Alias for L</"referrer">.
Get or replace current header value, shortcut for the C<Referer> header, there was a typo in L<RFC
2068|https://tools.ietf.org/html/rfc2068> which resulted in C<Referer> becoming an official header.
=head2 remove
$headers = $headers->remove('Foo');
Remove a header.
=head2 sec_websocket_accept
my $accept = $headers->sec_websocket_accept;
Expand Down Expand Up @@ -691,22 +712,6 @@ Get or replace current header value, shortcut for the C<Strict-Transport-Securit
Get or replace current header value, shortcut for the C<TE> header.
=head2 to_hash
my $single = $headers->to_hash;
my $multi = $headers->to_hash(1);
Turn headers into hash reference, array references to represent multiple headers with the same name are disabled by
default.
say $headers->to_hash->{DNT};
=head2 to_string
my $str = $headers->to_string;
Turn headers into a string, suitable for HTTP messages.
=head2 trailer
my $trailer = $headers->trailer;
Expand Down

0 comments on commit d11b23e

Please sign in to comment.