=pod

=for vim
   vim: tw=72 ts=3 sts=3 sw=3 et ai :

=encoding utf8

=head1 NAME

Data::Tubes::Plugin::Parser

=head1 DESCRIPTION

This module contains factory functions to generate I<tubes> that ease
parsing of input records.

Each of the generated tubes has the following contract:

=over

=item *

the input record MUST be a hash reference;

=item *

one field in the hash (according to factory argument C<input>, set to
C<raw> by default) points to the input text that has to be parsed;

=item *

one field in the hash (according to factory argument C<output>, set to
C<structured> by default) is set to the output of the parsing operation.

=back

The factory functions below have two names, one starting with C<parse_>
and the other without this prefix. They are perfectly equivalent to each
other, whereas the short version can be handier e.g. when using C<tube>
or C<pipeline> from L<Data::Tubes>.

=head1 FUNCTIONS

=over

=item B<< by_format >>

=item B<< parse_by_format >>

   my $tube = by_format(%args); # OR
   my $tube = by_format(\%args); # OR
   my $tube = by_format($format, %args);

parse the input text according to a template format string (passed via
factory argument C<format> or through first unnamed parameter
C<$format>). This string is supposed to be composed of word and non-word
sequences, where each word sequence is assumed to be the name of a
field, and each non-word sequence is a separator. Example:

   $format = 'foo;bar;baz';

is interpreted as follows:

   @field_names = ('foo', 'bar', 'baz');
   @separators  = (';', ';');

Example:

   $format = 'foo;bar~~~baz';

is interpreted as follows:

   @field_names = ('foo', 'bar', 'baz');
   @separators  = (';', '~~~');

In the first case, i.e. when all separators are equal to each other,
L</parse_by_split> will be called, as it is (arguably) slightly more
efficient. Otherwise, L</parse_by_regexes> will be called. Whatever
these two factories return will be returned back.

All C<@field_names> MUST be different from one another.

The following arguments are supported:

=over

=item C<allow_missing>

set to the number of missing trailing elements that you are fine to
lose, in case the format is only compound of a single separator and
L</parse_by_split> is used behind the scenes. This allows you setting an
optional I<catchall> trailing parameter to collect whatever you are not
really interested into, also allowing for its absence.

As an example, consider the following input lines:

   FOO0,BAR0,BAZ0,WHATEVER
   FOO1,BAR1,BAZ1
   FOO2,BAR2,BAZ2,WHAT2,EVER2,

Assuming that you're really interested into the first three parameter,
disregarding whatever comes after, you can set the following format:

   foo,bar,baz,rest

