Module:...::Scalar(3)

📦 version 1.1.3, in alpine 3.24

💖 Module::Generic::Scalar — String Manipulation Object Class 💖

okay bestie so this is a User Contributed Perl Documentation page, section 3, and it's literally the glow-up your plain strings have been begging for. no cap. 🌸

✨ SYNOPSIS ✨

like, here's the whole vibe at a glance, fr fr:

    my $s = Module::Generic::Scalar->new( "John Doe" );
    print( $s->substr( 0, 4 ), "\n" );
    # prints: John
    $s->append( 'more data' );
    # $a is now a Module::Generic::Array object
    my $a = $s->as_array;
    # $bool is now a Module::Generic::Boolean object
    # with value is true or false depending on underlying value of $s
    my $bool = $s->as_boolean;
    # $a is now a Module::Generic::Number object
    my $n = $s->as_number
    # raw string
    my $str = $s->as_string;
    print( "Hello $s\n" );
    # Hello John Doe

    my $str = Module::Generic::Scalar->new();
    $a->callback( add => sub
    {
        my( $new ) = @_;
        return unless( $$new eq $approved_string );
        return(1);
    });
    $str->append( $some_string );
    # or
    $str .= $some_string;

    $s->capitalise;
    $s->chomp;
    $s->chop;
    $s->clone;
    my $crypted = $s->crypt( $salt );
    $s->defined;
    $s->empty;
    $s->fc( $that );
    my $hex = $s->hex;
    my $index = $s->index;
    $s->is_alpha;
    $s->is_alpha_numeric;
    $s->is_empty;
    $s->is_lower;
    $s->is_numeric;
    $s->is_upper;

    my $s = Module::Generic::Scalar->new( 'Jack John Paul Peter' );
    # Takes the string, split it by space (now an array), join it by comma (now a scalar) and rejoin it with more strings
    say $s->split( qr/[[:blank:]]+/ )->join( ', ' )->join( ', ', qw( Gabriel Raphael Emmanuel ) );
    # prints: Jack, John, Paul, Peter, Gabriel, Raphael, Emmanuel

    $s->lc;
    $s->lcfirst;
    $s->left;
    $s->length;
    my $s = Module::Generic::Scalar->new( "I disapprove of what you say, but I will defend to the death your right to say it" );
    print( "Matches? ", $s->like( qr/\bapprove[[:blank:]\h]+what\b/ ) ? 'yes' : 'no', "\n" ); # print yes
    if( $s->like( qr/[[:blank:]\h]+/ ) )
    {
        # Do something
    }
    # or
    if( my $rv = $s->like( qr/([[:blank:]\h]+)/ )->result )
    {
        my $first_match = $rv->capture->first;
        # Do something
    }

    $s->lower;
    $s->ltrim;
    # Remove all kind of leading whitespaces
    $s->ltrim( qr/[[:blank:]\h]+/ );

    # $s is "Hello world"
    $s->match( 'world' ); # pass
    $s->match( qr/WORLD/i ); # pass
    $s->match( 'monde' ); # obviously fail
    if( $s->match( qr/[[:blank:]\h]+/ ) )
    {
        # Do something
    }
    if( my $rv = $s->match( qr/([[:blank:]\h]+)/ )->result )
    {
        my $first_match = $rv->capture->first;
        # Do something
    }

    my $unpack = $unpack_data->unpack( "A10xA28xA8A*" )->object;
    my $fh = $s->open;
    $fh->print;
    $fh->read;
    $s->ord;
    $s->pack;
    $s->pad( 3, 'X' );
    # XXXHello world

    $s->padd( -3, 'X' );
    # Hello worldXXX
    $s->pos;
    $s->$s->prepend( join( '', qw( Cogito ergo sum ) ) );
    $s->quotemeta;

    # $s is Hello world
    my $rv = $s->replace( ' ', '_' ); # Hello_world
    my $rv = $s->replace( qr/[[:blank:]\h]+/, '_' ); # Hello_world
    if( my $rv = $s->replace( qr/([[:blank:]\h]+)/, '_' )->result )
    {
        my $first_match = $rv->capture->first;
        # Do something
    }
    $s->reset;
    $s->reverse;
    Module::Generic::Scalar->new( "Hello world" )->right( 5 );
    # will produce: world
    $s->rindex;
    # Remove all kind of trailing whitespaces
    $s->rtrim( qr/[[:blank:]\h]+/ );
    $s->scalar;
    $s->set;
    # Returns a Module::Generic::Array object
    my $a = $s->split( /\n/ );
    my $a = $s->split( qr/\n/ );
    $s->sprintf;
    $s->substr;
    $s->tr;
    $s->trim;
    $s->uc;
    $s->ucfirst;
    print( $s->defined ? 'defined' : 'undefined', "\n" );

    my $array = $s->unpack( "W" );
    # Returns the ord() value as a Module::Generic::Array object
    $s->unpack( "W" )->length;
    # Object context. Ditto
    my( $date, $desc, $income, $expend ) = $s->unpack( "A10xA27xA7A*" );
    # Returns a regular list of values
    $s->upper;

