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.1.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 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.

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.

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_as_string

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

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.

cpanm Module::Generic

perl -MCPAN -e shell
install Module::Generic