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


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




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"



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


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:


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.


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:


Takes a boolean value. Defaults to false.

If true, this will decode the values.


Takes a boolean value. Defaults to false.

If true, this will encode the values.


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


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


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



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(
        decode => 1,
        encode => 1,
        params => { secure => undef }

would result in:

    site_prefs=lang%3Den-GB; secure


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.


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


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


Set or get an attribute and its value.

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


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


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


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


This will escape token value using hexadecimal equivalent if it contains delimiters as defined by rfc2616


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.


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;


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


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


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.


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


Jacques Deguest <>


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


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.