NAME

       Data::Flow - Perl extension for simple-minded recipe-controlled build of data.

SYNOPSIS

         use Data::Flow;
         $recipes = { path  => { default => './MANIFEST'},
                      contents => { prerequisites => ['path', 'x'] ,
                                    process =>
                                    sub {
                                      my $data = shift;
                                      $data->{ shift() } = `cat $data->{'path'}`
                                        x $data->{'x'};
                                    }
                                  },
                    };

         $request = new Data::Flow $recipes;
         $request->set( x => 1);
         print $request->get('contents');

         tie %request, Data::Flow, $recipes;
         $request{x} = 1;
         print $request{contents};

DESCRIPTION

       The module Data::Flow provides its services via objects. The objects may be obtained by the usual

         $request = new Data::Flow $recipes;

       paradigm. The argument $recipes is a hash reference, which provides the rules for request processing. The
       objects support three methods, set(), get(), aget(), and already_set(). 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 get(), and the last one to query whether a field is already known.

       The unit of requested information is a field. The method set() takes a pair "field => value", the methods
       get() and already_set() take one argument: the "field", and the method aget() takes multiple fields.

       Every object is created without any fields filled, but it knows how to construct fields basing on other
       fields or some global into. This knowledge is provided in the argument $recipe of the new() function.
       This is a reference to a hash, keyed by fields. The values of this hash are hash references themselves,
       which describe how to acquire the field which is the corresponding key of the initial hash.

       The internal hashes may have the following keys:

       "default"
               describes  the  default  value  for  the key, if none is provided by set(). The value becomes the
               value of the field of the object. No additional processing is performed. Example:

                 default => $Config{installdir}

       "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 required fields.

               If  "defaults"  did  not  satisfy  the request for a field, but "$recipe->{field}{prerequisites}"
               exists, the required fields are build before any further processing is done. Example:

                 prerequisites => [ qw(prefix arch) ]

       "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:

                 process => sub { my $data = shift;
                                 $data->{time} = localtime(time) } }

       "oo_process"
               contains  the  rule  to  build  the  field.  The  value  is  a reference to a subroutine taking 2
               arguments: the object $request, and the name of the required field. It is up to the subroutine to
               actually fill the corresponding field of $request, an error condition is raised if  it  did  not.
               Example:

                 oo_process => sub { my $data = shift;
                                    $data->set( time => localtime(time) ) }

       "output"
               the  corresponing  value  has  the  same  meaning  as  for "process", but the return value of the
               subroutine is used as the value of the field. Example:

                 output => sub { localtime(time) }

       "oo_output"
               the corresponing value has the same meaning as for "process", but the return value of the  method
               is used as the value of the field. Example:

                 output => sub { my $self = shift; $self->get('r') . localtime(time) }

       "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 fields of the object
               $request which appear in the array (in the same order). The return value  of  the  subroutine  is
               used as the value of the field. Example:

                 filter => [ sub { shift + shift },
                             'first_half', 'second_half' ]

               Note that the mentioned field will be automatically marked as prerequisites.

       "self_filter"
               is  similar to "filter", but an extra argument, the object itself, is put in front of the list of
               arguments.  Example:

                 self_filter => [ sub { my ($self, $first_half = (shift, shift);
                                        $first_half *= -$self->get('total')*100
                                          if $first_half < 0;  # negative means percentage
                                        $first_half + shift },
                             'first_half', 'second_half' ]

       "class_filter"
               is similar to "filter", 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:

                 class_filter => [ 'new', 'FileHandle', 'filename' ]

       "method_filter"
               is similar to "class_filter", but the second argument is the name of the field which is  used  to
               call the method upon. Example:

                 method_filter => [ 'show', 'widget_name', 'current_display' ]

   Tied interface
       The access to the same functionality is available via tied hash interface.

AUTHOR

       Ilya  Zakharevich,  cpan@ilyaz.org,  with  multiple  additions  from Terrence Monroe Brannon and Radoslav
       Nedyalkov.

SEE ALSO

       perl(1), make(1).

perl v5.36.0                                       2022-10-13                                          Flow(3pm)