Hello community, here is the log from the commit of package perl-Text-CSV_XS for openSUSE:Factory checked in at Tue May 31 14:26:31 CEST 2011.
-------- --- perl-Text-CSV_XS/perl-Text-CSV_XS.changes 2011-03-31 10:52:47.000000000 +0200 +++ /mounts/work_src_done/STABLE/perl-Text-CSV_XS/perl-Text-CSV_XS.changes 2011-05-16 10:55:15.000000000 +0200 @@ -1,0 +2,7 @@ +Mon May 16 08:47:46 UTC 2011 - co...@opensuse.org + +- updated to 0.82 + * Doc fix (RT#66905, Peter Newman) + * Documentation overhaul (pod links) + +------------------------------------------------------------------- calling whatdependson for head-i586 Old: ---- Text-CSV_XS-0.81.tgz New: ---- Text-CSV_XS-0.82.tgz ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ perl-Text-CSV_XS.spec ++++++ --- /var/tmp/diff_new_pack.spkOS9/_old 2011-05-31 14:25:53.000000000 +0200 +++ /var/tmp/diff_new_pack.spkOS9/_new 2011-05-31 14:25:53.000000000 +0200 @@ -18,23 +18,17 @@ Name: perl-Text-CSV_XS -Version: 0.81 +Version: 0.82 Release: 1 License: GPL+ or Artistic %define cpan_name Text-CSV_XS Summary: comma-separated values manipulation routines Url: http://search.cpan.org/dist/Text-CSV_XS/ Group: Development/Libraries/Perl -#Source: http://www.cpan.org/authors/id/H/HM/HMBRAND/Text-CSV_XS-%{version}.tgz -Source: %{cpan_name}-%{version}.tgz +Source: http://www.cpan.org/authors/id/H/HM/HMBRAND/%{cpan_name}-%{version}.tgz BuildRoot: %{_tmppath}/%{name}-%{version}-build BuildRequires: perl BuildRequires: perl-macros -BuildRequires: perl(Config) -BuildRequires: perl(DynaLoader) -BuildRequires: perl(IO::Handle) -Requires: perl(DynaLoader) -Requires: perl(IO::Handle) %{perl_requires} %description @@ -46,71 +40,9 @@ user-specified characters as delimiters, separators, and escapes so it is perhaps better called ASV (anything separated values) rather than just CSV. -Embedded newlines - *Important Note*: The default behavior is to only accept ASCII - characters. This means that fields can not contain newlines. If your - data contains newlines embedded in fields, or characters above 0x7e - (tilde), or binary data, you *must* set 'binary => 1' in the call to - 'new'. To cover the widest range of parsing options, you will always - want to set binary. - - But you still have the problem that you have to pass a correct line to - the 'parse' method, which is more complicated from the usual point of - usage: - - my $csv = Text::CSV_XS->new ({ binary => 1, eol => $/ }); - while (<>) { # WRONG! - $csv->parse ($_); - my @fields = $csv->fields (); - - will break, as the while might read broken lines, as that does not care - about the quoting. If you need to support embedded newlines, the way to - go is either - - my $csv = Text::CSV_XS->new ({ binary => 1, eol => $/ }); - while (my $row = $csv->getline (*ARGV)) { - my @fields = @$row; - - or, more safely in perl 5.6 and up - - my $csv = Text::CSV_XS->new ({ binary => 1, eol => $/ }); - open my $io, "<", $file or die "$file: $!"; - while (my $row = $csv->getline ($io)) { - my @fields = @$row; - -Unicode (UTF8) - On parsing (both for 'getline' and 'parse'), if the source is marked - being UTF8, then all fields that are marked binary will also be be - marked UTF8. - - For complete control over encoding, please use Text::CSV::Encoded: - - use Text::CSV::Encoded; - my $csv = Text::CSV::Encoded->new ({ - encoding_in => "iso-8859-1", # the encoding comes into Perl - encoding_out => "cp1252", # the encoding comes out of Perl - }); - - $csv = Text::CSV::Encoded->new ({ encoding => "utf8" }); - # combine () and print () accept *literally* utf8 encoded data - # parse () and getline () return *literally* utf8 encoded data - - $csv = Text::CSV::Encoded->new ({ encoding => undef }); # default - # combine () and print () accept UTF8 marked data - # parse () and getline () return UTF8 marked data - - On combining ('print' and 'combine'), if any of the combining fields - was marked UTF8, the resulting string will be marked UTF8. Note however - that all fields 'before' the first field that was marked UTF8 and - contained 8-bit characters that were not upgraded to UTF8, these will - be bytes in the resulting string too, causing errors. If you pass data - of different encoding, or you don't know if there is different - encoding, force it to be upgraded before you pass them on: - - $csv->print ($fh, [ map { utf8::upgrade (my $x = $_); $x } @data ]); - %prep %setup -q -n %{cpan_name}-%{version} +find . -type f -print0 | xargs -0 chmod 644 %build %{__perl} Makefile.PL INSTALLDIRS=vendor OPTIMIZE="%{optflags}" @@ -128,7 +60,7 @@ %{__rm} -rf %{buildroot} %files -f %{name}.files -%defattr(644,root,root,755) -%doc ChangeLog README +%defattr(-,root,root,755) +%doc ChangeLog examples README %changelog ++++++ Text-CSV_XS-0.81.tgz -> Text-CSV_XS-0.82.tgz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Text-CSV_XS-0.81/CSV_XS.pm new/Text-CSV_XS-0.82/CSV_XS.pm --- old/Text-CSV_XS-0.81/CSV_XS.pm 2011-02-04 14:10:06.000000000 +0100 +++ new/Text-CSV_XS-0.82/CSV_XS.pm 2011-05-01 17:21:25.000000000 +0200 @@ -7,7 +7,6 @@ # This program is free software; you can redistribute it and/or # modify it under the same terms as Perl itself. -################################################################################ # HISTORY # # Written by: @@ -18,8 +17,6 @@ # # Extended and Remodelled by: # H.Merijn Brand (h.m.br...@xs4all.nl) -# -############################################################################ require 5.005; @@ -30,7 +27,7 @@ use Carp; use vars qw( $VERSION @ISA ); -$VERSION = "0.81"; +$VERSION = "0.82"; @ISA = qw( DynaLoader ); bootstrap Text::CSV_XS $VERSION; @@ -603,7 +600,7 @@ my @rows; my $csv = Text::CSV_XS->new ({ binary => 1 }) or - die "Cannot use CSV: ".Text::CSV->error_diag (); + die "Cannot use CSV: ".Text::CSV_XS->error_diag (); open my $fh, "<:encoding(utf8)", "test.csv" or die "test.csv: $!"; while (my $row = $csv->getline ($fh)) { $row->[2] =~ m/pattern/ or next; # 3rd field should match @@ -632,12 +629,11 @@ B<Important Note>: The default behavior is to only accept ASCII characters. This means that fields can not contain newlines. If your data contains newlines embedded in fields, or characters above 0x7e (tilde), or binary -data, you *must* set C<< binary => 1 >> in the call to C<new>. To cover +data, you B<I<must>> set C<< binary => 1 >> in the call to L</new>. To cover the widest range of parsing options, you will always want to set binary. But you still have the problem that you have to pass a correct line to the -C<parse> method, which is more complicated from the usual point of -usage: +L</parse> method, which is more complicated from the usual point of usage: my $csv = Text::CSV_XS->new ({ binary => 1, eol => $/ }); while (<>) { # WRONG! @@ -659,37 +655,37 @@ while (my $row = $csv->getline ($io)) { my @fields = @$row; -=head2 Unicode (UTF8) +=head2 Unicode -On parsing (both for C<getline> and C<parse>), if the source is marked +On parsing (both for L</getline> and L</parse>), if the source is marked being UTF8, then all fields that are marked binary will also be be marked UTF8. For complete control over encoding, please use Text::CSV::Encoded: - use Text::CSV::Encoded; - my $csv = Text::CSV::Encoded->new ({ - encoding_in => "iso-8859-1", # the encoding comes into Perl - encoding_out => "cp1252", # the encoding comes out of Perl - }); - - $csv = Text::CSV::Encoded->new ({ encoding => "utf8" }); - # combine () and print () accept *literally* utf8 encoded data - # parse () and getline () return *literally* utf8 encoded data - - $csv = Text::CSV::Encoded->new ({ encoding => undef }); # default - # combine () and print () accept UTF8 marked data - # parse () and getline () return UTF8 marked data - -On combining (C<print> and C<combine>), if any of the combining fields was -marked UTF8, the resulting string will be marked UTF8. Note however that -all fields C<before> the first field that was marked UTF8 and contained -8-bit characters that were not upgraded to UTF8, these will be bytes in the -resulting string too, causing errors. If you pass data of different -encoding, or you don't know if there is different encoding, force it to be -upgraded before you pass them on: + use Text::CSV::Encoded; + my $csv = Text::CSV::Encoded->new ({ + encoding_in => "iso-8859-1", # the encoding comes into Perl + encoding_out => "cp1252", # the encoding comes out of Perl + }); + + $csv = Text::CSV::Encoded->new ({ encoding => "utf8" }); + # combine () and print () accept *literally* utf8 encoded data + # parse () and getline () return *literally* utf8 encoded data + + $csv = Text::CSV::Encoded->new ({ encoding => undef }); # default + # combine () and print () accept UTF8 marked data + # parse () and getline () return UTF8 marked data + +On combining (L</print> and L</combine>), if any of the combining fields +was marked UTF8, the resulting string will be marked UTF8. Note however +that all fields I<before> the first field that was marked UTF8 and +contained 8-bit characters that were not upgraded to UTF8, these will be +bytes in the resulting string too, causing errors. If you pass data of +different encoding, or you don't know if there is different encoding, force +it to be upgraded before you pass them on: - $csv->print ($fh, [ map { utf8::upgrade (my $x = $_); $x } @data ]); + $csv->print ($fh, [ map { utf8::upgrade (my $x = $_); $x } @data ]); =head1 SPECIFICATION @@ -780,19 +776,25 @@ =head1 FUNCTIONS -=head2 version () +=head2 version +X<version> (Class method) Returns the current module version. -=head2 new (\%attr) +=head2 new +X<new> (Class method) Returns a new instance of Text::CSV_XS. The objects -attributes are described by the (optional) hash ref C<\%attr>. Currently -the following attributes are available: +attributes are described by the (optional) hash ref C<\%attr>. + + my $csv = Text::CSV_XS->new ({ attributes ... }); + +Currently the following attributes are available: =over 4 =item eol +X<eol> An end-of-line string to add to rows. C<undef> is replaced with an empty string. The default is C<$\>. Common values for C<eol> are C<"\012"> (Line @@ -800,11 +802,12 @@ 7 (ASCII) characters. If both C<$/> and C<eol> equal C<"\015">, parsing lines that end on only a -Carriage Return without Line Feed, will be C<parse>d correct. Line endings, +Carriage Return without Line Feed, will be L</parse>d correct. Line endings, whether in C<$/> or C<eol>, other than C<undef>, C<"\n">, C<"\r\n">, or C<"\r"> are not (yet) supported for parsing. =item sep_char +X<sep_char> The char used for separating fields, by default a comma. (C<,>). Limited to a single-byte character, usually in the range from 0x20 (space) to 0x7e @@ -813,9 +816,10 @@ The separation character can not be equal to the quote character. The separation character can not be equal to the escape character. -See also CAVEATS +See also L</CAVEATS> =item allow_whitespace +X<allow_whitespace> When this option is set to true, whitespace (TAB's and SPACE's) surrounding the separation character is removed when parsing. If either TAB or SPACE is @@ -824,7 +828,7 @@ So lines like: - 1 , "foo" , bar , 3 , zapp + 1 , "foo" , bar , 3 , zapp are now correctly parsed, even though it violates the CSV specs. @@ -841,6 +845,7 @@ even if the original line was perfectly sane CSV. =item blank_is_undef +X<blank_is_undef> Under normal circumstances, CSV data makes no distinction between quoted- and unquoted empty fields. They both end up in an empty string field once @@ -861,6 +866,7 @@ ("1", "", undef, " ", "2") =item empty_is_undef +X<empty_is_undef> Going one step further than C<blank_is_undef>, this attribute converts all empty fields to undef, so @@ -875,6 +881,7 @@ that are empty after stripping allowed whitespace. YMMV. =item quote_char +X<quote_char> The char used for quoting fields containing blanks, by default the double quote character (C<">). A value of undef suppresses quote chars. (For @@ -884,6 +891,7 @@ The quote character can not be equal to the separation character. =item allow_loose_quotes +X<allow_loose_quotes> By default, parsing fields that have C<quote_char> characters inside an unquoted field, like @@ -907,6 +915,7 @@ making sure that the C<escape_char> is I<not> equal to C<quote_char>. =item escape_char +X<escape_char> The character used for escaping certain characters inside quoted fields. Limited to a single-byte character, usually in the range from 0x20 (space) @@ -916,7 +925,7 @@ in other words, the same as the default C<quote_char>. This means that doubling the quote mark in a field escapes it: - "foo","bar","Escape ""quote mark"" with two ""quote marks""","baz" + "foo","bar","Escape ""quote mark"" with two ""quote marks""","baz" If you change the default quote_char without changing the default escape_char, the escape_char will still be the quote mark. If instead you @@ -926,6 +935,7 @@ The escape character can not be equal to the separation character. =item allow_loose_escapes +X<allow_loose_escapes> By default, parsing fields that have C<escape_char> characters that escape characters that do not need to be escaped, like: @@ -938,6 +948,7 @@ sequences equal. =item binary +X<binary> If this attribute is TRUE, you may use binary characters in quoted fields, including line feeds, carriage returns and NULL bytes. (The latter must be @@ -949,13 +960,14 @@ setting C<{ binary => 1 }> is still a wise option. =item types +X<types> -A set of column types; this attribute is immediately passed to the I<types> -method below. You must not set this attribute otherwise, except for using -the I<types> method. For details see the description of the I<types> method -below. +A set of column types; this attribute is immediately passed to the L</types> +method. You must not set this attribute otherwise, except for using the +L</types> method. =item always_quote +X<always_quote> By default the generated fields are quoted only, if they need to, for example, if they contain the separator. If you set this attribute to a TRUE @@ -964,6 +976,7 @@ Text::CSV_XS. :-) =item quote_space +X<quote_space> By default, a space in a field would trigger quotation. As no rule exists this to be forced in CSV, nor any for the opposite, the default is true for @@ -971,21 +984,24 @@ attribute to 0. =item quote_null +X<quote_null> By default, a NULL byte in a field would be escaped. This attribute enables you to treat the NULL byte as a simple binary character in binary mode (the -C<{ binary => 1 }> is set). The default is true. You can prevent NULL +C<< { binary => 1 } >> is set). The default is true. You can prevent NULL escapes by setting this attribute to 0. =item keep_meta_info +X<keep_meta_info> By default, the parsing of input lines is as simple and fast as possible. However, some parsing information - like quotation of the original field - is lost in that process. Set this flag to true to be able to retrieve that -information after parsing with the methods C<meta_info>, C<is_quoted>, and -C<is_binary> described below. Default is false. +information after parsing with the methods L</meta_info>, L</is_quoted>, +and L</is_binary> described below. Default is false. =item verbatim +X<verbatim> This is a quite controversial attribute to set, but it makes hard things possible. @@ -995,12 +1011,12 @@ special when this flag is set, and be dealt with as being ordinary binary characters. This will ease working with data with embedded newlines. -When C<verbatim> is used with C<getline>, C<getline> auto-chomp's every +When C<verbatim> is used with L</getline>, L</getline> auto-chomp's every line. Imagine a file format like - M^^Hans^Janssen^Klas 2\n2A^Ja^11-06-2007#\r\n + M^^Hans^Janssen^Klas 2\n2A^Ja^11-06-2007#\r\n where, the line ending is a very specific "#\r\n", and the sep_char is a ^ (caret). None of the fields is quoted, but embedded binary data is likely @@ -1018,8 +1034,9 @@ anymore, and getline () chomps line endings on reading. =item auto_diag +X<auto_diag> -Set to true will cause C<error_diag> to be automatically be called in void +Set to true will cause L</error_diag> to be automatically be called in void context upon errors. In case of error C<2012 - EOF>, this call will be void. @@ -1067,82 +1084,85 @@ stream. If however, you want to create a new stream using the available CSV object, there is no harm in changing them. -If the C<new> constructor call fails, it returns C<undef>, and makes the -fail reason available through the C<error_diag> method. +If the L</new> constructor call fails, it returns C<undef>, and makes the +fail reason available through the L</error_diag> method. $csv = Text::CSV_XS->new ({ ecs_char => 1 }) or die "".Text::CSV_XS->error_diag (); -C<error_diag> will return a string like +L</error_diag> will return a string like "INI - Unknown attribute 'ecs_char'" =head2 print +X<print> $status = $csv->print ($io, $colref); -Similar to C<combine () + string () + print>, but more efficient. It +Similar to L</combine> + L</string> + L</print>, but way more efficient. It expects an array ref as input (not an array!) and the resulting string is not really created, but immediately written to the I<$io> object, typically -an IO handle or any other object that offers a I<print> method. Note, this +an IO handle or any other object that offers a L</print> method. Note, this implies that the following is wrong in perl 5.005_xx and older: open FILE, ">", "whatever"; $status = $csv->print (\*FILE, $colref); +For performance reasons the print method does not create a result string. +In particular the L</string>, L</status>, L</fields>, and L</error_input> +methods are meaningless after executing this method. + as in perl 5.005 and older, the glob C<\*FILE> is not an object, thus it does not have a print method. The solution is to use an IO::File object or to hide the glob behind an IO::Wrap object. See L<IO::File> and L<IO::Wrap> for details. -For performance reasons the print method does not create a result string. -In particular the I<$csv-E<gt>string>, I<$csv-E<gt>status>, I<$csv->fields> -and I<$csv-E<gt>error_input> methods are meaningless after executing this -method. - =head2 combine +X<combine> $status = $csv->combine (@columns); This object function constructs a CSV string from the arguments, returning success or failure. Failure can result from lack of arguments or an -argument containing an invalid character. Upon success, C<string> can be +argument containing an invalid character. Upon success, L</string> can be called to retrieve the resultant CSV string. Upon failure, the value -returned by C<string> is undefined and C<error_input> can be called to +returned by L</string> is undefined and L</error_input> can be called to retrieve an invalid argument. =head2 string +X<string> $line = $csv->string (); -This object function returns the input to C<parse> or the resultant CSV -string of C<combine>, whichever was called more recently. +This object function returns the input to L</parse> or the resultant CSV +string of L</combine>, whichever was called more recently. =head2 getline +X<getline> $colref = $csv->getline ($io); -This is the counterpart to print, like parse is the counterpart to combine: -It reads a row from the IO object $io using $io->getline () and parses this -row into an array ref. This array ref is returned by the function or undef -for failure. +This is the counterpart to L</print>, like L</parse> is the counterpart to +L</combine>: It reads a row from the IO object using C<< $io->getline >> +and parses this row into an array ref. This array ref is returned by the +function or undef for failure. -When fields are bound with C<bind_columns>, the return value is a reference -to an empty list. +When fields are bound with L</bind_columns>, the return value is a +reference to an empty list. -The I<$csv-E<gt>string>, I<$csv-E<gt>fields> and I<$csv-E<gt>status> -methods are meaningless, again. +The L</string>, L</fields>, and L</status> methods are meaningless, again. =head2 getline_all +X<getline_all> $arrayref = $csv->getline_all ($io); $arrayref = $csv->getline_all ($io, $offset); $arrayref = $csv->getline_all ($io, $offset, $length); -This will return a reference to a list of C<getline ($io)> results. In this -call, C<keep_meta_info> is disabled. If C<$offset> is negative, as with -C<splice>, only the last C<abs ($offset)> records of C<$io> are taken into -consideration. +This will return a reference to a list of L<getline ($io)|/getline> results. +In this call, C<keep_meta_info> is disabled. If C<$offset> is negative, as +with C<splice>, only the last C<abs ($offset)> records of C<$io> are taken +into consideration. Given a CSV file with 10 lines: @@ -1158,84 +1178,92 @@ 6..7 $csv->getline_all ($io, -4, 2) # first 2 of last 4 rows =head2 parse +X<parse> $status = $csv->parse ($line); This object function decomposes a CSV string into fields, returning success or failure. Failure can result from a lack of argument or the given CSV -string is improperly formatted. Upon success, C<fields> can be called to +string is improperly formatted. Upon success, L</fields> can be called to retrieve the decomposed fields . Upon failure, the value returned by -C<fields> is undefined and C<error_input> can be called to retrieve the +L</fields> is undefined and L</error_input> can be called to retrieve the invalid argument. -You may use the I<types> method for setting column types. See the +You may use the L</types> method for setting column types. See L</types>' description below. =head2 getline_hr +X<getline_hr> -The C<getline_hr> and C<column_names> methods work together to allow you to -have rows returned as hashrefs. You must call C<column_names> first to +The L</getline_hr> and L</column_names> methods work together to allow you +to have rows returned as hashrefs. You must call L</column_names> first to declare your column names. $csv->column_names (qw( code name price description )); $hr = $csv->getline_hr ($io); print "Price for $hr->{name} is $hr->{price} EUR\n"; -C<getline_hr> will croak if called before C<column_names>. +L</getline_hr> will croak if called before L</column_names>. =head2 getline_hr_all +X<getline_hr_all> $arrayref = $csv->getline_hr_all ($io); $arrayref = $csv->getline_hr_all ($io, $offset); $arrayref = $csv->getline_hr_all ($io, $offset, $length); -This will return a reference to a list of C<getline_hr ($io)> results. In -this call, C<keep_meta_info> is disabled. +This will return a reference to a list of L<getline_hr ($io)|/getline_hr> +results. In this call, C<keep_meta_info> is disabled. =head2 column_names +X<column_names> -Set the keys that will be used in the C<getline_hr> calls. If no keys +Set the keys that will be used in the L</getline_hr> calls. If no keys (column names) are passed, it'll return the current setting. -C<column_names> accepts a list of scalars (the column names) or a single -array_ref, so you can pass C<getline> +L</column_names> accepts a list of scalars (the column names) or a single +array_ref, so you can pass L</getline> - $csv->column_names ($csv->getline ($io)); + $csv->column_names ($csv->getline ($io)); -C<column_names> does B<no> checking on duplicates at all, which might lead +L</column_names> does B<no> checking on duplicates at all, which might lead to unwanted results. Undefined entries will be replaced with the string C<"\cAUNDEF\cA">, so - $csv->column_names (undef, "", "name", "name"); - $hr = $csv->getline_hr ($io); + $csv->column_names (undef, "", "name", "name"); + $hr = $csv->getline_hr ($io); -Will set C<$hr->{"\cAUNDEF\cA"}> to the 1st field, C<$hr->{""}> to the 2nd -field, and C<$hr->{name}> to the 4th field, discarding the 3rd field. +Will set C<< $hr->{"\cAUNDEF\cA"} >> to the 1st field, C<< $hr->{""} >> to +the 2nd field, and C<< $hr->{name} >> to the 4th field, discarding the 3rd +field. -C<column_names> croaks on invalid arguments. +L</column_names> croaks on invalid arguments. =head2 bind_columns +X<bind_columns> -Takes a list of references to scalars to store the fields fetched C<getline> -in. When you don't pass enough references to store the fetched fields in, -C<getline> will fail. If you pass more than there are fields to return, the -remaining references are left untouched. - - $csv->bind_columns (\$code, \$name, \$price, \$description); - while ($csv->getline ($io)) { - print "The price of a $name is \x{20ac} $price\n"; - } +Takes a list of references to scalars to store the fields fetched +L</getline> in. When you don't pass enough references to store the fetched +fields in, L</getline> will fail. If you pass more than there are fields to +return, the remaining references are left untouched. + + $csv->bind_columns (\$code, \$name, \$price, \$description); + while ($csv->getline ($io)) { + print "The price of a $name is \x{20ac} $price\n"; + } =head2 eof +X<eof> $eof = $csv->eof (); -If C<parse> or C<getline> was used with an IO stream, this method will +If L</parse> or L</getline> was used with an IO stream, this method will return true (1) if the last call hit end of file, otherwise it will return false (''). This is useful to see the difference between a failure and end of file. =head2 types +X<types> $csv->types (\@tref); @@ -1249,7 +1277,7 @@ Text::CSV_XS::PV ()]); Column types are used only for decoding columns, in other words by the -I<parse> and I<getline> methods. +L</parse> and L</getline> methods. You can unset column types by doing a @@ -1262,49 +1290,54 @@ =over 4 =item IV +X<IV> Set field type to integer. =item NV +X<NV> Set field type to numeric/float. =item PV +X<PV> Set field type to string. =back =head2 fields +X<fields> @columns = $csv->fields (); -This object function returns the input to C<combine> or the resultant -decomposed fields of C successful <parse>, whichever was called more +This object function returns the input to L</combine> or the resultant +decomposed fields of a successful L</parse>, whichever was called more recently. -Note that the return value is undefined after using C<getline>, which does -not fill the data structures returned by C<parse>. +Note that the return value is undefined after using L</getline>, which does +not fill the data structures returned by L</parse>. =head2 meta_info +X<meta_info> @flags = $csv->meta_info (); -This object function returns the flags of the input to C<combine> or the -flags of the resultant decomposed fields of C<parse>, whichever was called +This object function returns the flags of the input to L</combine> or the +flags of the resultant decomposed fields of L</parse>, whichever was called more recently. For each field, a meta_info field will hold flags that tell something about -the field returned by the C<fields> method or passed to the C<combine> +the field returned by the L</fields> method or passed to the L</combine> method. The flags are bit-wise-or'd like: -=over 4 +=over 2 -=item 0x0001 +=item C< >0x0001 The field was quoted. -=item 0x0002 +=item C< >0x0002 The field was binary. @@ -1313,11 +1346,12 @@ See the C<is_***> methods below. =head2 is_quoted +X<is_quoted> - my $quoted = $csv->is_quoted ($column_idx); + my $quoted = $csv->is_quoted ($column_idx); Where C<$column_idx> is the (zero-based) index of the column in the last -result of C<parse>. +result of L</parse>. This returns a true value if the data in the indicated column was enclosed in C<quote_char> quotes. This might be important for data where @@ -1325,48 +1359,53 @@ is explicitly marked as character string data. =head2 is_binary +X<is_binary> - my $binary = $csv->is_binary ($column_idx); + my $binary = $csv->is_binary ($column_idx); Where C<$column_idx> is the (zero-based) index of the column in the last -result of C<parse>. +result of L</parse>. This returns a true value if the data in the indicated column contained any -byte in the range [\x00-\x08,\x10-\x1F,\x7F-\xFF] +byte in the range C<[\x00-\x08,\x10-\x1F,\x7F-\xFF]>. =head2 is_missing +X<is_missing> - my $missing = $csv->is_missing ($column_idx); + my $missing = $csv->is_missing ($column_idx); Where C<$column_idx> is the (zero-based) index of the column in the last -result of C<getline_hr>. +result of L</getline_hr>. - while (my $hr = $csv->getline_hr ($fh)) { - $csv->is_missing (0) and next; # This was an empty line - } + while (my $hr = $csv->getline_hr ($fh)) { + $csv->is_missing (0) and next; # This was an empty line + } -When using C<getline_hr> for parsing, it is impossible to tell if the +When using L</getline_hr> for parsing, it is impossible to tell if the fields are C<undef> because they where not filled in the CSV stream or because they were not read at all, as B<all> the fields defined by -C<column_names> are set in the hash-ref. If you still need to know if all +L</column_names> are set in the hash-ref. If you still need to know if all fields in each row are provided, you should enable C<keep_meta_info> so you can check the flags. =head2 status +X<status> $status = $csv->status (); -This object function returns success (or failure) of C<combine> or C<parse>, -whichever was called more recently. +This object function returns success (or failure) of L</combine> or +L</parse>, whichever was called more recently. =head2 error_input +X<error_input> $bad_argument = $csv->error_input (); This object function returns the erroneous argument (if it exists) of -C<combine> or C<parse>, whichever was called more recently. +L</combine> or L</parse>, whichever was called more recently. =head2 error_diag +X<error_diag> Text::CSV_XS->error_diag (); $csv->error_diag (); @@ -1383,7 +1422,7 @@ If called in list context, it will return the error code and the error message in that order. If the last error was from parsing, the third value returned is a best guess at the location within the line that was being -parsed. It's value is 1-based. See C<examples/csv-check> for how this can +parsed. It's value is 1-based. See F<examples/csv-check> for how this can be used. If called in scalar context, it will return the diagnostics in a single @@ -1391,9 +1430,10 @@ diagnostics message in string context. When called as a class method or a direct function call, the error -diagnostics is that of the last C<new> call. +diagnostics is that of the last L</new> call. =head2 SetDiag +X<SetDiag> $csv->SetDiag (0); @@ -1416,102 +1456,117 @@ =head1 EXAMPLES -Reading a CSV file line by line: +=head2 Reading a CSV file line by line: - my $csv = Text::CSV_XS->new ({ binary => 1 }); - open my $fh, "<", "file.csv" or die "file.csv: $!"; - while (my $row = $csv->getline ($fh)) { - # do something with @$row - } - $csv->eof or $csv->error_diag; - close $fh or die "file.csv: $!"; - -Parsing CSV strings: - - my $csv = Text::CSV_XS->new ({ keep_meta_info => 1, binary => 1 }); - - my $sample_input_string = - qq{"I said, ""Hi!""",Yes,"",2.34,,"1.09","\x{20ac}",}; - if ($csv->parse ($sample_input_string)) { - my @field = $csv->fields; - foreach my $col (0 .. $#field) { - my $quo = $csv->is_quoted ($col) ? $csv->{quote_char} : ""; - printf "%2d: %s%s%s\n", $col, $quo, $field[$col], $quo; - } - } - else { - print STDERR "parse () failed on argument: ", - $csv->error_input, "\n"; - $csv->error_diag (); - } + my $csv = Text::CSV_XS->new ({ binary => 1 }); + open my $fh, "<", "file.csv" or die "file.csv: $!"; + while (my $row = $csv->getline ($fh)) { + # do something with @$row + } + $csv->eof or $csv->error_diag; + close $fh or die "file.csv: $!"; + +=head2 Parsing CSV strings: -An example for creating CSV files using the C<print> method, like in + my $csv = Text::CSV_XS->new ({ keep_meta_info => 1, binary => 1 }); + + my $sample_input_string = + qq{"I said, ""Hi!""",Yes,"",2.34,,"1.09","\x{20ac}",}; + if ($csv->parse ($sample_input_string)) { + my @field = $csv->fields; + foreach my $col (0 .. $#field) { + my $quo = $csv->is_quoted ($col) ? $csv->{quote_char} : ""; + printf "%2d: %s%s%s\n", $col, $quo, $field[$col], $quo; + } + } + else { + print STDERR "parse () failed on argument: ", + $csv->error_input, "\n"; + $csv->error_diag (); + } + +=head2 Printing CSV data + +=head3 The fast way: using L</print> + +An example for creating CSV files using the L</print> method, like in dumping the content of a database ($dbh) table ($tbl) to CSV: - my $csv = Text::CSV_XS->new ({ binary => 1, eol => $/ }); - open my $fh, ">", "$tbl.csv" or die "$tbl.csv: $!"; - my $sth = $dbh->prepare ("select * from $tbl"); - $sth->execute; - $csv->print ($fh, $sth->{NAME_lc}); - while (my $row = $sth->fetch) { - $csv->print ($fh, $row) or $csv->error_diag; - } - close $fh or die "$tbl.csv: $!"; - -or using the slower C<combine> and C<string> methods: - - my $csv = Text::CSV_XS->new; - - open my $csv_fh, ">", "hello.csv" or die "hello.csv: $!"; - - my @sample_input_fields = ( - 'You said, "Hello!"', 5.67, - '"Surely"', '', '3.14159'); - if ($csv->combine (@sample_input_fields)) { - print $csv_fh $csv->string, "\n"; - } - else { - print "combine () failed on argument: ", - $csv->error_input, "\n"; - } - close $csv_fh or die "hello.csv: $!"; - -For more extended examples, see the C<examples/> sub-directory in the -original distribution or the git repository at -http://repo.or.cz/w/Text-CSV_XS.git?a=tree;f=examples. The following files -can be found there: + my $csv = Text::CSV_XS->new ({ binary => 1, eol => $/ }); + open my $fh, ">", "$tbl.csv" or die "$tbl.csv: $!"; + my $sth = $dbh->prepare ("select * from $tbl"); + $sth->execute; + $csv->print ($fh, $sth->{NAME_lc}); + while (my $row = $sth->fetch) { + $csv->print ($fh, $row) or $csv->error_diag; + } + close $fh or die "$tbl.csv: $!"; + +=head3 The slow way: using L</combine> and L</string> + +or using the slower L</combine> and L</string> methods: + + my $csv = Text::CSV_XS->new; + + open my $csv_fh, ">", "hello.csv" or die "hello.csv: $!"; + + my @sample_input_fields = ( + 'You said, "Hello!"', 5.67, + '"Surely"', '', '3.14159'); + if ($csv->combine (@sample_input_fields)) { + print $csv_fh $csv->string, "\n"; + } + else { + print "combine () failed on argument: ", + $csv->error_input, "\n"; + } + close $csv_fh or die "hello.csv: $!"; + +=head2 The examples folder + +For more extended examples, see the F<examples/> (1) sub-directory in the +original distribution or the git repository (2). + + 1. http://repo.or.cz/w/Text-CSV_XS.git?a=tree;f=examples + 2. http://repo.or.cz/w/Text-CSV_XS.git + +The following files can be found there: =over 2 =item parser-xs.pl +X<parser-xs.pl> This can be used as a boilerplate to `fix' bad CSV and parse beyond errors. - $ perl examples/parser-xs.pl bad.csv >good.csv + $ perl examples/parser-xs.pl bad.csv >good.csv =item csv-check +X<csv-check> This is a command-line tool that uses parser-xs.pl techniques to check the CSV file and report on its content. - $ csv-check files/utf8.csv - Checked with examples/csv-check 1.2 using Text::CSV_XS 0.61 - OK: rows: 1, columns: 2 - sep = <,>, quo = <">, bin = <1> + $ csv-check files/utf8.csv + Checked with examples/csv-check 1.5 using Text::CSV_XS 0.81 + OK: rows: 1, columns: 2 + sep = <,>, quo = <">, bin = <1> =item csv2xls +X<csv2xls> A script to convert CSV to Microsoft Excel. This requires L<Date::Calc> and L<Spreadsheet::WriteExcel>. The converter accepts various options and can produce UTF-8 Excel files. =item csvdiff +X<csvdiff> A script that provides colorized diff on sorted CSV files, assuming first line is header and first field is the key. Output options include colorized ANSI escape codes or HTML. - $ csvdiff --html --output=diff.html file1.csv file2.csv + $ csvdiff --html --output=diff.html file1.csv file2.csv =back @@ -1547,19 +1602,19 @@ =item setting meta info -Future extensions might include extending the C<meta_info>, C<is_quoted>, -and C<is_binary> to accept setting these flags for fields, so you can -specify which fields are quoted in the C<combine>/C<string> combination. +Future extensions might include extending the L</meta_info>, L</is_quoted>, +and L</is_binary> to accept setting these flags for fields, so you can +specify which fields are quoted in the L</combine>/L</string> combination. - $csv->meta_info (0, 1, 1, 3, 0, 0); - $csv->is_quoted (3, 1); + $csv->meta_info (0, 1, 1, 3, 0, 0); + $csv->is_quoted (3, 1); =item combined methods -Requests for adding means (methods) that combine C<combine> and C<string> -in a single call will B<not> be honored. Likewise for C<parse> and -C<fields>. Given the trouble with embedded newlines, Using C<getline> and -C<print> instead is the preferred way to go. +Requests for adding means (methods) that combine L</combine> and L</string> +in a single call will B<not> be honored. Likewise for L</parse> and +L</fields>. Given the trouble with embedded newlines, Using L</getline> and +L</print> instead is the preferred way to go. =item Parse the whole file at once @@ -1567,19 +1622,19 @@ returning a list of hashes. Possible extension to this could be to enable a column selection on the call: - my @AoH = $csv->parse_file ($filename, { cols => [ 1, 4..8, 12 ]}); + my @AoH = $csv->parse_file ($filename, { cols => [ 1, 4..8, 12 ]}); Returning something like - [ { fields => [ 1, 2, "foo", 4.5, undef, "", 8 ], - flags => [ ... ], - }, - { fields => [ ... ], - . - }, - ] + [ { fields => [ 1, 2, "foo", 4.5, undef, "", 8 ], + flags => [ ... ], + }, + { fields => [ ... ], + . + }, + ] -Note that C<getline_all> already returns all rows for an open stream, but +Note that L</getline_all> already returns all rows for an open stream, but this will not return flags. =item EBCDIC @@ -1591,11 +1646,11 @@ Opening EBCDIC encode files on ASCII+ systems is likely to succeed using Encode's cp37, cp1047, or posix-bc: - open my $fh, "<:encoding(cp1047)", "ebcdic_file.csv" or die "..."; + open my $fh, "<:encoding(cp1047)", "ebcdic_file.csv" or die "..."; =back -=head1 Release plan +=head2 Release plan No guarantees, but this is what I have in mind right now: @@ -1621,10 +1676,10 @@ If an error occurred, C<$csv->error_diag> can be used to get more information on the cause of the failure. Note that for speed reasons, the internal value is never cleared on success, so using the value returned by -C<error_diag> in normal cases - when no error occurred - may cause +L</error_diag> in normal cases - when no error occurred - may cause unexpected results. -If the constructor failed, the cause can be found using C<error_diag> as a +If the constructor failed, the cause can be found using L</error_diag> as a class method, like C<Text::CSV_XS->error_diag>. C<$csv->error_diag> is automatically called upon error when the contractor @@ -1638,141 +1693,208 @@ =over 2 -=item INI +=item * +INI Initialization error or option conflict. -=item ECR +=item * +ECR Carriage-Return related parse error. -=item EOF +=item * +EOF End-Of-File related parse error. -=item EIQ +=item * +EIQ Parse error inside quotation. -=item EIF +=item * +EIF Parse error inside field. -=item ECB +=item * +ECB Combine error. -=item EHR +=item * +EHR HashRef parse related error. =back +And below should be the complete list of error codes that can be returned: + =over 2 -=item 1001 "INI - sep_char is equal to quote_char or escape_char" +=item * +1001 "INI - sep_char is equal to quote_char or escape_char" +X<1001> The separation character cannot be equal to either the quotation character or the escape character, as that will invalidate all parsing rules. -=item 1002 "INI - allow_whitespace with escape_char or quote_char SP or TAB" +=item * +1002 "INI - allow_whitespace with escape_char or quote_char SP or TAB" +X<1002> Using C<allow_whitespace> when either C<escape_char> or C<quote_char> is equal to SPACE or TAB is too ambiguous to allow. -=item 1003 "INI - \r or \n in main attr not allowed" +=item * +1003 "INI - \r or \n in main attr not allowed" +X<1003> Using default C<eol> characters in either C<sep_char>, C<quote_char>, or C<escape_char> is not allowed. -=item 2010 "ECR - QUO char inside quotes followed by CR not part of EOL" +=item * +2010 "ECR - QUO char inside quotes followed by CR not part of EOL" +X<2010> When C<eol> has been set to something specific, other than the default, like C<"\r\t\n">, and the C<"\r"> is following the B<second> (closing) C<quote_char>, where the characters following the C<"\r"> do not make up the C<eol> sequence, this is an error. -=item 2011 "ECR - Characters after end of quoted field" +=item * +2011 "ECR - Characters after end of quoted field" +X<2011> Sequences like C<1,foo,"bar"baz,2> are not allowed. C<"bar"> is a quoted field, and after the closing quote, there should be either a new-line sequence or a separation character. -=item 2012 "EOF - End of data in parsing input stream" +=item * +2012 "EOF - End of data in parsing input stream" +X<2012> Self-explaining. End-of-file while inside parsing a stream. Can only happen -when reading from streams with C<getline>, as using C<parse> is done on +when reading from streams with L</getline>, as using L</parse> is done on strings that are not required to have a trailing C<eol>. -=item 2021 "EIQ - NL char inside quotes, binary off" +=item * +2021 "EIQ - NL char inside quotes, binary off" +X<2021> Sequences like C<1,"foo\nbar",2> are only allowed when the binary option has been selected with the constructor. -=item 2022 "EIQ - CR char inside quotes, binary off" +=item * +2022 "EIQ - CR char inside quotes, binary off" +X<2022> Sequences like C<1,"foo\rbar",2> are only allowed when the binary option has been selected with the constructor. -=item 2023 "EIQ - QUO character not allowed" +=item * +2023 "EIQ - QUO character not allowed" +X<2023> Sequences like C<"foo "bar" baz",quux> and C<2023,",2008-04-05,"Foo, Bar",\n> will cause this error. -=item 2024 "EIQ - EOF cannot be escaped, not even inside quotes" +=item * +2024 "EIQ - EOF cannot be escaped, not even inside quotes" +X<2024> The escape character is not allowed as last character in an input stream. -=item 2025 "EIQ - Loose unescaped escape" +=item * +2025 "EIQ - Loose unescaped escape" +X<2025> An escape character should escape only characters that need escaping. Allowing the escape for other characters is possible with the C<allow_loose_escape> attribute. -=item 2026 "EIQ - Binary character inside quoted field, binary off" +=item * +2026 "EIQ - Binary character inside quoted field, binary off" +X<2026> Binary characters are not allowed by default. Exceptions are fields that contain valid UTF-8, that will automatically be upgraded is the content is valid UTF-8. Pass the C<binary> attribute with a true value to accept binary characters. -=item 2027 "EIQ - Quoted field not terminated" +=item * +2027 "EIQ - Quoted field not terminated" +X<2027> When parsing a field that started with a quotation character, the field is expected to be closed with a quotation character. When the parsed line is exhausted before the quote is found, that field is not terminated. -=item 2030 "EIF - NL char inside unquoted verbatim, binary off" +=item * +2030 "EIF - NL char inside unquoted verbatim, binary off" +X<2030> -=item 2031 "EIF - CR char is first char of field, not part of EOL" +=item * +2031 "EIF - CR char is first char of field, not part of EOL" +X<2031> -=item 2032 "EIF - CR char inside unquoted, not part of EOL" +=item * +2032 "EIF - CR char inside unquoted, not part of EOL" +X<2032> -=item 2034 "EIF - Loose unescaped quote" +=item * +2034 "EIF - Loose unescaped quote" +X<2034> -=item 2035 "EIF - Escaped EOF in unquoted field" +=item * +2035 "EIF - Escaped EOF in unquoted field" +X<2035> -=item 2036 "EIF - ESC error" +=item * +2036 "EIF - ESC error" +X<2036> -=item 2037 "EIF - Binary character in unquoted field, binary off" +=item * +2037 "EIF - Binary character in unquoted field, binary off" +X<2037> -=item 2110 "ECB - Binary character in Combine, binary off" +=item * +2110 "ECB - Binary character in Combine, binary off" +X<2110> -=item 2200 "EIO - print to IO failed. See errno" +=item * +2200 "EIO - print to IO failed. See errno" +X<2200> -=item 3001 "EHR - Unsupported syntax for column_names ()" +=item * +3001 "EHR - Unsupported syntax for column_names ()" +X<3001> -=item 3002 "EHR - getline_hr () called before column_names ()" +=item * +3002 "EHR - getline_hr () called before column_names ()" +X<3002> -=item 3003 "EHR - bind_columns () and column_names () fields count mismatch" +=item * +3003 "EHR - bind_columns () and column_names () fields count mismatch" +X<3003> -=item 3004 "EHR - bind_columns () only accepts refs to scalars" +=item * +3004 "EHR - bind_columns () only accepts refs to scalars" +X<3004> -=item 3006 "EHR - bind_columns () did not pass enough refs for parsed fields" +=item * +3006 "EHR - bind_columns () did not pass enough refs for parsed fields" +X<3006> -=item 3007 "EHR - bind_columns needs refs to writable scalars" +=item * +3007 "EHR - bind_columns needs refs to writable scalars" +X<3007> -=item 3008 "EHR - unexpected error in bound fields" +=item * +3008 "EHR - unexpected error in bound fields" +X<3008> =back @@ -1791,7 +1913,7 @@ Jochen Wiedmann F<E<lt>j...@ispsoft.dee<gt>> rewrote the encoding and decoding in C by implementing a simple finite-state machine and added the variable quote, escape and separator characters, the binary mode and the -print and getline methods. See ChangeLog releases 0.10 through 0.23. +print and getline methods. See F<ChangeLog> releases 0.10 through 0.23. H.Merijn Brand F<E<lt>h.m.br...@xs4all.nle<gt>> cleaned up the code, added the field flags methods, wrote the major part of the test suite, completed @@ -1810,7 +1932,6 @@ =cut =for elvis - -:ex:se gw=75: +:ex:se gw=75|color guide #ff0000: =cut diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Text-CSV_XS-0.81/ChangeLog new/Text-CSV_XS-0.82/ChangeLog --- old/Text-CSV_XS-0.81/ChangeLog 2011-03-07 23:25:58.000000000 +0100 +++ new/Text-CSV_XS-0.82/ChangeLog 2011-05-01 12:44:36.000000000 +0200 @@ -1,8 +1,12 @@ +2011-05-01 0.82 - H.Merijn Brand <h.m.br...@xs4all.nl> + * Doc fix (RT#66905, Peter Newman) + * Documentation overhaul (pod links) + 2011-03-07 0.81 - H.Merijn Brand <h.m.br...@xs4all.nl> * Add is_missing () * Doc overhaul * Fix Build on OpenVMS (RT#65654, Martin P.J. Zinser) - * Fix SetDiag () leak (RT#66453, Sven Sch�ling) + * Fix SetDiag () leak (RT#66453, Sven Schöling) 2010-12-24 0.80 - H.Merijn Brand <h.m.br...@xs4all.nl> * Implement getline_all () and getaline_hr_all () diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Text-CSV_XS-0.81/META.yml new/Text-CSV_XS-0.82/META.yml --- old/Text-CSV_XS-0.81/META.yml 2011-03-22 15:04:02.000000000 +0100 +++ new/Text-CSV_XS-0.82/META.yml 2011-05-07 17:49:20.000000000 +0200 @@ -1,6 +1,6 @@ --- #YAML:1.0 name: Text-CSV_XS -version: 0.81 +version: 0.82 abstract: Comma-Separated Values manipulation routines license: perl author: @@ -10,7 +10,7 @@ provides: Text::CSV_XS: file: CSV_XS.pm - version: 0.81 + version: 0.82 requires: perl: 5.005 DynaLoader: 0 diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/Text-CSV_XS-0.81/Makefile.PL new/Text-CSV_XS-0.82/Makefile.PL --- old/Text-CSV_XS-0.81/Makefile.PL 2011-02-11 22:35:13.000000000 +0100 +++ new/Text-CSV_XS-0.82/Makefile.PL 2011-05-01 11:25:40.000000000 +0200 @@ -7,19 +7,6 @@ use ExtUtils::MakeMaker; -eval { require Text::CSV_XS }; -if (!$@ && $Text::CSV_XS::VERSION < 0.15) { - print <<'MSG'; - -You seem to have installed a previous version of the Text::CSV_XS module. -Note that you might encounter problems in existing applications (not the -DBD::CSV driver) due to incompatible changes in the print and getline -methods. See "perldoc CSV_XS.pm" for details. - -MSG - sleep 5; - } - my %wm = ( NAME => "Text::CSV_XS", ABSTRACT => "Comma-Separated Values manipulation routines", @@ -40,6 +27,18 @@ valgrind.log ) }, + + macro => { GCC_WALL => (join " " => qw( + -Wall -Wextra -Wbad-function-cast -Wcomment -Wcomments + -Wformat -Wdisabled-optimization -Wmissing-prototypes + -Werror-implicit-function-declaration -Wmissing-noreturn + -Wmissing-format-attribute -Wno-cast-qual -Wunused-value + -Wno-sign-compare -Wpointer-arith -Wreturn-type -Wshadow + -Wswitch-default -Wuninitialized -Wunreachable-code + -Wundef + )), + "#OPTIMIZE" => "-O2 \$(GCC_WALL)", + }, ); $ExtUtils::MakeMaker::VERSION > 6.30 and $wm{LICENSE} = "perl"; ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Remember to have fun... -- To unsubscribe, e-mail: opensuse-commit+unsubscr...@opensuse.org For additional commands, e-mail: opensuse-commit+h...@opensuse.org