🎀 VERSION 🎀

v1.4.3 — that's the one, bestie. 💅

🦋 DESCRIPTION 🦋

so the whole point of this class/package is to give you an object-oriented way to mess with strings. it's giving "strings but make it a whole person." ✨

the object is overloaded, which means when you use it as a string, it just hands back the embedded string. iconic behaviour honestly:

    print( "I met with $s\n" );

and that would produce: I met with John Doe

🌈 METHODS 🌈

💜 `new`

you hand it a scalar reference, an array, or just a regular plain string, and it gives you back a shiny new object. 🫶

if you pass it an array reference or an array-based object like Module::Generic::Array, it will concatenate all the array elements together. slay.

💜 `append`

give it a string and it adds that string to the end of your string object. no drama.

    # $s is 'Hello'
    $s->append( ' world' );
    # now this is: Hello world

💜 `as_array`

returns the current string value as an Module::Generic::Array object. 🧚

💜 `as_boolean`

returns a Module::Generic::Boolean object, with its value set to true or false depending on the value of the scalar object. vibe check time:

    # $s is 1
    $s->as_boolean; # sets to true
    # $s is 0
    $s->as_boolean; # sets to false
    # $s is hello
    $s->as_boolean: # sets to true
    # $s is undefined or empty
    $s->as_boolean: # sets to false
    # etc...

Module::Generic::Boolean objects are genuinely so useful, bestie — in perl they act like 0 or 1 to show false or true, but when you use them in json, they get automatically converted into "false" or "true". like, multilingual queen. 👑

💜 `as_number`

returns the current string as an Module::Generic::Number object. 🔢

💜 `as_string`

returns the object string as a, you guessed it, string. 💖

    my $s = Module::Generic::Scalar->new( "Mary Jane" );
    print( "Hello $s\n" );
    # Hello Mary Jane

💜 `callback`

sets or gets a callback on the scalar object. you can set 2 types of callback: "add" or "remove", and they get called respectively when you add something to the scalar, or when you remove something from it. 🎀

how does it even do that? it ties the scalar to its internal class Module::Generic::Scalar::Tie, which will call the "add" or "remove" callback whenever data is being added or removed — no matter how, i.e. whether it's through the methods of this class, or by you just directly trying to add data to it:

    my $str = Module::Generic::Scalar->new();
    $a->callback( add => sub
    {
        my( $new ) = @_;
        return unless( $$new eq $approved_string );
        return(1);
    });
    $str->append( $some_string );
    # or
    $str .= $some_string;

in both cases above the string will be added — and if it were some other unapproved text, the data would not get added to the string. gatekeeping, but make it responsible. 🙈

so the callback must return true to allow the data to be added, or undef to refuse. and heads up: returning an empty string or 0 will not work as a rejection, even though those are false values. yes, really. 💀

both the "add" and "remove" callbacks receive an hash reference as their sole argument.

the "add" callback receives an hash reference with these properties:

added — a scalar reference to the new value being set in replacement of the old one, so you can inspect it. 🔍
removed — a scalar reference to the old value being replaced, so you can inspect it.
type — the callback type: "add"

the "remove" callback works exactly the same way, but for any operation that tries to remove data from the string. it receives an hash reference with these properties:

removed
type — the callback type: "remove"

    my $str = Module::Generic::Scalar->new();
    $str->callback( remove => sub
    {
        my( $old, $new ) = @_;
        # Do some check to accept or reject
        return(1); # always return true to accept
    });
    $str->substr( 3, 4, $some_other_text ); # Attempt to change the string

this example above would call the callback passing it the old and new string. 🫶

