Iterator

NAME

Text::CSV_PP::Iterator - Provide fetchrow_hashref() for CSV files

Synopsis

	use Text::CSV_PP::Iterator;

	my($parser) = Text::CSV_PP::Iterator -> new
	({
		column_names	=> [qw/One Two Three Four Five/],
		file_name		=> 'no.heading.in.file.csv',
	});

	my($hashref);

	while ($hashref = $parser -> fetchrow_hashref() )
	{
		print map{"$_ => $$hashref{$_}. "} sort keys %$hashref;
		print "\n";
	}

Description

Text::CSV_PP::Iterator is a pure Perl module.

It is a convenient wrapper around Text::CSV_PP. Points of interest:

	o Text::CSV_PP::Iterator reads the file for you, using Iterator::IO.
		Warning: Iterator::IO V 0.02 has 3 bugs in it, where it does not
		call throw() properly. I've reported this via http://rt.cpan.org
	o All of Text::CSV_PP's new() parameters are supported by the fact
		that Text::CSV_PP::Iterator subclasses Text::CSV_PP
	o All data is returned as a hashref just like DBI's fetchrow_hashref(),
		using Text::CSV_PP::Iterator's only method, fetchrow_hashref()
	o The module reads the column headers from the first record in the file, or ...
	o The column headers can be passed in to new() if the file has none
	o Non-existent file errors throw the exception Iterator::X::IO_Error,
		which stringifies to a nice error message if you don't catch it
	o EOF returns undef to allow this neat construct:
		while ($hashref = $parser -> fetchrow_hashref() ){...}
	o Dependencies:
	- Iterator::IO
	- Text::CSV_PP
	o Example code: t/test.t demonstrates:
	- How to call fetchrow_hashref in isolation and in a loop
	- How to call fetchrow_hashref in eval{...} and catch exceptions

Distributions

This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.

See http://savage.net.au/Perl-modules.html for details.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.

Constructor and initialization

new(...) returns a Text::CSV_PP::Iterator object.

This is the class's contructor.

Usage: Text::CSV_PP::Iterator -> new({...}).

This method takes a hashref of parameters. Only the file_name parameter is mandatory.

For each parameter you wish to use, call new as new({param_1 => value_1, ...}).

• file_name

  This is the name of the file that this module will read for you.

  One record will be returned each time you call fetchrow_hashref().

  There is no default value for file_name.

  This parameter is mandatory.

Method: fetchrow_hashref()

Returns an hashref ref of column data from the next record in the input file.

Example code

See the file t/test.t in the distro.

Required Modules

• Iterator::IO
• Text::CSV_PP

Similar Modules

There are quite a few modules on CPAN which offer ways of processing CSV (and similar) files:

• Text::CSV

  The original, and pure-Perl, way of doing things.

  The major drawback is the lack of options to new().

• Text::CSV_PP

  A pure-Perl version of the next module, and the parent of my module.

  Allows the column separator to be surrounded by tabs or spaces. Nice.

  Does not allow the column headers to be provided to new().

• Text::CSV_XS

  A compiled module, with many options.

  Does not allow the column separator to be surrounded by tabs or spaces.

  Does not allow the column headers to be provided to new().

  I always use this module if I have a compiler available. But that was before I wrote the current module.

• Text::CSV::LibCSV

  Requires the external, compiled, library libcsv, which is written in C.

  I did not test this module.

• Text::CSV::Simple

  This is a wrapper around the compiled code in Text::CSV_XS.

  I did not test this module.

• Text::LooseCSV

  I did not test this module.

• Text::RecordParser

  This module has a fake META.yml, which does not list any dependencies. However, when you try to install it, you get:

  	- ERROR: Test::Exception is not installed
  	- ERROR: IO::Scalar is not installed
  	- ERROR: Class::Accessor is not installed
  	- ERROR: Readonly is not installed
  	- ERROR: List::MoreUtils is not installed
  	* Optional prerequisite Text::TabularDisplay is not installed
  	* Optional prerequisite Readonly::XS is not installed

  I did not test this module.

• Tie::CSV_File

  A different way of viewing CSV files.

  This is a wrapper around the compiled code in Text::CSV_XS.

  It supports some of the same options as Text::CSV_XS.

  I did not test this module.

• Text::xSV

  This module has a huge, and I do mean huge, number of methods. If only they worked...

  Unfortunately, in one set of tests this module kept overwriting my input file, which is very nasty.

  In another set, the method print_header() did not work. Now, that method calls format_header(), which looks for the field $self->{header}, but you have to have called read_header(), which does not set $self->{header}. Rather read_header() is aliased to bind_header(), which calls bind_fields(), which does not set $self->{header} either. It sets $self->{field_pos}. Oh, dear. Forget it.

Changes

See Changes.txt.

Author

Text::CSV_PP::Iterator was written by Ron Savage <ron@savage.net.au> in 2007.

Home page: http://savage.net.au/index.html

Copyright

Australian copyright © 2007, Ron Savage. All rights reserved.

	All Programs of mine are 'OSI Certified Open Source Software';
	you can redistribute them and/or modify them under the terms of
	The Artistic License, a copy of which is available at:
	http://www.opensource.org/licenses/index.html