1Data::Munge(3)        User Contributed Perl Documentation       Data::Munge(3)
2
3
4

NAME

6       Data::Munge - various utility functions
7

SYNOPSIS

9        use Data::Munge;
10
11        my $re = list2re qw/f ba foo bar baz/;
12        # $re = qr/bar|baz|foo|ba|f/;
13
14        print byval { s/foo/bar/ } $text;
15        # print do { my $tmp = $text; $tmp =~ s/foo/bar/; $tmp };
16
17        foo(mapval { chomp } @lines);
18        # foo(map { my $tmp = $_; chomp $tmp; $tmp } @lines);
19
20        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
25        my $trimmed = trim "  a b c "; # "a b c"
26
27        my $x = 'bar';
28        if (elem $x, [qw(foo bar baz)]) { ... }
29
30        my $contents = slurp $fh;  # or: slurp *STDIN
31
32        eval_string('print "hello world\\n"');  # says hello
33        eval_string('die');  # dies
34        eval_string('{');    # throws a syntax error
35
36        my $fac = rec {
37          my ($rec, $n) = @_;
38          $n < 2 ? 1 : $n * $rec->($n - 1)
39        };
40        print $fac->(5);  # 120
41
42        if ("hello, world!" =~ /(\w+), (\w+)/) {
43          my @captured = submatches;
44          # @captured = ("hello", "world")
45        }
46

DESCRIPTION

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
51   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
56            my $re = list2re keys %hash;
57            $str =~ s/($re)/$hash{$1}/g;
58
59           This function takes special care to get several edge cases right:
60
61           •   Empty list: An empty argument list results in a regex that
62               doesn't match anything.
63
64           •   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
68           •   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
74       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
81            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
85           Since perl 5.14 you can also use the "/r" flag:
86
87            foo($str =~ s/!/?/gr);
88
89           But "byval" works on all versions of perl and is not limited to
90           "s///".
91
92       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
98            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
103       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
110       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
119           $$  Inserts a '$'.
120
121           $&  Inserts the matched substring.
122
123           $`  Inserts the substring preceding the match.
124
125           $'  Inserts the substring following the match.
126
127           $N  (where N is a digit)
128               Inserts the substring matched by the Nth capturing group.
129
130           ${N}  (where N is one or more digits)
131               Inserts the substring matched by the Nth capturing group.
132
133           Note that these aren't variables; they're character sequences
134           interpreted by "replace".
135
136           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
143           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
146       trim STRING
147           Returns STRING with all leading and trailing whitespace removed.
148           Like "length" it returns "undef" if the input is "undef".
149
150       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
156           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
160       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
164            my $foo = "Hello, world!\n";
165            eval_string 'print $foo';
166            # Dies: Global symbol "$foo" requires explicit package name
167
168           That is, the eval'd code can't see variables from the scope of the
169           "eval_string" call.
170
171       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
176           "slurp $handle" is equivalent to "do { local $/; scalar readline
177           $handle }".
178
179       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
183            my $code = rec {
184              my ($rec, $n) = @_;
185              $rec->($n - 1) if $n > 0;
186              print $n, "\n";
187            };
188            $code->(4);
189
190           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
196           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
203           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

AUTHOR

210       Lukas Mai, "<l.mai at web.de>"
211
213       Copyright 2009-2011, 2013-2015 Lukas Mai.
214
215       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
219       See http://dev.perl.org/licenses/ for more information.
220
221
222
223perl v5.34.0                      2022-01-21                    Data::Munge(3)
Impressum