Functions

list2re LIST

Converts a list of strings to a regex that matches any of the strings. Especially useful in combination with "keys". Example:

 my $re = list2re keys %hash;
 $str =~ s/($re)/$hash{$1}/g;
    

This function takes special care to get several edge cases right:

byval BLOCK SCALAR

Takes a code block and a value, runs the block with $_ set to that value, and returns the final value of $_. The global value of $_ is not affected. $_ isn't aliased to the input value either, so modifying $_ in the block will not affect the passed in value. Example:

 foo(byval { s/!/?/g } $str);
 # Calls foo() with the value of $str, but all '!' have been replaced by '?'.
 # $str itself is not modified.
    

Since perl 5.14 you can also use the "/r" flag:

 foo($str =~ s/!/?/gr);
    

But "byval" works on all versions of perl and is not limited to "s///".

mapval BLOCK LIST

Works like a combination of "map" and "byval"; i.e. it behaves like "map", but $_ is a copy, not aliased to the current element, and the return value is taken from $_ again (it ignores the value returned by the block). Example:

 my @foo = mapval { chomp } @bar;
 # @foo contains a copy of @bar where all elements have been chomp'd.
 # This could also be written as chomp(my @foo = @bar); but that's not
 # always possible.
    

submatches

Returns a list of the strings captured by the last successful pattern match. Normally you don't need this function because this is exactly what "m//" returns in list context. However, "submatches" also works in other contexts such as the RHS of "s//.../e".

replace STRING, REGEX, REPLACEMENT, FLAG

replace STRING, REGEX, REPLACEMENT

A clone of javascript's "String.prototype.replace". It works almost the same as "byval { s/REGEX/REPLACEMENT/FLAG } STRING", but with a few important differences. REGEX can be a string or a compiled "qr//" object. REPLACEMENT can be a string or a subroutine reference. If it's a string, it can contain the following replacement patterns:

trim STRING

Returns STRING with all leading and trailing whitespace removed. Like "length" it returns "undef" if the input is "undef".

elem SCALAR, ARRAYREF

Returns a boolean value telling you whether SCALAR is an element of ARRAYREF or not. Two scalars are considered equal if they're both "undef", if they're both references to the same thing, or if they're both not references and "eq" to each other.

This is implemented as a linear search through ARRAYREF that terminates early if a match is found (i.e. "elem 'A', ['A', 1 .. 9999]" won't even look at elements "1 .. 9999").

eval_string STRING

Evals STRING just like "eval" but doesn't catch exceptions. Caveat: Unlike with "eval" the code runs in an empty lexical scope:

 my $foo = "Hello, world!\n";
 eval_string 'print $foo';
 # Dies: Global symbol "$foo" requires explicit package name
    

That is, the eval'd code can't see variables from the scope of the "eval_string" call.

slurp FILEHANDLE

Reads and returns all remaining data from FILEHANDLE as a string, or "undef" if it hits end-of-file. (Interaction with non-blocking filehandles is currently not well defined.)

"slurp $handle" is equivalent to "do { local $/; scalar readline $handle }".

rec BLOCK

Creates an anonymous sub as "sub BLOCK" would, but supplies the called sub with an extra argument that can be used to recurse:

 my $code = rec {
   my ($rec, $n) = @_;
   $rec->($n - 1) if $n > 0;
   print $n, "\n";
 };
 $code->(4);
    

That is, when the sub is called, an implicit first argument is passed in $_[0] (all normal arguments are moved one up). This first argument is a reference to the sub itself. This reference could be used to recurse directly or to register the sub as a handler in an event system, for example.

A note on defining recursive anonymous functions: Doing this right is more complicated than it may at first appear. The most straightforward solution using a lexical variable and a closure leaks memory because it creates a reference cycle. Starting with perl 5.16 there is a "__SUB__" constant that is equivalent to $rec above, and this is indeed what this module uses (if available).

However, this module works even on older perls by falling back to either weak references (if available) or a "fake recursion" scheme that dynamically instantiates a new sub for each call instead of creating a cycle. This last resort is slower than weak references but works everywhere.