view release on metacpan or  search on metacpan

lib/Data/TableReader.pm  view on Meta::CPAN

set it to a coderef such as:

  my @messages;
  sub { my ($level, $message)= @_;
    push @messages, [ $level, $message ]
      if grep { $level eq $_ } qw( info warn error );
  };

for a simple way to capture the messages without involving a logging module.
And for extra convenience, you can set it to an arrayref which will receive
any message that would otherwise have gone to 'warn' or 'error'.

=head1 METHODS

=head2 detect_input_format

   my ($decoder_class, @args)= $tr->detect_input_format(\%hints);
   my ($decoder_class, @args)= $tr->detect_input_format( $filename, $head_of_file );

This is used internally to detect the format of a file, but you can call it manually if you
like.  The following hints can be supplied as a hashref:

  { http_headers => ...,  # hashref or various objects representing HTTP headers
    content_type => ...,  # a MIME content-type, optional charset
	 charset      => ...,  # a character set, as seen in charset=X on a MIME type
    filename     => ...,  # filename, using file extension to guess content-type
	 content_head => ...,  # the first block(s) of the file, to probe magic numbers
	 content_ofs  => ...,  # a byte offset from which the input file should be read
  }

Missing hints will be pulled from L</input> if possible, updating the supplied hashref.
The two-argument form was the previous calling convention, and doesn't provide a way to retrieve
the generated hint values.

The return value is the best guess of module name and constructor arguments that
should be used to parse the file.  However, this doesn't guarantee such module actually exists
or is installed; it might just echo the file extension back to you.  (which could be useful if
you write your own Decoder subclass with that name)

On failure, it returns an empty list.

=head2 detect_input_charset

   my $charset= $tr->detect_input_charset(\%hints);

This is used internally to detect the text encoding of a file, but you can call it manually if
you like.  The following hints can be supplied as a hashref:

  { charset      => ...,  # a character set, as seen in charset=X on a MIME type
	 content_head => ...,  # the first block(s) of the file
	 content_ofs  => ...,  # byte offset from which detection should start
  }

Missing hints will be pulled from L</input> if possible, modifying the supplied hashref.

The return value is the best guess of C<charset> based on the content.  If the content can't be
read, or isn't conclusive, this returns C<undef>.  If successful, the C<charset> is stored into
C<< $hints->{charset} >> overwriting any previous value, though it doesn't clear a previously
set C<charset> hint on failure.

If the content started with a byte-order-mark (BOM) the length of the BOM will be added to
C<< $hints->{content_ofs} >>.  Note that this means you shouldn't call C<detect_input_charset>
twice without resetting C<content_ofs> inbetween.

=head2 find_table

  if ($tr->find_table) { ... }

Search through the input for the beginning of the records, identified by a header row matching
the various constraints defined in L</fields>.  If L</header_row_at> is C<undef>, then this does
nothing and assumes success.

Returns a boolean of whether it succeeded.  This method does I<not> C<croak> on failure like
L</iterator> does, on the assumption that you want to handle them gracefully.
All diagnostics about the search are logged via L</log>, but also reported in
L</table_search_results>.

=head2 field_map

Build a hashref of C<< { $field_name => $col_idx_or_arrayref } >>  for the current L</col_map>.
If the field is defined as an array field, the value will be an arrayref (even if only found in
one column).  Otherwise, the value is a simple scalar of the column index.

=head2 iterator

  my $iter= $tr->iterator;
  while (my $rec= $iter->()) { ... }

Create an iterator.  If the table has not been located, then find it and C<croak> if it
can't be found.  Depending on the decoder and input filehandle, you might only be able to
have one instance of the iterator at a time.

The iterator derives from L<Data::TableReader::Iterator> but also has a method "all" which
returns all records in an arrayref.

  my $records= $tr->iterator->all;

=head1 THANKS

Portions of this software were funded by
L<Ellis, Partners in Management Solutions|http://www.epmsonline.com/>
and L<Candela Corporation|https://www.candelacorp.com/>.

=head1 AUTHOR

Michael Conrad <mike@nrdvana.net>

=head1 CONTRIBUTORS

=for stopwords Christian Walde Étienne Mollier Michael Conrad

=over 4

=item *

Christian Walde <walde.christian@gmail.com>

=item *

Étienne Mollier <emollier@debian.org>