to replace a callback, just add another one — it'll replace the previous one. easy.

you can get the callback code associated with a callback by calling "callback" with one argument: the callback type.

    my $code_ref = $str->callback( 'add' );

to remove a callback, pass undef:

    $str->callback( add => undef );
    $str->callback( remove => undef );

by default, a scalar object is not tied to Module::Generic::Scalar::Tie and no callbacks are set nor used. be mindful when using callbacks, since it will slow things down a little bit — even though it's a very thin layer. 😭

see perltie for more info on tieing data.

🧵 THREAD SAFETY 🧵

the "callback" method installs internal hooks that are triggered on scalar value mutation (e.g., when a new value is assigned). these callbacks are enabled by tying the scalar to an internal package (not part of the public API). 🔥

while this design is fully safe in single-threaded use, note the following if you're working in a multi-threaded environment:

Callbacks may be triggered by assignments to the scalar value — e.g., $$scalar = "new value".
If the scalar object is accessed by multiple threads, and a callback mutates shared state, this may lead to race conditions unless external locking is applied. ⚠️
It is recommended that each scalar object be thread-local, or that the callback logic be thread-safe.

the internal tied object is not exposed, and should not be accessed directly. don't do it bestie, i'm serious. 💀

💜 `capitalise`

returns a new Module::Generic::Scalar object representing the string with the words capitalised — done in a smart way. meaning the special words like "and", "but", "if", "on", "or", "the", "to", etc. are not capitalised. taste! 👑

this is based on the work done by John Gruber and Aristotle Pagaltzis https://gist.github.com/gruber/9f9e8650d68b13ce4d78

💜 `chomp`

just like "chomp" in perlfunc, this removes the trailing new lines in the string object, if any. 🍓

and per the perl documentation for "chomp" in perlfunc: "it returns the total number of characters removed from all its arguments."

💜 `chop`

just like "chop" in perlfunc, this removes the trailing character in the string object, no matter what it is, and returns the character chopped. savage but fair. ✂️

💜 `clone`

returns a copy of the object. 🦋

💜 `crypt`

this takes a "salt" and returns an encrypted version of the string. see "crypt" in perlfunc. ⚠️ note that this does not work well on some BSD systems.

`defined` 💖

Okay so this one is a vibe check: it returns true or false whether the string object contains a defined string, i.e. not undef.

`empty` 🫶

Alias for reset. This empties the scalar object, making it zero-byte in length. Iconic little reset button energy.

`error` 😭

Provided with an error message string, or a hash of parameters, and this will instantiate a new exception object and return undef, or return a Module::Generic::Null object in object context, such as when it is chained.

See error in Module::Generic for more information. No cap, that’s the whole tea.

`fc` 🦋

Just like fc in perlfunc, provided with a string, this enables comparison with casefolding.

To quote from the manual: “Casefolding is the process of mapping strings to a form where case differences are erased”.

lc($this) eq lc($that)    # Wrong!
# or
uc($this) eq uc($that)    # Also wrong!
# or
$this =~ /^\Q$that\E\z/i  # Right!
# And now
my $s = Module::Generic::Scalar( $this );
$s->fc( $that );

`hex` ✨

Returns the hex value of the string. Cute, concise, does exactly what it says.

`index` 🔍

Given a sub string and an optional position, and this returns the position at which the sub string was found, as a Module::Generic::Number object.

See index in perlfunc.

`is_alpha` 💅

Returns true if the string contains only alphabetic characters, or else it returns false.

This uses perl’s [[:alpha:]] to test.

`is_alpha_numeric` 🎀

Returns true if the string contains only alphabetic or numeric characters, or else it returns false.

This uses perl’s [[:alnum:]] to test.

`is_empty` 🫧

Returns true if the string is zero in length, or else it returns false.

`is_lower` 🌸

Returns true if the string contains only lower case characters, or else it returns false.

This uses perl’s [[:lower:]] to test.

`is_numeric` 🔢

Returns true if the string contains only numeric characters, or else it returns false.

This uses looks_like_number in Scalar::Util.

`is_upper` 👑

Returns true if the string contains only upper case characters, or else it returns false.

This uses perl’s [[:upper:]] to test.

`join` 🧚

Takes a string as the delimiter and one or more elements and this will join the current string object and the other string elements provided using the string delimiter. For example:

