The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Module-Generic-v0.27.1
River stage two • 15 direct dependents • 19 total dependents
2 ++
/ Module::Generic::HeaderValue

NAME

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

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 );

VERSION

    v0.4.1

DESCRIPTION

This is a class to parse and handle header values, such as in HTTP, PO file, WebSocket extension, or cookies in accordance with rfc2616

The object has stringification capability. For this see "as_string"

CONSTRUCTORS

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:

debug integer

See "debug" in Module::Generic

decode boolean
encode boolean
params hash reference
token_max integer
value_max integer

new_from_header

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

If "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 site_prefs with value lang=en-GB

It will set the value as an array reference that can be retrieved with "value" and as a string with "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 text/html: encoding=utf-8, the value will be a 1-element long array reference:

    ["text/html"]

Use "value_as_string", so you do not have to worry about this.

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

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

new_from_multi

Takes a header value that contains potentially multiple values separated by a proper comma and this returns an array object (Module::Generic::Array) of 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 =, ;, , or the end of string.

Possible options are:

decode

Takes a boolean value. Defaults to false.

If true, this will decode the values.

encode

Takes a boolean value. Defaults to false.

If true, this will encode the values.

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

separator

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

token_max

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

METHODS

as_string

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

If "encode" is set and there is a token value, then this will be url escaped.

An attribute value set to 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

decode

Boolean. If set to true, "new_from_header" will uri-unescape the token value, if any. For example a header value of site_prefs=lang%3Den-GB is made of a token site_prefs and a token value lang%3Den-GB, which once decoded will become lang=en-GB, but a header value of text/html has no token value and thus no decoding applies.

encode

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

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 );

param

Set or get an attribute and its value.

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

params

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

qstring

Provided with a string and this returns a quoted version, if necessary.

reset

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

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.

value

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

However, the value returned is always an array object 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 Content-Type: text/plain:

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

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

    my $cookie_name = $hv->value->first;
    my $cookie_val = $hv->value->last;

value_as_string

Returns a header value, without any possible attribute, as a string properly formatted and uri-escaped, if necessary.

value_data

This method returns the value part of a header field value. The need for distinction stems from some header field value, such as cookies, who have field value such as foo=bar where foo is the name and bar is the actual value.

This method ensures that, no matter the header field type, this returns the actual value, For example:

    my $hv = Module::Generic::HeaderValue->new_from_header( 'text/plain' );
    say $hv->value_data; # text/plain
    my $hv = Module::Generic::HeaderValue->new_from_header( 'foo=bar' );
    say $hv->value_data; # bar
    say $hv->value_name; # foo

value_max

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

A value of 0 means no limit.

value_name

This method returns the name part of the header field value. This is typically useful when dealing with cookies whose value is comprised of a cookie name and a cookie value. Thus with a cook with value foo=bar, this method would return foo.

See also "value_data"

SERIALISATION

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Module::Generic::Cookies, Text::PO. WebSocket::Extension

COPYRIGHT & LICENSE

Copyright(c) 2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.