and also set C<allow_missing> to 1, indicating that you can sustain the
lack of C<rest> (which you really don't care about);

=item C<format>

the format to use for splitting the inputs. This parameter is the
I<main> one, so it can also be passed as the first, unnamed parameter
(see third calling convention);

=item C<input>

name of the input field, defaults to C<raw>;

=item C<name>

name of the tube, useful for debugging;

=item C<output>

name of the output field, defaults to C<structured>;

=back

=item B<< by_regex >>

=item B<< parse_by_regex >>

   my $tube = by_regex(%args); # OR
   my $tube = by_regex(\%args); # OR
   my $tube = by_regex($regex, %args);

parse the input text based on a regular expression, passed as argument
C<regex> or C<$regex> as unnamed first parameter. The regular expression
is supposed to have named captures, that will eventually be used to
populate the rendered output.

The following arguments are supported:

=over

=item C<input>

name of the input field, defaults to C<raw>;

=item C<name>

name of the tube, useful for debugging;

=item C<output>

name of the output field, defaults to C<structured>;

=item C<regex>

the regular expression to use for splitting the inputs. This is the
I<main> argument, and can be passed also as the first unnamed one in the
argument list.

=back

=item B<< by_separators >>

=item B<< parse_by_separators >>

   my $tube = by_separators(%args); # OR
   my $tube = by_separators(\%args); # OR

parse the input according to a series of separators, that will be
applied in sequence. For example, if the list of separators is the
following:

   @separators = (';', '~~');

the following input:

   $text = 'foo;bar~~/baz/';

will be split as:

   @split = ('foo', 'bar', '/baz/');

The following arguments are supported:

=over

=item C<input>

name of the input field, defaults to C<raw>;

=item C<keys>

a reference to an array containing the list of keys to be associated to
the values from the split;

=item C<name>

name of the tube, useful for debugging;

=item C<output>

name of the output field, defaults to C<structured>;

=item C<separators>

a reference to an array containing the list of separators to be
used for splitting the input.

=back

=item B<< by_split >>

=item B<< parse_by_split >>

   my $tube = by_split(%args); # OR
   my $tube = by_split(\%args); # OR
   my $tube = by_split($separator, %args);

split the input according to a separator string, passed either as the
first unnamed parameter C<$separator> or as hash options C<separator>.

The following arguments are supported:

=over

=item C<allow_missing>

set to the number of missing trailing elements that you are fine to
lose, in case you also provide C<keys> (see below). This is particularly
important when this function is called behind the scenes by
L</parse_by_format>, because I<that> sets C<keys>.

In practice, suppose that you set the following C<keys>:

   [qw< foo bar baz whatever >]

A normal parsing will expect to find at least four elements, so the
following input would fail:

   FOO,BAR,BAZ

On the other hand, if you set C<allow_missing> to 1, you are accepting
that there might be a missing value for C<whatever>, that will be filled
with the undefined value.


=item C<input>

name of the input field, defaults to C<raw>;

=item C<keys>

optional reference to an array containing a list of keys to be
associated to the split data. If present, it will be used as such; if
absent, a reference to an array will be set as output.

=item C<name>

name of the tube, useful for debugging;

=item C<output>

name of the output field, defaults to C<structured>;

=item C<separator>

a reference to an array containing the list of separators to be
used for splitting the input. This is the I<main> argument, and can be
passed also as the first unnamed one in the argument list.

=back

=item B<< ghashy >>

=item B<< parse_ghashy >>

   my $tube = ghashy(%args); # OR
   my $tube = ghashy(\%args);

parse the input thext as a hash, generalized. The algorithm used is the
same as L<Data::Tubes::Util/generalized_hash>. It is a generalization of
L</hashy> below.

Accepts all arguments as L<Data::Tubes::Util/generalized_hash>, with the
same default values except for C<default_key> that is set to the empty
string (as opposed to not being defined). This means that stand-alone
values will always be accepted. This setting is in line with L</hashy>
and has been set for backwards/mutual compatibility.

The following arguements are recognised too:

=over

=item C<defaults>

a hash reference with default values for the output;

=item C<input>

name of the input field, defaults to C<raw>;

=item C<name>

name of the tube, useful for debugging. Defaults to C<parse ghashy>;

=item C<output>

name of the output field, defaults to C<structured>;

=back

=item B<< hashy >>

=item B<< parse_hashy >>

   my $tube = hashy(%args); # OR
   my $tube = hashy(\%args);

parse the input text as a hash. The algorithm used is the same as
L<Data::Tubes::Util/metadata>.

=over

=item C<chunks_separator>

character used to divide chunks in the input;

=item C<default_key>

the default key to be used when a key is not present in a chunk;

=item C<defaults>

a hash reference with default values for the output;

=item C<input>

name of the input field, defaults to C<raw>;

=item C<key_value_separator>

character used to divide the key from the value in a chunk;

=item C<name>

name of the tube, useful for debugging. Defaults to C<parse hashy>;

=item C<output>

name of the output field, defaults to C<structured>;

=back

This tube factory is strict in what accepts as inputs, in that the
separators MUST be single characters and there is no escaping mechanism.
If you need something more flexible, see L</ghashy> above.

=item B<< single >>

=item B<< parse_single >>

   my $tube = single(%args); # OR
   my $tube = single(\%args);

consider the input text as already parsed, and generate as output a hash
reference where the text is associated to a key.

=over

=item C<input>

name of the input field, defaults to C<raw>;

=item C<key>

key to use for associating the input text;

=item C<name>

name of the tube, useful for debugging;

=item C<output>

name of the output field, defaults to C<structured>;

=back

=back

=head1 BUGS AND LIMITATIONS

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

=head1 AUTHOR

Flavio Poletti <polettix@cpan.org>

=head1 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.

=cut
