1Data::Munge(3) User Contributed Perl Documentation Data::Munge(3)
2
6 Data::Munge - various utility functions
7
9 use Data::Munge;
10 my $re = list2re qw/f ba foo bar baz/;
12 # $re = qr/bar|baz|foo|ba|f/;
13 print byval { s/foo/bar/ } $text;
15 # print do { my $tmp = $text; $tmp =~ s/foo/bar/; $tmp };
16 foo(mapval { chomp } @lines);
18 # foo(map { my $tmp = $_; chomp $tmp; $tmp } @lines);
19 print replace('Apples are round, and apples are juicy.', qr/apples/i, 'oranges', 'g');
21 # "oranges are round, and oranges are juicy."
22 print replace('John Smith', qr/(\w+)\s+(\w+)/, '$2, $1');
23 # "Smith, John"
24 my $trimmed = trim " a b c "; # "a b c"
26 my $x = 'bar';
28 if (elem $x, [qw(foo bar baz)]) { ... }
29 my $contents = slurp $fh; # or: slurp *STDIN
31 eval_string('print "hello world\\n"'); # says hello
33 eval_string('die'); # dies
34 eval_string('{'); # throws a syntax error
35 my $fac = rec {
37 my ($rec, $n) = @_;
38 $n < 2 ? 1 : $n * $rec->($n - 1)
39 };
40 print $fac->(5); # 120
41 if ("hello, world!" =~ /(\w+), (\w+)/) {
43 my @captured = submatches;
44 # @captured = ("hello", "world")
45 }
46
48 This module defines a few generally useful utility functions. I got
49 tired of redefining or working around them, so I wrote this module.
50 Functions
52 list2re LIST
53 Converts a list of strings to a regex that matches any of the
54 strings. Especially useful in combination with "keys". Example:
55 my $re = list2re keys %hash;
57 $str =~ s/($re)/$hash{$1}/g;
58 This function takes special care to get several edge cases right:
60 • Empty list: An empty argument list results in a regex that
62 doesn't match anything.
63 • Empty string: An argument list consisting of a single empty
65 string results in a regex that matches the empty string (and
66 nothing else).
67 • Prefixes: The input strings are sorted by descending length to
69 ensure longer matches are tried before shorter matches.
70 Otherwise "list2re('ab', 'abcd')" would generate "qr/ab|abcd/",
71 which (on its own) can never match "abcd" (because "ab" is
72 tried first, and it always succeeds where "abcd" could).
73 byval BLOCK SCALAR
75 Takes a code block and a value, runs the block with $_ set to that
76 value, and returns the final value of $_. The global value of $_ is
77 not affected. $_ isn't aliased to the input value either, so
78 modifying $_ in the block will not affect the passed in value.
79 Example:
80 foo(byval { s/!/?/g } $str);
82 # Calls foo() with the value of $str, but all '!' have been replaced by '?'.
83 # $str itself is not modified.
84 Since perl 5.14 you can also use the "/r" flag:
86 foo($str =~ s/!/?/gr);
88 But "byval" works on all versions of perl and is not limited to
90 "s///".
91 mapval BLOCK LIST
93 Works like a combination of "map" and "byval"; i.e. it behaves like
94 "map", but $_ is a copy, not aliased to the current element, and
95 the return value is taken from $_ again (it ignores the value
96 returned by the block). Example:
97 my @foo = mapval { chomp } @bar;
99 # @foo contains a copy of @bar where all elements have been chomp'd.
100 # This could also be written as chomp(my @foo = @bar); but that's not
101 # always possible.
102 submatches
104 Returns a list of the strings captured by the last successful
105 pattern match. Normally you don't need this function because this
106 is exactly what "m//" returns in list context. However,
107 "submatches" also works in other contexts such as the RHS of
108 "s//.../e".
109 replace STRING, REGEX, REPLACEMENT, FLAG
111 replace STRING, REGEX, REPLACEMENT
112 A clone of javascript's "String.prototype.replace". It works almost
113 the same as "byval { s/REGEX/REPLACEMENT/FLAG } STRING", but with a
114 few important differences. REGEX can be a string or a compiled
115 "qr//" object. REPLACEMENT can be a string or a subroutine
116 reference. If it's a string, it can contain the following
117 replacement patterns:
118 $$ Inserts a '$'.
120 $& Inserts the matched substring.
122 $` Inserts the substring preceding the match.
124 $' Inserts the substring following the match.
126 $N (where N is a digit)
128 Inserts the substring matched by the Nth capturing group.
129 ${N} (where N is one or more digits)
131 Inserts the substring matched by the Nth capturing group.
132 Note that these aren't variables; they're character sequences
134 interpreted by "replace".
135 If REPLACEMENT is a subroutine reference, it's called with the
137 following arguments: First the matched substring (like $& above),
138 then the contents of the capture buffers (as returned by
139 "submatches"), then the offset where the pattern matched (like
140 "$-[0]", see "@-" in perlvar), then the STRING. The return value
141 will be inserted in place of the matched substring.
142 Normally only the first occurrence of REGEX is replaced. If FLAG is
144 present, it must be 'g' and causes all occurrences to be replaced.
145 trim STRING
147 Returns STRING with all leading and trailing whitespace removed.
148 Like "length" it returns "undef" if the input is "undef".
149 elem SCALAR, ARRAYREF
151 Returns a boolean value telling you whether SCALAR is an element of
152 ARRAYREF or not. Two scalars are considered equal if they're both
153 "undef", if they're both references to the same thing, or if
154 they're both not references and "eq" to each other.
155 This is implemented as a linear search through ARRAYREF that
157 terminates early if a match is found (i.e. "elem 'A', ['A', 1 ..
158 9999]" won't even look at elements "1 .. 9999").
159 eval_string STRING
161 Evals STRING just like "eval" but doesn't catch exceptions. Caveat:
162 Unlike with "eval" the code runs in an empty lexical scope:
163 my $foo = "Hello, world!\n";
165 eval_string 'print $foo';
166 # Dies: Global symbol "$foo" requires explicit package name
167 That is, the eval'd code can't see variables from the scope of the
169 "eval_string" call.
170 slurp FILEHANDLE
172 Reads and returns all remaining data from FILEHANDLE as a string,
173 or "undef" if it hits end-of-file. (Interaction with non-blocking
174 filehandles is currently not well defined.)
175 "slurp $handle" is equivalent to "do { local $/; scalar readline
177 $handle }".
178 rec BLOCK
180 Creates an anonymous sub as "sub BLOCK" would, but supplies the
181 called sub with an extra argument that can be used to recurse:
182 my $code = rec {
184 my ($rec, $n) = @_;
185 $rec->($n - 1) if $n > 0;
186 print $n, "\n";
187 };
188 $code->(4);
189 That is, when the sub is called, an implicit first argument is
191 passed in $_[0] (all normal arguments are moved one up). This first
192 argument is a reference to the sub itself. This reference could be
193 used to recurse directly or to register the sub as a handler in an
194 event system, for example.
195 A note on defining recursive anonymous functions: Doing this right
197 is more complicated than it may at first appear. The most
198 straightforward solution using a lexical variable and a closure
199 leaks memory because it creates a reference cycle. Starting with
200 perl 5.16 there is a "__SUB__" constant that is equivalent to $rec
201 above, and this is indeed what this module uses (if available).
202 However, this module works even on older perls by falling back to
204 either weak references (if available) or a "fake recursion" scheme
205 that dynamically instantiates a new sub for each call instead of
206 creating a cycle. This last resort is slower than weak references
207 but works everywhere.
208
210 Lukas Mai, "<l.mai at web.de>"
211
213 Copyright 2009-2011, 2013-2015 Lukas Mai.
214 This program is free software; you can redistribute it and/or modify it
216 under the terms of either: the GNU General Public License as published
217 by the Free Software Foundation; or the Artistic License.
218 See http://dev.perl.org/licenses/ for more information.
220perl v5.34.0 2022-01-21 Data::Munge(3)