my $s = Module::Generic::Scalar->new( 'Jack John Paul Peter' );
# Takes the string, split it by space (now an array), join it by comma (now a scalar) and rejoin it with more strings
say $s->split( qr/[[:blank:]]+/ )->join( ', ' )->join( ', ', qw( Gabriel Raphael Emmanuel ) );
# prints: Jack, John, Paul, Peter, Gabriel, Raphael, Emmanuel

Note that if, among the element passed to join, an array object is provided, it will not be expanded. Thus, if you do something like this:

my $a = Module::Generic::Array->new( [qw( John Peter )] );
say Module::Generic::Scalar->new( 'Paul' )->join( ', ', $a );

It will not produce Paul, John, Peter, but instead something like: Paul, Module::Generic::Array=ARRAY(0x5646f0116470).

That’s because there is no way to guess if the user wanted to pass on a list or just an object and making that kind of assumption is dangerous.

What you would want to do instead is:

say Module::Generic::Scalar->new( 'Paul' )->join( ', ', $a->list );

Or maybe

say Module::Generic::Scalar->new( 'Paul' )->join( ', ', @$a );

Of course, passing an overloaded object that has the stringification capability will transform it automatically into a string before being joined. Thus:

my $word1 = Module::Generic::Scalar->new( 'Hello' );
my $word2 = Module::Generic::Scalar->new( 'world' );
say $word1->join( ' ', $word2 );

will yield: Hello world because Module::Generic::Scalar objects have overloaded stringification capability.

It returns the newly formed string as a new Module::Generic::Scalar object. Slay.

`lc` 🌈

Takes the current string object and returns a new Module::Generic::Scalar object with the string all in lower case.

`lcfirst` 🍓

Takes the current string object and returns a new Module::Generic::Scalar object with the first character of the string in lower case.

`left` ⬅️

Provided with a number and this will get the chunk starting from the left of the string object.

Module::Generic::Scalar->new( "Hello world" )->left( 5 );
# will produce: Hello

`length` 📏

This returns the length of the string, as a Module::Generic::Number object.

`like` 💜

Provided with a string or a regular expression and this returns the value of the regular expression evaluation against the object string.

my $s = "I disapprove of what you say, but I will defend to the death your right to say it";
print( "Matches? ", $s->like( qr/\bapprove[[:blank:]\h]+what\b/ ) ? 'yes' : 'no', "\n" ); # print yes

If there is no match, it returns 0, but in object, list or scalar context or when there are matches, it returns a Module::Generic::RegexpCapture object. This object stringifies into the number of matches, so you can do:

if( $s->like( qr/[[:blank:]\h]+/ ) )
{
    # Do something
}

if( my $rv = $s->like( qr/([[:blank:]\h]+)/ )->result )
{
    my $first_match = $rv->capture->first;
    # Do something
}

Regular expression can also be one from Regexp::Common.

`lower` 🌸

Alias for lc. Same lowercase fantasy, different label.

`ltrim` 🧼

This removes any new line and space characters, i.e. "\r" and "\n" at the beginning of the string.

It takes an optional argument that can be an alternative string to remove at the end of the sstring or a regular expression, such as one provided with perlfunc/qr.

$s->ltrim( qr/[[:blank:]\h]+/ ); # Remove all kind of leading whitespaces

It returns the object itself for chaining.

Regular expression can also be one from Regexp::Common.

`match` 🔥

Provided with a string or a regular expression like the one created with qr in perlfunc and this returns true or false whether the string object matched or not.

# $s is "Hello world"
$s->match( 'world' ); # pass
$s->match( qr/WORLD/i ); # pass
$s->match( 'monde' ); # obviously fail

if( $s->match( qr/[[:blank:]\h]+/ ) )
{
    # Do something
}

if( my $rv = $s->match( qr/([[:blank:]\h]+)/ )->result )
{
    my $first_match = $rv->capture->first;
    # Do something
}

Regular expression can also be one from Regexp::Common.

`object` 🪞

Returns the current object. This is useful when chaining to force an object context. For example, with unpack. In scalar context, unpack, as per the unpack in perlfunc documentation will return the first element:

my $unpack = $unpack_data->unpack( "A10xA28xA8A*" );

But what if we wanted $unpack to not be the first element, but the array object? For that, we would need to call unpack in object context:

my $unpack = $unpack_data->unpack( "A10xA28xA8A*" )->object;

Main character energy: force the object context.

