Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Munge(3)	      User Contributed Perl Documentation	Data::Munge(3)

NAME
       Data::Munge - various utility functions

SYNOPSIS
	use Data::Munge;

	my $re = list2re qw/f ba foo bar baz/;
	# $re =	qr/bar|baz|foo|ba|f/;

	print byval { s/foo/bar/ } $text;
	# print	do { my	$tmp = $text; $tmp =~ s/foo/bar/; $tmp };

	foo(mapval { chomp } @lines);
	# foo(map { my $tmp = $_; chomp	$tmp; $tmp } @lines);

	print replace('Apples are round, and apples are	juicy.', qr/apples/i, 'oranges', 'g');
	# "oranges are round, and oranges are juicy."
	print replace('John Smith', qr/(\w+)\s+(\w+)/, '$2, $1');
	# "Smith, John"

	my $trimmed = trim "  a	b c "; # "a b c"

	my $x =	'bar';
	if (elem $x, [qw(foo bar baz)])	{ ... }

	my $contents = slurp $fh;  # or: slurp *STDIN

	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

	if ("hello, world!" =~ /(\w+), (\w+)/) {
	  my @captured = submatches;
	  # @captured =	("hello", "world")
	}

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;

	   This	function takes special care to get several edge	cases right:

	   o   Empty list: An empty argument list results in a regex that
	       doesn't match anything.

	   o   Empty string: An	argument list consisting of a single empty
	       string results in a regex that matches the empty	string (and
	       nothing else).

	   o   Prefixes: The input strings are sorted by descending length to
	       ensure longer matches are tried before shorter matches.
	       Otherwise "list2re('ab',	'abcd')" would generate	"qr/ab|abcd/",
	       which (on its own) can never match "abcd" (because "ab" is
	       tried first, and	it always succeeds where "abcd"	could).

       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.

	   Since perl 5.14 you can also	use the	"/r" flag:

	    foo($str =~	s/!/?/gr);

	   But "byval" works on	all versions of	perl and is not	limited	to
	   "s///".

       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. Caveat:
	   Unlike with "eval" the code runs in an empty	lexical	scope:

	    my $foo = "Hello, world!\n";
	    eval_string	'print $foo';
	    # Dies: Global symbol "$foo" requires explicit package name

	   That	is, the	eval'd code can't see variables	from the scope of the
	   "eval_string" call.

       slurp FILEHANDLE
	   Reads and returns all remaining data	from FILEHANDLE	as a string,
	   or "undef" if it hits end-of-file. (Interaction with	non-blocking
	   filehandles is currently not	well defined.)

	   "slurp $handle" is equivalent to "do	{ local	$/; scalar readline
	   $handle }".

       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-2015 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.

perl v5.32.1			  2017-03-17			Data::Munge(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Munge&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help