Mojo::Util(3pm)

1Mojo::Util(3)         User Contributed Perl Documentation        Mojo::Util(3)
2
3
4

NAME

6       Mojo::Util - Portable utility functions
7

SYNOPSIS

9         use Mojo::Util qw(b64_encode url_escape url_unescape);
10
11         my $str = 'test=23';
12         my $escaped = url_escape $str;
13         say url_unescape $escaped;
14         say b64_encode $escaped, '';
15

DESCRIPTION

17       Mojo::Util provides portable utility functions for Mojo.
18

FUNCTIONS

20       Mojo::Util implements the following functions, which can be imported
21       individually.
22
23   b64_decode
24         my $bytes = b64_decode $b64;
25
26       Base64 decode bytes with MIME::Base64.
27
28   b64_encode
29         my $b64 = b64_encode $bytes;
30         my $b64 = b64_encode $bytes, "\n";
31
32       Base64 encode bytes with MIME::Base64, the line ending defaults to a
33       newline.
34
35   camelize
36         my $camelcase = camelize $snakecase;
37
38       Convert "snake_case" string to "CamelCase" and replace "-" with "::".
39
40         # "FooBar"
41         camelize 'foo_bar';
42
43         # "FooBar::Baz"
44         camelize 'foo_bar-baz';
45
46         # "FooBar::Baz"
47         camelize 'FooBar::Baz';
48
49   class_to_file
50         my $file = class_to_file 'Foo::Bar';
51
52       Convert a class name to a file.
53
54         # "foo_bar"
55         class_to_file 'Foo::Bar';
56
57         # "foobar"
58         class_to_file 'FOO::Bar';
59
60         # "foo_bar"
61         class_to_file 'FooBar';
62
63         # "foobar"
64         class_to_file 'FOOBar';
65
66   class_to_path
67         my $path = class_to_path 'Foo::Bar';
68
69       Convert class name to path, as used by %INC.
70
71         # "Foo/Bar.pm"
72         class_to_path 'Foo::Bar';
73
74         # "FooBar.pm"
75         class_to_path 'FooBar';
76
77   decamelize
78         my $snakecase = decamelize $camelcase;
79
80       Convert "CamelCase" string to "snake_case" and replace "::" with "-".
81
82         # "foo_bar"
83         decamelize 'FooBar';
84
85         # "foo_bar-baz"
86         decamelize 'FooBar::Baz';
87
88         # "foo_bar-baz"
89         decamelize 'foo_bar-baz';
90
91   decode
92         my $chars = decode 'UTF-8', $bytes;
93
94       Decode bytes to characters with Encode, or return "undef" if decoding
95       failed.
96
97   deprecated
98         deprecated 'foo is DEPRECATED in favor of bar';
99
100       Warn about deprecated feature from perspective of caller. You can also
101       set the "MOJO_FATAL_DEPRECATIONS" environment variable to make them die
102       instead with Carp.
103
104   dumper
105         my $perl = dumper {some => 'data'};
106
107       Dump a Perl data structure with Data::Dumper.
108
109   encode
110         my $bytes = encode 'UTF-8', $chars;
111
112       Encode characters to bytes with Encode.
113
114   extract_usage
115         my $usage = extract_usage;
116         my $usage = extract_usage '/home/sri/foo.pod';
117
118       Extract usage message from the SYNOPSIS section of a file containing
119       POD documentation, defaults to using the file this function was called
120       from.
121
122         # "Usage: APPLICATION test [OPTIONS]\n"
123         extract_usage;
124
125         =head1 SYNOPSIS
126
127           Usage: APPLICATION test [OPTIONS]
128
129         =cut
130
131   getopt
132         getopt
133           'H|headers=s' => \my @headers,
134           't|timeout=i' => \my $timeout,
135           'v|verbose'   => \my $verbose;
136         getopt $array,
137           'H|headers=s' => \my @headers,
138           't|timeout=i' => \my $timeout,
139           'v|verbose'   => \my $verbose;
140         getopt $array, ['pass_through'],
141           'H|headers=s' => \my @headers,
142           't|timeout=i' => \my $timeout,
143           'v|verbose'   => \my $verbose;
144
145       Extract options from an array reference with Getopt::Long, but without
146       changing its global configuration, defaults to using @ARGV. The
147       configuration options "no_auto_abbrev" and "no_ignore_case" are enabled
148       by default.
149
150         # Extract "charset" option
151         getopt ['--charset', 'UTF-8'], 'charset=s' => \my $charset;
152         say $charset;
153
154   gunzip
155         my $uncompressed = gunzip $compressed;
156
157       Uncompress bytes with IO::Compress::Gunzip.
158
159   gzip
160         my $compressed = gzip $uncompressed;
161
162       Compress bytes with IO::Compress::Gzip.
163
164   hmac_sha1_sum
165         my $checksum = hmac_sha1_sum $bytes, 'passw0rd';
166
167       Generate HMAC-SHA1 checksum for bytes with Digest::SHA.
168
169         # "11cedfd5ec11adc0ec234466d8a0f2a83736aa68"
170         hmac_sha1_sum 'foo', 'passw0rd';
171
172   html_attr_unescape
173         my $str = html_attr_unescape $escaped;
174
175       Same as "html_unescape", but handles special rules from the HTML Living
176       Standard <https://html.spec.whatwg.org> for HTML attributes.
177
178         # "foo=bar&ltest=baz"
179         html_attr_unescape 'foo=bar&ltest=baz';
180
181         # "foo=bar<est=baz"
182         html_attr_unescape 'foo=bar&lt;est=baz';
183
184   html_unescape
185         my $str = html_unescape $escaped;
186
187       Unescape all HTML entities in string.
188
189         # "<div>"
190         html_unescape '&lt;div&gt;';
191
192   humanize_bytes
193         my $str = humanize_bytes 1234;
194
195       Turn number of bytes into a simplified human readable format. Note that
196       this function is EXPERIMENTAL and might change without warning!
197
198         # "1B"
199         humanize_bytes 1;
200
201         # "7.5GiB"
202         humanize_bytes 8007188480;
203
204         # "13GiB"
205         humanize_bytes 13443399680;
206
207         # "-685MiB"
208         humanize_bytes -717946880;
209
210   md5_bytes
211         my $checksum = md5_bytes $bytes;
212
213       Generate binary MD5 checksum for bytes with Digest::MD5.
214
215   md5_sum
216         my $checksum = md5_sum $bytes;
217
218       Generate MD5 checksum for bytes with Digest::MD5.
219
220         # "acbd18db4cc2f85cedef654fccc4a4d8"
221         md5_sum 'foo';
222
223   monkey_patch
224         monkey_patch $package, foo => sub {...};
225         monkey_patch $package, foo => sub {...}, bar => sub {...};
226
227       Monkey patch functions into package.
228
229         monkey_patch 'MyApp',
230           one   => sub { say 'One!' },
231           two   => sub { say 'Two!' },
232           three => sub { say 'Three!' };
233
234   punycode_decode
235         my $str = punycode_decode $punycode;
236
237       Punycode decode string as described in RFC 3492
238       <http://tools.ietf.org/html/rfc3492>.
239
240         # "bücher"
241         punycode_decode 'bcher-kva';
242
243   punycode_encode
244         my $punycode = punycode_encode $str;
245
246       Punycode encode string as described in RFC 3492
247       <http://tools.ietf.org/html/rfc3492>.
248
249         # "bcher-kva"
250         punycode_encode 'bücher';
251
252   quote
253         my $quoted = quote $str;
254
255       Quote string.
256
257   scope_guard
258         my $guard = scope_guard sub {...};
259
260       Create anonymous scope guard object that will execute the passed
261       callback when the object is destroyed.
262
263         # Execute closure at end of scope
264         {
265           my $guard = scope_guard sub { say "Mojo!" };
266           say "Hello";
267         }
268
269   secure_compare
270         my $bool = secure_compare $str1, $str2;
271
272       Constant time comparison algorithm to prevent timing attacks.
273
274   sha1_bytes
275         my $checksum = sha1_bytes $bytes;
276
277       Generate binary SHA1 checksum for bytes with Digest::SHA.
278
279   sha1_sum
280         my $checksum = sha1_sum $bytes;
281
282       Generate SHA1 checksum for bytes with Digest::SHA.
283
284         # "0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33"
285         sha1_sum 'foo';
286
287   slugify
288         my $slug = slugify $string;
289         my $slug = slugify $string, $bool;
290
291       Returns a URL slug generated from the input string. Non-word characters
292       are removed, the string is trimmed and lowercased, and whitespace
293       characters are replaced by a dash. By default, non-ASCII characters are
294       normalized to ASCII word characters or removed, but if a true value is
295       passed as the second parameter, all word characters will be allowed in
296       the result according to unicode semantics.
297
298         # "joel-is-a-slug"
299         slugify 'Joel is a slug';
300
301         # "this-is-my-resume"
302         slugify 'This is: my - résumé! ☃ ';
303
304         # "this-is-my-résumé"
305         slugify 'This is: my - résumé! ☃ ', 1;
306
307   split_cookie_header
308         my $tree = split_cookie_header 'a=b; expires=Thu, 07 Aug 2008 07:07:59 GMT';
309
310       Same as "split_header", but handles "expires" values from RFC 6265
311       <http://tools.ietf.org/html/rfc6265>.
312
313   split_header
314          my $tree = split_header 'foo="bar baz"; test=123, yada';
315
316       Split HTTP header value into key/value pairs, each comma separated part
317       gets its own array reference, and keys without a value get "undef"
318       assigned.
319
320         # "one"
321         split_header('one; two="three four", five=six')->[0][0];
322
323         # "two"
324         split_header('one; two="three four", five=six')->[0][2];
325
326         # "three four"
327         split_header('one; two="three four", five=six')->[0][3];
328
329         # "five"
330         split_header('one; two="three four", five=six')->[1][0];
331
332         # "six"
333         split_header('one; two="three four", five=six')->[1][1];
334
335   steady_time
336         my $time = steady_time;
337
338       High resolution time elapsed from an arbitrary fixed point in the past,
339       resilient to time jumps if a monotonic clock is available through
340       Time::HiRes.
341
342   tablify
343         my $table = tablify [['foo', 'bar'], ['baz', 'yada']];
344
345       Row-oriented generator for text tables.
346
347         # "foo   bar\nyada  yada\nbaz   yada\n"
348         tablify [['foo', 'bar'], ['yada', 'yada'], ['baz', 'yada']];
349
350   term_escape
351         my $escaped = term_escape $str;
352
353       Escape all POSIX control characters except for "\n".
354
355         # "foo\\x09bar\\x0d\n"
356         term_escape "foo\tbar\r\n";
357
358   trim
359         my $trimmed = trim $str;
360
361       Trim whitespace characters from both ends of string.
362
363         # "foo bar"
364         trim '  foo bar  ';
365
366   unindent
367         my $unindented = unindent $str;
368
369       Unindent multi-line string.
370
371         # "foo\nbar\nbaz\n"
372         unindent "  foo\n  bar\n  baz\n";
373
374   unquote
375         my $str = unquote $quoted;
376
377       Unquote string.
378
379   url_escape
380         my $escaped = url_escape $str;
381         my $escaped = url_escape $str, '^A-Za-z0-9\-._~';
382
383       Percent encode unsafe characters in string as described in RFC 3986
384       <http://tools.ietf.org/html/rfc3986>, the pattern used defaults to
385       "^A-Za-z0-9\-._~".
386
387         # "foo%3Bbar"
388         url_escape 'foo;bar';
389
390   url_unescape
391         my $str = url_unescape $escaped;
392
393       Decode percent encoded characters in string as described in RFC 3986
394       <http://tools.ietf.org/html/rfc3986>.
395
396         # "foo;bar"
397         url_unescape 'foo%3Bbar';
398
399   xml_escape
400         my $escaped = xml_escape $str;
401
402       Escape unsafe characters "&", "<", ">", """ and "'" in string, but do
403       not escape Mojo::ByteStream objects.
404
405         # "&lt;div&gt;"
406         xml_escape '<div>';
407
408         # "<div>"
409         use Mojo::ByteStream qw(b);
410         xml_escape b('<div>');
411
412   xor_encode
413         my $encoded = xor_encode $str, $key;
414
415       XOR encode string with variable length key.
416

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

SEE ALSO