`open` 🚪

Opens the scalar in read/write mode and returns an object with same capabilities as regular file handle.

`ord` 🔡

This returns the value of ord in perlfunc on the string, as a Module::Generic::Number object.

`pack` 🎁

Like pack in perlfunc, this takes a template and convert the string object. “The resulting string is the concatenation of the converted values.”

It returns a new Module::Generic::Scalar object.

See also pack in Module::Generic::Array.

`pad` 🧸

Provided with a number n and a string and this will create n instance of the string. If the number is positive, the string will be placed at the beginning and if negative, it will be placed at the end.

$s->pad( 3, 'X' );
# XXXHello world

$s->padd( -3, 'X' );
# Hello worldXXX

`pass_error` 💀

If provided with an error object, this will set it in this package and pass it along to the caller.

If no error object is provided, this will merely return undef, or an Module::Generic::Null object in object context, such as when it is chained.

See pass_error in Module::Generic for more information.

`pos` 📍

This sets or gets the position inside the string object. See pos in perlfunc for detail about this.

`prepend` 🫶

Takes some data as its unique argument and prepend it to the scalar object underlying value.

If you want to pass multiple data, you will have to join them first:

$s->prepend( join( '', qw( Cogito ergo sum ) ) );

`quotemeta` 🛡️

Given a string, this returns a new Module::Generic::Scalar object with the given string characters escaped with quotemeta in perlfunc.

`replace` 🔁

Provided with a string or a regular expression and a replacement string and this will replace all instance of the string or regular expression with the replacement string provided.

# $s is Hello world
my $rv = $s->replace( ' ', '_' ); # Hello_world
my $rv = $s->replace( qr/[[:blank:]\h]+/, '_' ); # Hello_world

if( $s->replace( qr/[[:blank:]\h]+/, '_' ) )
{
    # Do something
}

if( my $rv = $s->replace( qr/([[:blank:]\h]+)/, '_' )->result )
{
    my $first_match = $rv->capture->first;
    # Do something
}

Regular expression can also be one from Regexp::Common.

`reset` ♻️

This empty the string inside the object.

`reverse` 🔄

Given a string, this returns a new Module::Generic::Scalar object with the given string in reverse order.

`right` ➡️

Provided with a number and this will get the chunk starting from the right of the string object.

Module::Generic::Scalar->new( "Hello world" )->right( 5 );
# will produce: world

`rindex` 🔎

Given a sub string and an optional position, and this returns the position at which the sub string was found, starting from the end.

See rindex in perlfunc.

`rtrim` 🌸

This removes any new line and space characters, i.e. "\r" and "\n" at the end of the string.

It takes an optional argument that can be an alternative string to remove at the end of the sstring or a regular expression, such as one provided with perlfunc/qr.

$s->rtrim( qr/[[:blank:]\h]+/ ); # Remove all kind of trailing whitespaces

It returns the object itself for chaining. Chain goes on, periodt.

Regular expression can also be one from Regexp::Common 💖

scalar 🧮

Returns the string chillin’ inside this scalar object. It calls as_string.

set 🎀

Hand it a scalar reference or a scalar-based object like Module::Generic::Scalar, or an array reference, and it sets the current string.

It acts the exact same way as for new, except it acts on the current object string. Periodt.

split ✂️

Give it a string or an expression, and it returns the list in list context or, in scalar context, an array reference as a Module::Generic::Array object.

Be careful that you cannot just do like perl’s original split such as:

my $a = $s->split( /\n/ );

Because /\n/ is not passed as an argument, i.e. it results in no argument being passed, so you do need to either provide the expression as "\n" or as a regular expression:

my $a = $s->split( qr/\n/ );

It will warn you if no argument was provided.

Regular expression can also be one from Regexp::Common.

sprintf 🧁

Provided with a list of arguments, and this replaces the placeholders just like sprintf in perlfunc does.

substr 🪄

Provided with an offset, an optional length and an optional replacement string, and this modifies in-place the current object string and returns a new Module::Generic::Scalar object of the string segment thus altered or removed or replaced.

See substr in perlfunc for more information.

$s = 'I disapprove of what you say, but I will defend to the death your right to say it'; # Evelyn Hall, "Friends of Voltaire"
$s->substr( 2, 13 );
# returns a new object containing 'disapprove of'
$s->substr( 2, 13, 'really do not approve' );
# returns a new object containing 'disapprove of' and the current object now contains:
# 'I really do not approve what you say, but I will defend to the death your right to say it'

