NAME¶
Data::Munge - various utility functions
SYNOPSIS¶
use Data::Munge;
my $re = list2re qw/foo bar baz/;
print byval { s/foo/bar/ } $text;
foo(mapval { chomp } @lines);
print replace('Apples are round, and apples are juicy.', qr/apples/i, 'oranges', 'g');
print replace('John Smith', qr/(\w+)\s+(\w+)/, '$2, $1');
my $trimmed = trim " a b c "; # "a b c"
my $x = 'bar';
if (elem $x, [qw(foo bar baz)]) { ... }
eval_string('print "hello world\\n"'); # says hello
eval_string('die'); # dies
eval_string('{'); # throws a syntax error
my $fac = rec {
my ($rec, $n) = @_;
$n < 2 ? 1 : $n * $rec->($n - 1)
};
print $fac->(5); # 120
DESCRIPTION¶
This module defines a few generally useful utility functions. I got tired of
redefining or working around them, so I wrote this module.
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;
- 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.
- 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:
- $$
- Inserts a '$'.
- $&
- Inserts the matched substring.
- $`
- Inserts the substring preceding the match.
- $'
- Inserts the substring following the match.
- $N (where N is a digit)
- Inserts the substring matched by the Nth capturing group.
- ${N} (where N is one or more digits)
- Inserts the substring matched by the Nth capturing group.
Note that these aren't variables; they're character sequences interpreted by
"replace".
If REPLACEMENT is a subroutine reference, it's called with the following
arguments: First the matched substring (like $& above), then the contents
of the capture buffers (as returned by "submatches"), then the
offset where the pattern matched (like "$-[0]", see "@-"
in perlvar), then the STRING. The return value will be inserted in place of
the matched substring.
Normally only the first occurrence of REGEX is replaced. If FLAG is present, it
must be 'g' and causes all occurrences to be replaced.
- 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.
- 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.
AUTHOR¶
Lukas Mai, "<l.mai at web.de>"
COPYRIGHT & LICENSE¶
Copyright 2009-2011, 2013-2014 Lukas Mai.
This program is free software; you can redistribute it and/or modify it under
the terms of either: the GNU General Public License as published by the Free
Software Foundation; or the Artistic License.
See
http://dev.perl.org/licenses/ for more information.