This module contains factory functions to generate tubes that ease handling data sources.



   my $tube = iterate_array($array, %args); # OR
   my $tube = iterate_array(%args); # OR
   my $tube = iterate_array(\%args);

iterate over an array, that can be provided to the factory as an array field or unnamed first parameter $array, or provided as input record. In case both are provided, the array from the factory (the global array) is iterated for each call to the tube, before the array provided to the tube call itself.

The input record for the generated tube MUST be either false or a reference to an array. The returned tube ALWAYS returns an iterator (i.e. it returns the string iterator, followed by a sub reference that acts as an iterator).

The following arguments are supported:


the global array to iterate over. Defaults to an empty array reference. It can be passed also as the first unnamed argument;


name of the tube, useful when debugging;


   my $tube = open_file($binmode, %args); # OR
   my $tube = open_file(%args); # OR
   my $tube = open_file(\%args);

open a file from the input record.

Depending on what is provided as parameter input in %args, the input channel will be either the record itself (if input is undefined or zero-length) or what input points inside the input record, that in this case MUST be a hash.

The input channel might be either a filehandle or a string; in either case, normalize_filename from Data::Tubes::Util is used to resolve a handle or a filename.

The tube returns a data structure that copies the input one (if input is defined and not empty) and sets an output field (set in the factory, defaults to source) to a hash reference with the following fields:


a filehandle that can be used to read from the source;


what was passed as input;


the type of the particular source, might be handle, scalar (if the input is a reference to a scalar) or file;


a name that will provide a hint about what the channel is. If the input channel is a handle, this will be set to handle:%s (with %s expanded to a string); if it is a reference to a scalar (which is a valid filename for CORE::open) it sets it to scalar:%s and if it is a plain filename it sets it to file:%s.

The arguments accepted by the factory function are the following:


whenever a filehandle is opened, the generated filehandle is set to this via CORE::binmode. Defaults to :encoding(UTF-8). This parameter can also be passed as the first unnamed argument in the call to the factory function;


if defined and not empty, the records input to the tube MUST be hash references with a field named as the provided input; otherwise, the whole input record is the channel to open;


name for the tube, useful for debugging;


name of the output field in the returned record, defaults to source.


   my $tube = iterate_files(@channels_list); # OR
   my $tube = iterate_files(@channels_list, \%args);

generate a tube that iterates over a list of files, either provided to the factory function directly, or provided as a reference to an array when invoking the tube. The two following cases are equivalent:

   # pass the file list to the factory
   my $tube1 = iterate_files('foo.txt', 'bar.txt');
   my (undef, $iterator) = $tube1->();

   # leave factory without list, pass to the tube
   my $tube2 = iterate_files();
   my (undef, $iterator)= $tube2->(['foo.txt', 'bar.txt']);

All elements in @channels_list MUST be valid channels for the tube generated by "open_file". Optionally, the last item in the argument list can be a reference to a hash, with further options for the factory.

The factory is built as a sequence (see Data::Tubes::Plugin::Plumbing) of "iterate_array", "open_file" and a logger (see Data::Tubes::Plugin::Plumbing for the latter).

The following arguments can be (optionally) supplied via %args:


optional hash with arguments for "iterate_array", where the array field is overridden with @channels_list;


optional hash with arguments for logger in Data::Tubes::Plugin::Plubming. Defaults to setting a target pointing to a sub reference that gives out message reading from %s, where %s is expanded with the content of $record->{source}{name};


optional hash with arguments for the "open_file" sub-tube, defaults to the empty hash which means taking all defaults from "open_file".


Report bugs either through RT or GitHub (patches welcome).


Flavio Poletti <>


Copyright (C) 2016 by Flavio Poletti <>

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.