Module:...erValue(3)

🌸 NAME 🌸

Module::Generic::HeaderValue — Generic Header Value Parser. This is the Module:...erValue(3) page, bestie, and it's literally all about parsing and handling header values like a total pro 💅✨

---

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

---

🦋 DESCRIPTION 🦋

Okay so this is a class that parses and handles header values — think HTTP, PO files, WebSocket extensions, or cookies — in accordance with rfc2616 at https://datatracker.ietf.org/doc/html/rfc2616#section-4.2 🌈

The object has stringification capability. For that, go look at "as_string" 👑

---

🧸 CONSTRUCTORS 🧸

💖 new

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

Each parameter has a corresponding method, so bestie, check their method documentation for the 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 a 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. Iconic, honestly.

Each attribute token found such as encoding in the example above will be converted to lowercase before being 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. Periodt.

🦋 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. That's the vibe check for commas 😌

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 an 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. No cap.

🎀 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 a hash object (Module::Generic::Hash) of parameters.

⭐ qstring

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

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

🔥 reset

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

💜 token_escape

Provided with a string, this will escape token value using hexadecimal equivalent if it contains delimiters as defined by rfc2616 at 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"

🌈 token_max

Integer. Defaults 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 pair, 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 the header field (e.g., bar in foo=bar). The need for distinction stems from some header field values, such as cookies, which have field values such as foo=bar where foo is the name and bar is the actual value. It returns an empty string if no value part exists.

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. Defaults 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 (e.g., foo in foo=bar). This is typically useful when dealing with cookies whose value is comprised of a cookie name and a cookie value. Thus with a cookie whose value is foo=bar, this method would return foo. It returns an empty string if no name part exists:

my $hv = Module::Generic::HeaderValue->new_from_header( "foo=bar" );
print $hv->value_name; # "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" ✨

---

🛡️ THREAD-SAFETY 🛡️

Module::Generic::HeaderValue is thread-safe for all operations, as it operates on per-object state and uses thread-safe external libraries. We love a safe queen 💅

Key considerations for thread-safety:

• Shared Variables — There are no shared variables that are modified at runtime. Regular expressions (e.g., $TOKEN_REGEXP, $TEXT_REGEXP) are compile-time constants and immutable. The global $DEBUG variable (inherited from Module::Generic) is typically set before threads are created, and it is the user's responsibility to ensure thread-safety if modified at runtime:

use threads;
local $Module::Generic::HeaderValue::DEBUG = 0; # Set before threads
my @threads = map
{
    threads->create(sub
    {
        my $hv = Module::Generic::HeaderValue->new( "foo; bar=2" );
        $hv->as_string; # Thread-safe
    });
} 1..5;
$_->join for( @threads );

• Object State — Header data (e.g., "value", "params") is stored per-object, ensuring thread isolation:

use threads;
my @threads = map
{
    threads->create(sub
    {
        my $hv = Module::Generic::HeaderValue->new( "foo; bar=2" );
        $hv->param( tid => threads->tid ); # Thread-safe
    });
} 1..5;
$_->join for( @threads );

• External Libraries — Methods like "token_escape" and "value_as_string" use URI::Escape, which is thread-safe as it operates on local data.
• Serialisation — Serialisation methods ("FREEZE", "THAW") operate on per-object state, making them thread-safe.

For debugging in threaded environments:

ls -l /proc/$$/fd  # List open file descriptors

---

🌟 AUTHOR 🌟

Jacques Deguest <jack@deguest.jp>

---

💖 SEE ALSO 💖

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

🎀 COPYRIGHT & LICENSE 🎀

okay so legal bits, but make it cute — it's not scary, promise 🫶

Copyright(c) 2021-2024 DEGUEST Pte. Ltd.

periodt, that's the copyright line, copied exactly 💅

And here's the actual permission bit — you can use, copy, modify and redistribute this package and its associated files under the same terms as Perl itself ✨ So yeah, same deal as Perl, no special extra rules, no secret side quest. Go off, bestie 💖

ngl this is the part everyone skips, but it's literally the whole vibe check for what you're allowed to do with the code — so don't skip it 🙈

---

🌸 and that's the whole page, you made it to the end!! 🌸

source + version tea: this one's from perl v5.42.2, dated 2026-02-15, and it's the Module:...erValue(3) page — go forth and slay your modules, ily, bye 👑💜