view release on metacpan or  search on metacpan

lib/Module/Generic/HeaderValue.pm  view on Meta::CPAN

=head1 NAME

Module::Generic::HeaderValue - Generic Header Value Parser

=head1 SYNOPSIS

    use Module::Generic::HeaderValue;
    my $hv = Module::Generic::HeaderValue->new( 'foo' ) || die( Module::Generic::HeaderValue->error, "\n" );
    my $hv = Module::Generic::HeaderValue->new( 'foo', bar => 2 ) || die( Module::Generic::HeaderValue->error, "\n" );
    print( "SomeHeader: $hv\n" );
    # will produce:
    SomeHeader: foo; bar=2
    my $cookie = "Set-Cookie: token=984.1635825594; Path=/; Expires=Thu, 01 Jan 1970 09:00:00 GMT"
    my $all = Module::Generic::HeaderValue->new_from_multi( $cookie );

=head1 VERSION

    v0.4.4

=head1 DESCRIPTION

This is a class to parse and handle header values, such as in HTTP, L<PO file|Text::PO>, L<WebSocket extension|WebSocket::Extension>, or L<cookies|Cookies> in accordance with L<rfc2616|https://datatracker.ietf.org/doc/html/rfc2616#section-4.2>

The object has stringification capability. For this see L</as_string>

=head1 CONSTRUCTORS

=head2 new

Takes a header value, and optionally an hash or hash reference of parameters and this returns the object.

Each parameter have a corresponding method, so please check their method documentation for details.

Supported parameters are:

=over 4

=item debug integer

See L<Module::Generic/debug>

=item decode boolean

=item encode boolean

=item params hash reference

=item token_max integer

=item value_max integer

=back

=head2 new_from_header

Takes a header value such as C<foo; bar=2> and and an hash or hash reference of options and this will parse it and return a new L<Module::Generic::HeaderValue> object.

If L</decode>, it will decode the value found, if any. For example:

    my $hv = Module::Generic::HeaderValue->new_from_header( "site_prefs=lang%3Den-GB" );

would become token C<site_prefs> with value C<lang=en-GB>

It will set the value as an array reference that can be retrieved with L</value> and as a string with L</value_as_string>

If the value is made of a token and a token value, such as in the example above, the array will be 2-elements long:

    ["site_prefs", "lang=en-GB"]

otherwise, such as in the example of C<text/html: encoding=utf-8>, the value will be a 1-element long array reference:

    ["text/html"]

Use L</value_as_string>, so you do not have to worry about this.

Each attribute token found such as C<encoding> in the example above, will be converted to lowercase before added in the C<params> hash reference that can be accessed with L</params>

You can control what acceptable attribute length and attribute's value length is by setting L</token_max> and L</value_max> respectively. If it is set to 0, then it will be understood as no length limit.

=head2 new_from_multi

Takes a header value that contains potentially multiple values separated by a proper comma and this returns an array object (L<Module::Generic::Array>) of L<Module::Generic::HeaderValue> objects.

    my $all = Module::Generic::HeaderValue->new_from_multi(
        q{site_prefs=lang%3Den-GB; Path=/; Expires=Monday, 01-Nov-2021 17:12:40 GMT; SameSite=Strict, csrf=9849724969dbcffd48c074b894c8fbda14610dc0ae62fac0f78b2aa091216e0b.1635825594; Path=/account; Secure}
    );

Note that the comma in this string is found to be a separator only when it is followed by some token itself followed by C<=>, C<;>, C<,> or the end of string.

Possible options are:

=over 4

=item C<decode>

Takes a boolean value. Defaults to false.

If true, this will decode the values.

=item C<encode>

Takes a boolean value. Defaults to false.

If true, this will encode the values.

=item C<params_only>

Takes a boolean value. Defaults to false.

If true, this will not assume the first part of the parameters passed is the main value.

This is the case for the header field Strict-Transport-Security

=item C<separator>

Takes a string, which defaults to C<;>. This is used as the separator between the parameters.

=item C<token_max>

Takes an integer. This is the maximum size of a token. Defaults to 0, i.e. no limit.

=back

=head1 METHODS

=head2 as_string

Returns the object as a string suitable to be added in an HTTP header.

If L</encode> is set and there is a token value, then this will be url escaped.

An attribute value set to C<undef> will result in the attribute alone:

    my $hv = Module::Generic::HeaderValue->new(
        "site_prefs=lang%3Den-GB",
        decode => 1,
        encode => 1,
        params => { secure => undef }
    );

would result in:

    site_prefs=lang%3Den-GB; secure

Optionally takes an array reference of parameter names to output first, followed by an optional hash or hash reference of options.

Supported options are:

=over 4

=item C<quote>

Boolean. Defaults to false.

If set to true, all parameter values will be wrapped in double quotes, regardless of whether quoting would otherwise be required. This is useful for headers such as C<Content-Disposition> in C<multipart/form-data> contexts, where L<RFC 7578|https://d...

    # Force quoting for all parameter values
    my $str = $hv->as_string( [qw( name filename )], { quote => 1 } );
    # produces: form-data; name="pause99_add_uri_httpupload"; filename="Module-Generic-v1.2.1.tar.gz"

=back

=head2 decode

Boolean. If set to true, L</new_from_header> will uri-unescape the token value, if any. For example a header value of C<site_prefs=lang%3Den-GB> is made of a token C<site_prefs> and a token value C<lang%3Den-GB>, which once decoded will become C<lang...

=head2 encode

Boolean. If set to true, then L</as_string> will encode the token value, if any. See above in L</decode>.

=head2 original

Cache value of the object stringified. It could also be set during object instantiation to provide the original header value.

    my $hv = Module::Generic::HeaderValue->new( 'foo', original => 'foo; bar=2' ) || 
        die( Module::Generic::HeaderValue->error );

=head2 param

Set or get an attribute and its value.

    $hv->param( encoding => 'utf-8' );
    $hv->param( secure => undef );

=head2 params

Set or get an hash object (L<Module::Generic::Hash>) of parameters.

=head2 qstring

Provided with a string, this returns a quoted version if necessary (e.g., if the string contains delimiters). Returns the quoted string, or C<undef> with an error if the string contains invalid characters:

    my $quoted = $hv->qstring( "Mon, 01 Nov 2021" );
    print $quoted; # "Mon, 01 Nov 2021"

=head2 reset

Remove the cached version of the stringification, i.e. set the object property C<original> to an empty string.

=head2 token_escape

Provided with a string, this will escape token value using hexadecimal equivalent if it contains delimiters as defined by L<rfc2616|https://datatracker.ietf.org/doc/html/rfc2616#section-2.2>

It returns the escaped string:

    my $escaped = $hv->token_escape( "foo/bar" );
    print $escaped; # "foo%2Fbar"

=head2 token_max

Integer. Default to 0. Set or get the maximum length of a token. which applies to an attribute.

A value of 0 means no limit.

=head2 value

Set or get the main header value. For example, in the case of C<foo; bar=2>, the main value here is C<foo>.

However, the value returned is always an L<array object|Module::Generic::Array> because some value could itself be a name-value pairs, like in the case of cookies, so to get the actual value, you would do:

If this is a regular field-value definition, such as C<Content-Type: text/plain>:

    my $val = $hv->value->first;

But if this is a value of type C<name-value> like with cookies, to get the value, you would do instead: