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