.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Flow 3pm"
.TH Flow 3pm "2008-05-11" "perl v5.10.0" "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::Flow \- Perl extension for simple\-minded recipe\-controlled build of data.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 11
\&  use Data::Flow;
\&  $recipes = { path  => { default => \*(Aq./MANIFEST\*(Aq},
\&               contents => { prerequisites => [\*(Aqpath\*(Aq, \*(Aqx\*(Aq] ,
\&                             process => 
\&                             sub {
\&                               my $data = shift; 
\&                               $data\->{ shift() } = \`cat $data\->{\*(Aqpath\*(Aq}\`
\&                                 x $data\->{\*(Aqx\*(Aq};
\&                             }
\&                           },
\&             };
\&
\&  $request = new Data::Flow $recipes;
\&  $request\->set( x => 1);
\&  print $request\->get(\*(Aqcontents\*(Aq);
\&
\&  tie %request, Data::Flow, $recipes;
\&  $request{x} = 1;
\&  print $request{contents};
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The module Data::Flow provides its services via objects. The objects may
be obtained by the usual
.PP
.Vb 1
\&  $request = new Data::Flow $recipes;
.Ve
.PP
paradigm. The argument \f(CW$recipes\fR is a hash reference, which provides
the rules for request processing. The objects support three methods,
\&\fIset()\fR, \fIget()\fR, \fIaget()\fR, and \fIalready_set()\fR. The first one is used to provide input data for
processing, the second one to obtain the output. The third one to obtain a
reference to an array with results of repeated \fIget()\fR, and the last one to query
whether a field is already known.
.PP
The unit of requested information is a \fIfield\fR. The method \fIset()\fR
takes a pair \f(CW\*(C`field => value\*(C'\fR, the methods \fIget()\fR and \fIalready_set()\fR take one
argument: the \f(CW\*(C`field\*(C'\fR, and the method \fIaget()\fR takes multiple fields.
.PP
Every object is created without any fields filled, but it knows how to
\&\fIconstruct\fR fields basing on other fields or some global into. This
knowledge is provided in the argument \f(CW$recipe\fR of the \fInew()\fR
function. This is a reference to a hash, keyed by \fIfields\fR. The
values of this hash are hash references themselves, which describe how
to acquire the \fIfield\fR which is the corresponding key of the initial
hash.
.PP
The internal hashes may have the following keys:
.ie n .IP """default""" 8
.el .IP "\f(CWdefault\fR" 8
.IX Item "default"
describes the default value for the key, if none is provided by
\&\fIset()\fR. The value becomes the value of the field of the object. No
additional processing is performed. Example:
.Sp
.Vb 1
\&  default => $Config{installdir}
.Ve
.ie n .IP """prerequisites""" 8
.el .IP "\f(CWprerequisites\fR" 8
.IX Item "prerequisites"
gives the fields which are needed for the construction of the given
field. The corresponding value is an array references. The array
contains the \fIrequired\fR fields.
.Sp
If \f(CW\*(C`defaults\*(C'\fR did not satisfy the request for a field, but
\&\f(CW\*(C`$recipe\->{field}{prerequisites}\*(C'\fR exists, the \fIrequired\fR
fields are build before any further processing is done. Example:
.Sp
.Vb 1
\&  prerequisites => [ qw(prefix arch) ]
.Ve
.ie n .IP """process""" 8
.el .IP "\f(CWprocess\fR" 8
.IX Item "process"
contains the rule to build the field. The value is a reference to a
subroutine taking 2 arguments: the reference to a hash with all the fields
which have been set, and the name of
the required field. It is up to the subroutine to actually fill the
corresponding field of the hash, an error condition is raised if it did
not. Example:
.Sp
.Vb 2
\&  process => sub { my $data = shift;
\&                  $data\->{time} = localtime(time) } }
.Ve
.ie n .IP """oo_process""" 8
.el .IP "\f(CWoo_process\fR" 8
.IX Item "oo_process"
contains the rule to build the field. The value is a reference to a
subroutine taking 2 arguments: the object \f(CW$request\fR, and the name of
the required field. It is up to the subroutine to actually fill the
corresponding field of \f(CW$request\fR, an error condition is raised if it did
not. Example:
.Sp
.Vb 2
\&  oo_process => sub { my $data = shift;
\&                     $data\->set( time => localtime(time) ) }
.Ve
.ie n .IP """output""" 8
.el .IP "\f(CWoutput\fR" 8
.IX Item "output"
the corresponing value has the same meaning as for \f(CW\*(C`process\*(C'\fR, but the
return value of the subroutine is used as the value of the
\&\fIfield\fR. Example:
.Sp
.Vb 1
\&  output => sub { localtime(time) }
.Ve
.ie n .IP """oo_output""" 8
.el .IP "\f(CWoo_output\fR" 8
.IX Item "oo_output"
the corresponing value has the same meaning as for \f(CW\*(C`process\*(C'\fR, but the
return value of the method is used as the value of the
\&\fIfield\fR. Example:
.Sp
.Vb 1
\&  output => sub { my $self = shift; $self\->get(\*(Aqr\*(Aq) . localtime(time) }
.Ve
.ie n .IP """filter""" 8
.el .IP "\f(CWfilter\fR" 8
.IX Item "filter"
contains the rule to build the field basing on other fields. The value
is a reference to an array. The first element of the array is a
reference to a subroutine, the rest contains names of the fields. When
the subroutine is called, the arguments are the values of \fIfields\fR of
the object \f(CW$request\fR which appear in the array (in the same order). The
return value of the subroutine is used as the value of the
\&\fIfield\fR. Example:
.Sp
.Vb 2
\&  filter => [ sub { shift + shift }, 
\&              \*(Aqfirst_half\*(Aq, \*(Aqsecond_half\*(Aq ]
.Ve
.Sp
Note that the mentioned field will be automatically marked as
prerequisites.
.ie n .IP """self_filter""" 8
.el .IP "\f(CWself_filter\fR" 8
.IX Item "self_filter"
is similar to \f(CW\*(C`filter\*(C'\fR, but an extra argument, the object itself, is put in
front of the list of arguments.  Example:
.Sp
.Vb 5
\&  self_filter => [ sub { my ($self, $first_half = (shift, shift);
\&                         $first_half *= \-$self\->get(\*(Aqtotal\*(Aq)*100
\&                           if $first_half < 0;  # negative means percentage
\&                         $first_half + shift }, 
\&              \*(Aqfirst_half\*(Aq, \*(Aqsecond_half\*(Aq ]
.Ve
.ie n .IP """class_filter""" 8
.el .IP "\f(CWclass_filter\fR" 8
.IX Item "class_filter"
is similar to \f(CW\*(C`filter\*(C'\fR, but the first argument is the name of the
method to call, second one is the name of the package to use for the
method invocation. The rest contains names of field to provide as
method arguments. Example:
.Sp
.Vb 1
\&  class_filter => [ \*(Aqnew\*(Aq, \*(AqFileHandle\*(Aq, \*(Aqfilename\*(Aq ]
.Ve
.ie n .IP """method_filter""" 8
.el .IP "\f(CWmethod_filter\fR" 8
.IX Item "method_filter"
is similar to \f(CW\*(C`class_filter\*(C'\fR, but the second argument is the name of the
field which is used to call the method upon. Example:
.Sp
.Vb 1
\&  method_filter => [ \*(Aqshow\*(Aq, \*(Aqwidget_name\*(Aq, \*(Aqcurrent_display\*(Aq ]
.Ve
.SS "Tied interface"
.IX Subsection "Tied interface"
The access to the same functionality is available via tied hash
interface.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ilya Zakharevich, cpan@ilyaz.org, with multiple additions from
Terrence Monroe Brannon and Radoslav Nedyalkov.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fImake\fR\|(1).