.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Data::Rmap 3pm"
.TH Data::Rmap 3pm "2016-12-28" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Rmap \- recursive map, apply a block to a data structure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& $ perl \-MData::Rmap \-e \*(Aqprint rmap { $_ } 1, [2,3], \e\e4, "\en"\*(Aq
\& 1234
\&
\& $ perl \-MData::Rmap=:all
\& rmap_all { print (ref($_) || "?") ,"\en" } \e@array, \e%hash, \e*glob;
\&
\& # OUTPUT (Note: a GLOB always has a SCALAR, hence the last two items)
\& # ARRAY
\& # HASH
\& # GLOB
\& # SCALAR
\& # ?
\&
\&
\& # Upper\-case your leaves in\-place
\& $array = [ "a", "b", "c" ];
\& $hash  = { key => "a value" };
\& rmap { $_ = uc $_; } $array, $hash;
\&
\& use Data::Dumper; $Data::Dumper::Terse=1; $Data::Dumper::Indent=0;
\& print Dumper($array), " ", Dumper($hash), "\en";
\&
\& # OUTPUT
\& # [\*(AqA\*(Aq,\*(AqB\*(Aq,\*(AqC\*(Aq] {\*(Aqkey\*(Aq => \*(AqA VALUE\*(Aq}
\&
\&
\& # Simple array dumper.
\& # Uses $self\->recurse method to alter traversal order
\& ($dump) = rmap_to {
\&
\&    return "\*(Aq$_\*(Aq" unless ref($_); # scalars are quoted and returned
\&
\&    my $self = shift;
\&    # use $self\->recurse to grab results and wrap them
\&    return \*(Aq[ \*(Aq . join(\*(Aq, \*(Aq, $self\->recurse() ) . \*(Aq ]\*(Aq;
\&
\&  } ARRAY|VALUE,  [ 1, [ 2, [ [ 3 ], 4 ] ], 5 ];
\&
\& print "$dump\en";
\& # OUTPUT
\& # [ \*(Aq1\*(Aq, [ \*(Aq2\*(Aq, [ [ \*(Aq3\*(Aq ], \*(Aq4\*(Aq ] ], \*(Aq5\*(Aq ]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 1
\& rmap BLOCK LIST
.Ve
.PP
Recursively evaluate a \s-1BLOCK\s0 over a list of data structures
(locally setting \f(CW$_\fR to each element) and return the list composed
of the results of such evaluations.  \f(CW$_\fR can be used to modify
the elements.
.PP
Data::Rmap currently traverses \s-1HASH, ARRAY, SCALAR\s0 and \s-1GLOB\s0 reference
types and ignores others.  Depending on which rmap_* wrapper is used,
the \s-1BLOCK\s0 is called for only scalar values, arrays, hashes, references,
all elements or a customizable combination.
.PP
The list of data structures is traversed pre-order in a depth-first fashion.
That is, the \s-1BLOCK\s0 is called for the container reference before is it called
for it's elements (although see \*(L"recurse\*(R" below for post-order).
The values of a hash are traversed in the usual \*(L"values\*(R" order which
may affect some applications.
.PP
If the \*(L"cut\*(R" subroutine is called in the \s-1BLOCK\s0 then the traversal
stops for that branch, say if you \*(L"cut\*(R" an array then the code is
never called for it's elements (or their sub-elements).
To simultaneously return values and cut, simply pass the return list
to cut:  \f(CW\*(C`cut(\*(Aqadd\*(Aq,\*(Aqto\*(Aq,\*(Aqreturned\*(Aq);\*(C'\fR
.PP
The first parameter to the \s-1BLOCK\s0 is an object which maintains the
state of the traversal.  Methods available on this object are
described in \*(L"State Object\*(R" below.
.SH "EXPORTS"
.IX Header "EXPORTS"
By default:
.PP
.Vb 1
\& rmap, rmap_all, cut
.Ve
.PP
Optionally:
.PP
.Vb 3
\& rmap_scalar rmap_hash rmap_array rmap_code rmap_ref rmap_to
\& :types => [ qw(NONE VALUE HASH ARRAY SCALAR REF CODE ALL) ],
\& :all => ... # everything
.Ve
.SH "Functions"
.IX Header "Functions"
The various names are just wrappers which select when to call
the code \s-1BLOCK. \s0 rmap_all always calls it, the others are more
selective while rmap_to takes an extra parameter permitting you
to provide selection criteria.  Furthermore, you can always
just rmap_all and skip nodes which are not of interest.
.ie n .IP "rmap_to { ... } $want, @data_structures;" 4
.el .IP "rmap_to { ... } \f(CW$want\fR, \f(CW@data_structures\fR;" 4
.IX Item "rmap_to { ... } $want, @data_structures;"
Most general first.
.Sp
Recurse the \f(CW@data_structures\fR and apply the \s-1BLOCK\s0 to
elements selected by \f(CW$want\fR.  The \f(CW$want\fR parameter is the
bitwise \*(L"or\*(R" of whatever types you choose (imported with :types):
.Sp
.Vb 12
\& VALUE  \- non\-reference scalar, eg. 1
\& HASH   \- hash reference
\& ARRAY  \- array reference
\& SCALAR \- scalar reference, eg. \e1
\& REF    \- higher\-level reference, eg. \e\e1, \e\e{}
\&          B<NOT> any reference type, see <Scalar::Util>\*(Aqs reftype:
\&          perl \-MScalar::Util=reftype \-le \*(Aqprint map reftype($_), \e1, \e\e1\*(Aq
\& GLOB   \- glob reference, eg. \e*x
\&          (scalar, hash and array recursed, code too as of 0.63)
\& ALL    \- all of the above (not CODE)
\& CODE   \- code references (as of 0.63)
\& NONE   \- none of the above
.Ve
.Sp
So to call the block for arrays and scalar values do:
.Sp
.Vb 2
\& use Data::Rmap \*(Aq:all\*(Aq;         # or qw(:types rmap_to)
\& rmap { ... } ARRAY|VALUE, @data_structures;
.Ve
.Sp
(\s-1ALL\s0 | \s-1CODE\s0) and (\s-1ALL & \s0!GLOB) might also be handy.
.Sp
The remainder of the wrappers are given in terms of the \f(CW$want\fR for rmap_to.
.ie n .IP "rmap { ... } @list;" 4
.el .IP "rmap { ... } \f(CW@list\fR;" 4
.IX Item "rmap { ... } @list;"
Recurse and call the \s-1BLOCK\s0 on non-reference scalar values.  \f(CW$want\fR = \s-1VALUE\s0
.IP "rmap_all \s-1BLOCK LIST\s0" 4
.IX Item "rmap_all BLOCK LIST"
Recurse and call the \s-1BLOCK\s0 on everything.  \f(CW$want\fR = \s-1ALL\s0
.ie n .IP "rmap_scalar { ... }  @list" 4
.el .IP "rmap_scalar { ... }  \f(CW@list\fR" 4
.IX Item "rmap_scalar { ... } @list"
Recurse and call the \s-1BLOCK\s0 on non-collection scalars.
\&\f(CW$want\fR = VALUE|SCALAR|REF
.IP "rmap_hash" 4
.IX Item "rmap_hash"
Recurse and call the \s-1BLOCK\s0 on hash refs.  \f(CW$want\fR = \s-1HASH\s0
.IP "rmap_array" 4
.IX Item "rmap_array"
Recurse and call the \s-1BLOCK\s0 on array refs.  \f(CW$want\fR = \s-1ARRAY\s0
.IP "rmap_code" 4
.IX Item "rmap_code"
Recurse and call the \s-1BLOCK\s0 on code refs.  \f(CW$want\fR = \s-1CODE\s0
.IP "rmap_ref" 4
.IX Item "rmap_ref"
Recurse and call the \s-1BLOCK\s0 on all \*(L"normal\*(R" references:
\&\f(CW$want\fR = HASH|ARRAY|SCALAR|REF
.Sp
Note: rmap_ref isn't the same as rmap_to {} \s-1REF\s0
.IP "cut(@list)" 4
.IX Item "cut(@list)"
Don't traverse sub-elements and return the \f(CW@list\fR immediately.
For example, if \f(CW$_\fR is an \s-1ARRAY\s0 reference, then the array's elements
are not traversed.
.Sp
If there's two paths to an element, both will need to be cut.
.SH "State Object"
.IX Header "State Object"
The first parameter to the \s-1BLOCK\s0 is an object which maintains
most of the traversal state (except current node, which is \f(CW$_\fR).
\&\fIYou will ignore it most of the time\fR.
The \*(L"recurse\*(R" method may be useful.
Other methods should only be used in throw away tools, see \s-1TODO\s0
.PP
Methods:
.IP "recurse" 4
.IX Item "recurse"
Process child nodes of \f(CW$_\fR now and return the result.
.Sp
This makes it easier to perform post-order and in-order
processing of a structure.  Note that since the same \*(L"seen list\*(R"
is used, the child nodes aren't reprocessed.
.IP "code" 4
.IX Item "code"
The code reference of the \s-1BLOCK\s0 itself.  Possible useful in
some situations.
.IP "seen" 4
.IX Item "seen"
Reference to the \s-1HASH\s0 used to track where we have visited.
You may want to modify it in some situations (though I haven't yet).
Beware circular references.  The (current) convention used for the key
is in the source.
.IP "want" 4
.IX Item "want"
The \f(CW$want\fR state described in rmap_to.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 3
\& # command\-line play
\& $ perl \-MData::Rmap \-le \*(Aqprint join ":", rmap { $_ } 1,2,[3..5],\e\e6\*(Aq
\& 1:2:3:4:5:6
\&
\&
\& # Linearly number questions on a set of pages
\& my $qnum = 1;
\& rmap_hash {
\&     $_\->{qnum} = $qnum++ if($_\->{qn});
\& } @pages;
\&
\&
\& # Grep recursively, finding ALL objects
\& use Scalar::Util qw(blessed);
\& my @objects = rmap_ref {
\&     blessed($_) ? $_ : ();
\& } $data_structure;
\&
\&
\& # Grep recursively, finding public objects (note the cut)
\& use Scalar::Util qw(blessed);
\& my @objects = rmap_ref {
\&     blessed($_) ?  cut($_) : ();
\& } $data_structure;
\&
\&
\& # Return a modified structure
\& # (result flattening means we must cheat by cloning then modifying)
\& use Storable qw(dclone);
\& use Lingua::EN::Numbers::Easy;
\&
\& $words = [ 1, \e2, { key => 3 } ];
\& $nums = dclone $words;
\& rmap { $_ = $N{$_} || $_ } $nums;
\&
\&
\& # Make an assertion about a structure
\& use Data::Dump;
\& rmap_ref {
\&    blessed($_) && $_\->isa(\*(AqQuestion\*(Aq) && defined($_\->name)
\&        or die "Question doesn\*(Aqt have a name:", dump($_);
\& } @pages;
\&
\&
\& # Traverse a tree using localize state
\& $tree = [
\&     one =>
\&     two =>
\&     [
\&         three_one =>
\&         three_two =>
\&         [
\&             three_three_one =>
\&         ],
\&         three_four =>
\&     ],
\&     four =>
\&     [
\&         [
\&             five_one_one =>
\&         ],
\&     ],
\& ];
\&
\& @path = (\*(Aqq\*(Aq);
\& rmap_to {
\&     if(ref $_) {
\&         local(@path) = (@path, 1); # ARRAY adds a new level to the path
\&         $_[0]\->recurse(); # does stuff within local(@path)\*(Aqs scope
\&     } else {
\&         print join(\*(Aq.\*(Aq, @path), " = $_ \en"; # show the scalar\*(Aqs path
\&     }
\&     $path[\-1]++; # bump last element (even when it was an aref)
\& } ARRAY|VALUE, $tree;
\&
\& # OUTPUT
\& # q.1 = one
\& # q.2 = two
\& # q.3.1 = three_one
\& # q.3.2 = three_two
\& # q.3.3.1 = three_three_one
\& # q.3.4 = three_four
\& # q.4 = four
\& # q.5.1.1 = five_one_one
\&
\& # replace CODE with "<CODE>"
\& $ perl \-MData::Rmap=:all \-E \*(Aqsay join ":", rmap_code { "<CODE>" } sub{},sub{}\*(Aq
\& <CODE>:<CODE>
\&
\& # look inside code refs with PadWalker
\& $ perl \-MData::Rmap=:all \-MSub::Identify=:all \-MPadWalker=:all \-MSub::Name
\&   use 5.10.0;
\&   my $s = sub {}; sub A::a { $s };
\&   say join ", ",
\&    rmap_code {
\&        sub_fullname($_),                       # name string
\&        map { $_[0]\->recurse } closed_over($_)  # then recurse the sub innards
\&    } \e*A::a, subname b => sub { $s };
\&   # A::a, main::_\|_ANON_\|_, main::b
.Ve
.SH "Troubleshooting"
.IX Header "Troubleshooting"
Beware comma after block:
.PP
.Vb 3
\& rmap { print }, 1..3;
\&               ^\-\-\-\-\-\-\-\- bad news, you get an empty list:
\& rmap(sub { print $_; }), 1..3;
.Ve
.PP
If you don't import a function, perl's confusion may produce:
.PP
.Vb 2
\& $ perl \-MData::Rmap \-le \*(Aqrmap_scalar { print } 1\*(Aq
\& Can\*(Aqt call method "rmap_scalar" without a package or object reference...
\&
\& $ perl \-MData::Rmap \-le \*(Aqrmap_scalar { $_++ } 1\*(Aq
\& Can\*(Aqt call method "rmap_scalar" without a package or object reference...
.Ve
.PP
If there's two paths to an element, both will need to be cut.
.PP
If there's two paths to an element, one will be taken randomly when
there is an intervening hash.
.PP
Autovivification can lead to \*(L"Deep recursion\*(R" warnings if you test
\&\f(CW\*(C`exists $_\->{this}{that}\*(C'\fR instead of
\&\f(CW\*(C`exists $_\->{this} && exists $_\->{this}{that}\*(C'\fR
as you may follow a long chain of \*(L"this\*(R"s
Alternatively use the \*(L"no autovivification\*(R" pragma to avoid this problem.
.SH "TODO"
.IX Header "TODO"
put for \f(CW@_\fR in wrapper to allow parameters in a different wrapper,
solve localizing problem.
.PP
Store custom localized data about the traversal.
Seems too difficult and ugly when compare to doing it at the call site.
Should support multiple reentrancy so avoid the symbol table.
.PP
\&\f(CW\*(C`rmap_args { } $data_structure, @args\*(C'\fR form to pass parameters.
Could potentially help localizing needs.  (Maybe only recurse last item)
.PP
Benchmark.  Use array based object and/or direct access internally.
.PP
Think about permitting different callback for different types.
The prototype syntax is a bit too flaky....
.PP
Ensure that no memory leaks are possible, leaking the closure.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
map, grep, Storable's dclone, Scalar::Util's reftype and blessed
.PP
Faint traces of treemap:
.PP
.Vb 1
\& http://www.perlmonks.org/index.pl?node_id=60829
.Ve
.PP
Update: various alternatives have appear over the years,
Data::Visitor has a list.
.SH "AUTHOR"
.IX Header "AUTHOR"
Brad Bowman <rmap@bereft.net>
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2004\- Brad Bowman (<rmap@bereft.net>).
All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
See perlartistic and perlgpl.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0