tr 🔁

Provided with a search list and a replacement list and this will perform just like the perl core tr in perlfunc function.

It also accepts options like cdsr and returns the resulting value.

THREAD SAFETY AND SECURITY WARNING ⚠️

The tr method uses eval to dynamically apply a transliteration pattern:

$$self =~ tr/$search/$replace/$opts/;

This can be considered safe as long as the $search and $replace values come from a trusted source. However, if untrusted user input is passed to these arguments, it could result in a malformed or dangerous regular expression being compiled at runtime.

To ensure safety:

Only use static or validated content in $search and $replace
Avoid using this method inside threads with shared objects unless the object is guarded externally

trim 🧼

Provided with a target string or a regular expression, and this will remove any occurrence of them in the string object.

uc 🔠

Takes the current string object and returns a new Module::Generic::Scalar object with the string all in upper case.

ucfirst 🌟

Takes the current string object and returns a new Module::Generic::Scalar object with the first character of the string in upper case.

undef 🫥

Sets the underlying string object to undef.

This would make

print( $s->defined ? 'defined' : 'undefined', "\n" );

return false, but be careful that you cannot do:

print( $s ? 'defined' : 'undefined', "\n" );

Because $s is the object so it would always return true.

If you stringify it like

print( "$s" ? 'defined' : 'undefined', "\n" );

It would still return as defined, because this would be a defined string, albeit empty.

unpack 📦

my $array = $s->unpack( "W" );
# Returns the ord() value as a Module::Generic::Array object
$s->unpack( "W" )->length;
# Object context. Ditto
my( $date, $desc, $income, $expend ) = $s->unpack( "A10xA27xA7A*" );
# Returns a regular list of values

Does the reverse of pack. Provided with a template, it takes the string object and expands it out into a list of values.

It returns an Module::Generic::Array object in object or scalar context, and a regular list in list context.

upper ⬆️

Alias for uc.

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 🧵

This module is designed to be fully thread-safe and process-safe, ensuring data integrity across Perl ithreads and mod_perl’s threaded Multi-Processing Modules (MPMs) such as Worker or Event. It relies on Module::Generic::Global for thread-safe storage of shared state and employs synchronisation mechanisms to prevent data corruption and race conditions.

Synchronisation Mechanisms 🔒

Shared State

The module uses Module::Generic::Global to manage shared state in two namespaces:

"errors": Stores error objects for "error" and "pass_error", keyed by object reference address, process ID, and thread ID (if applicable).
"loaded_classes": Tracks loaded classes in "_load_class", keyed by class name and thread ID (if applicable).

These repositories are ":shared" when "CAN_THREADS" is true (Perl supports ithreads), protected by "lock" in perlfunc for Perl threads or APR::ThreadRWLock for mod_perl threaded MPMs without threads. In non-threaded environments, repositories are per-process, requiring no synchronisation.

Tied Scalars

When callbacks are set via "callback", the scalar is tied to "Module::Generic::Scalar::Tie". As of version 1.4.3, tied scalar operations (e.g., "STORE", "FETCH") are thread-safe, as they rely on Module::Generic::Global’s synchronisation. However, callbacks themselves are not inherently thread-safe. If a callback accesses shared resources or performs complex operations, you must implement additional synchronisation (e.g., using "lock" in perlfunc or Thread::Semaphore).

Context Key Isolation 🔑

Module::Generic::Global uses context keys to isolate data:

Object-Level Keys

Methods like "error", "pass_error", and "DESTROY" use object-level keys ("<refaddr>;<pid>[;<tid>]"), where "refaddr" is the object’s reference address, "pid" is the process ID, and "tid" is the thread ID (if "HAS_THREADS" is true). This ensures thread- and process-specific isolation for errors.

Class-Level Keys

"_load_class" uses class-level keys ("<class>[;<tid>]"), isolating loaded class tracking per thread or process.

Keys differ between threaded ("<refaddr>;<pid>;<tid>") and non-threaded ("<refaddr>;<pid>") environments, preventing cross-context interference.

Error Handling 😭

Errors are stored in the "errors" namespace, with one error per object-process-thread combination. The package-global $ERROR is retained for backward compatibility but is not cleared in "DESTROY" to avoid affecting other objects. Errors are serialised using Storable::Improved for thread compatibility.

