| Subject: | Guide users toward more appropriate use of Text-CSV elements in constructor |
In https://stackoverflow.com/questions/49471465/use-of-uninitialized-in-textcsvhashify/49471620#49471620 (also the subject of https://rt.cpan.org/Ticket/Display.html?id=125384), the user confused matters by, in one version of the program, providing the constructor with an 'eol' element:
#####
'eol' => '\r\n',
#####
The user reported getting this error message:
#####
'_ERROR_DIAG' => 'EOF - End of data in parsing input stream'
#####
I haven't been able to reproduce that error. However, it appears that the user provided new() with vastly more elements than were needed to get the job done.
#####
$obj = Text::CSV::Hashify->new( {
file => $csvfile,
format => 'hoh', # hash of hashes, which is default
key => 'asset', # corrected typo
eol => '\r\n',
sep_char => ',',
quote_char => '',
escape_char => '',
binary => 1,
decode_utf8 => 0,
auto_diag => 1,
diag_verbose => 1,
blank_is_undef => 0,
empty_is_undef => 0,
allow_whitespace => 1,
allow_loose_quotes => 1,
allow_loose_escapes => 1,
allow_unquoted_escape => 1,
always_quote => 1,
quote_empty => 1,
quote_space => 1,
escape_null => 1,
quote_binary => 1,
keep_meta_info => 1,
verbatim => 0,
} );
#####
AFAICT, the only elements the user needed were 'file', 'format' and 'key'. While I don't know the user's motivation for this, there is an aspect to the Text::CSV::Hashify documentation that might have encouraged it. Both the SYNOPSIS and the documentation for new() show:
#####
$obj = Text::CSV::Hashify->new( {
file => '/path/to/file.csv',
format => 'hoh', # hash of hashes, which is default
key => 'id', # needed except when format is 'aoh'
max_rows => 20, # number of records to read; defaults to all
... # other key-value pairs possible for Text::CSV
} );
#####
This might be interpreted as: "Go browse through the Text::CSV documentation and add as many elements as you want." But many of the arguments passable to Text::CSV are intended for *writing* CSV files. Text::CSV::Hashify, in contrast, is *only* intended for *reading* CSV files. Hence, a user must be selective in passing extra elements to new().
'eol', in particular, is primarily intended for writing CSV and is almost certainly inappropriate for this module. The Text::CSV documentation states:
#####
eol
my $csv = Text::CSV->new ({ eol => $/ });
$csv->eol (undef);
my $eol = $csv->eol;
The end-of-line string to add to rows for "print" or the record separator for "getline".
When not passed in a parser instance, the default behavior is to accept "\n", "\r", and "\r\n", so it is probably safer to not specify "eol" at all. Passing "undef" or the empty string behave the same.
#####
Make this module's documentation be more emphatic with respect to the need for selectivity when Text::CSV elements in new().