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



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.


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.


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.


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


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.