NAME

Data::Tubes::Plugin::Util

DESCRIPTION

This module contains functions to ease using tubes.

FUNCTIONS

identify

   identify($args, $opts);

print out an identification for a tube as a log (via Log::Log4perl::Tiny). This function is supposed to be used in tube factories, to print out a message stating that the specific factory is running.

In general, $args is the hash reference of arguments that is used as input for the factory. On the other hand, $opts are options for identity itself.

Both $args and $opts MUST be hash references. If not provided (or undef), it is taken from field identification in $args.

The function tries to figure out the name of the factory that is calling the function itself, so that you don't have to. You can override this automatic detection through option caller inside $opts.

The following keys are supported in $opts:

caller

the result of running CORE::caller where the input sees fit. This is useful whenever you have a tube factory that relies upon another tube factory, and you want to ensure that the right caller will be used;

level

hint for CORE::caller for automatic detection of the caller. You are probably better off using "caller" instead;

loglevel

log level to use for emitting the log message;

message

a Template::Perlish-compliant string with the message. This template will be expanded with a hash containing the following parameters:

package

filename

line

subroutine

hasargs

wantarray

evaltext

is_require

hints

bitmask

hintsh

whatever is available as caller (either from $opts, or automatically detected);

name

of the tube, tanek from $args (or set to string *unknown*, in case it is undefined in $args);

args

what passed as $args

opts

what passed or deduced as $opts

tp_opts

options for Template::Perlish's constructor.

The following options are supported in $args:

identifier

the default value for $opts;

name

the name of the tube, defaults to *undef*.

log_helper

   my $lh = log_helper($args, $opts);

generate a sub reference that can be useful for emitting log messages, possibly inserted by a factory inside a generated tube. Weight carefully if you really want to use a log helper or if you're just better off using a logger from Data::Tubes::Plugin::Plumbing.

$args is supposed to be arguments used to call the tube factory. $opts contain options for log_helper itself.

If not defined, $opts is taken from field logger in $args.

The returned sub takes a record as input, and expands a Template::Perlish template. See message in the options $opts below.

The following options are available for $opts:

loglevel

log level to use for emitting the log message;

message

a Template::Perlish-compliant string with the message. This template will be expanded with a hash containing the following parameters:

args

whatever was passed as $args;

opts

whatever passed as $opts or taken from $args in field logger;

record

the input record.

tp_opts

options for Template::Perlish's constructor.

The following options are recognised from $args:

logger

the default value for $opts;

name

the name of the tube, defaults to *undef*.

read_file

   my $contents = read_file($filename, %args); # OR
   my $contents = read_file(%args); # OR
   my $contents = read_file(\%args);

See "read_file" in Data::Tubes::Util, this is a re-export for ease of use with "summon" in Data::Tubes and backwards compatibility.

tubify

   @tubes = tubify(@specifications); # OR
   @tubes = tubify(\%opts, @specifications);

automatically transform input specifications into tubes. Each item in @specification can be either a tube (i.e. a code reference), or something that can be transformed into a tube (see "tube" in Data::Tubes for a definition). Additionally, whatever in @specification is found to be false (in the Perl sense) will just be ignored.

Hence, this does returns the two tubes you think:

   @tubes = tubify(
      'Reader::by_line',
      ['Parser::by_format', format => 'foo,bar,baz'],
   );

Additionally, this actually does what you think:

   @tubes = tubify(
      'Reader::by_line',
      ['Parser::by_format', format => 'foo,bar,baz'],
      ($foobar && sub { die unless $_[0]->{structured}}),
   );

You can optionally pass a hash reference of options as the first parameter. This allows you to set any option available through "tube" in Data::Tubes, e.g. prefix.

BUGS AND LIMITATIONS

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

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Flavio Poletti <polettix@cpan.org>

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.

cpanm Data::Tubes

perl -MCPAN -e shell
install Data::Tubes