mod_perl Considerations 🐪

Prefork MPM

Data is per-process, requiring no additional synchronisation.

Threaded MPMs (Worker/Event)

Shared repositories are protected by Module::Generic::Global’s synchronisation. Users should call "Module::Generic::Global-"cleanup_register> in mod_perl handlers to clear repositories after requests, preventing memory leaks.

Thread-Unsafe Functions

Avoid Perl functions like "localtime", "readdir", "srand", or operations like "chdir", "umask", "chroot" in threaded MPMs, as they may affect all threads. Consult perlthrtut at http://perldoc.perl.org/perlthrtut.html and mod_perl documentation at https://perl.apache.org/docs/2.0/user/coding/coding.html#Thread_environment_Issues for details.

Recommendations for Threaded Applications 💡

Use non-tied scalars without additional synchronisation, as Module::Generic::Global handles shared state.
For tied scalars, ensure callbacks are thread-safe by adding locks for shared resources.
In mod_perl, use "cleanup_register" to manage memory.

AUTHOR ✍️

Jacques Deguest jack@deguest.jp

COPYRIGHT & LICENSE 📜

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

That’s the whole page, bestie — rendered by perl v5.42.2 on 2026-02-15 for Module:...::Scalar(3). 💅✨

📦 where this page comes from

alpine 3.24: perl-module-generic-doc 1.1.3-r1 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

Module:...::Scalar(3)

💖 Module::Generic::Scalar — String Manipulation Object Class 💖

✨ SYNOPSIS ✨

🎀 VERSION 🎀

🦋 DESCRIPTION 🦋

🌈 METHODS 🌈

💜 new

💜 append

💜 as_array

💜 as_boolean

💜 as_number

💜 as_string

💜 callback

🧵 THREAD SAFETY 🧵

💜 capitalise

💜 chomp

💜 chop

💜 clone

💜 crypt

defined 💖

empty 🫶

error 😭

fc 🦋

hex ✨

index 🔍

is_alpha 💅

is_alpha_numeric 🎀

is_empty 🫧

is_lower 🌸

is_numeric 🔢

is_upper 👑

join 🧚

lc 🌈

lcfirst 🍓

left ⬅️

length 📏

like 💜

lower 🌸

ltrim 🧼

match 🔥

object 🪞

open 🚪

ord 🔡

pack 🎁

pad 🧸

pass_error 💀

pos 📍

prepend 🫶

quotemeta 🛡️

replace 🔁

reset ♻️

reverse 🔄

right ➡️

rindex 🔎

rtrim 🌸

scalar 🧮

set 🎀

split ✂️

sprintf 🧁

substr 🪄

tr 🔁

THREAD SAFETY AND SECURITY WARNING ⚠️

trim 🧼

uc 🔠

ucfirst 🌟

undef 🫥

unpack 📦

upper ⬆️

SERIALISATION 🧚

THREAD-SAFETY 🧵

Synchronisation Mechanisms 🔒

Context Key Isolation 🔑

Error Handling 😭

mod_perl Considerations 🐪

Recommendations for Threaded Applications 💡

SEE ALSO 👀

AUTHOR ✍️

COPYRIGHT & LICENSE 📜

💜 `new`

💜 `append`

💜 `as_array`

💜 `as_boolean`

💜 `as_number`

💜 `as_string`

💜 `callback`

💜 `capitalise`

💜 `chomp`

💜 `chop`

💜 `clone`

💜 `crypt`

`defined` 💖

`empty` 🫶

`error` 😭

`fc` 🦋

`hex` ✨

`index` 🔍

`is_alpha` 💅

`is_alpha_numeric` 🎀

`is_empty` 🫧

`is_lower` 🌸

`is_numeric` 🔢

`is_upper` 👑

`join` 🧚

`lc` 🌈

`lcfirst` 🍓

`left` ⬅️

`length` 📏

`like` 💜

`lower` 🌸

`ltrim` 🧼

`match` 🔥

`object` 🪞

`open` 🚪

`ord` 🔡

`pack` 🎁

`pad` 🧸

`pass_error` 💀

`pos` 📍

`prepend` 🫶

`quotemeta` 🛡️

`replace` 🔁

`reset` ♻️

`reverse` 🔄

`right` ➡️

`rindex` 🔎

`rtrim` 🌸