## no critic: TestingAndDebugging::RequireUseStrict
package App::CSVUtils::Manual::Cookbook;

# AUTHORITY
# DATE
our $DIST = 'App-CSVUtils'; # DIST
# VERSION

1;
# ABSTRACT: App::CSVUtils cookbook

__END__

=pod

=encoding UTF-8

=head1 NAME

App::CSVUtils::Manual::Cookbook - App::CSVUtils cookbook

=head1 VERSION

This document describes version 1.030 of App::CSVUtils::Manual::Cookbook (from Perl distribution App-CSVUtils), released on 2023-07-25.

=head1 DESCRIPTION

This document lists the various tasks you can do with the scripts included in
L<App::CSVUtils> distribution.

Example F<1.csv> content:

 name,age,rank
 andi,25,120
 budi,28,115
 cinta,19,142
 derry,33,121

Example F<2.csv> content:

 name,gender
 andi,M
 budi,M
 cinta,F
 erni,F

=head1 ADDING FIELDS

With L<csv-add-field>, we add a new field named C<foo> with the content
calculated from Perl code:

 % csv-add-fields 1.csv foo -e '$main::rownum * 2'
 name,age,rank,foo
 andi,25,120,4
 budi,28,115,6
 cinta,19,142,8
 derry,33,121,10

You can specify at which position the new field will be using one of the options
C<--at>, C<--after>, C<--before>.

=head2 Adding a field containing line number

 % csv-add-fields 1.csv linenum --at 1 -e '++$i'
 linenum,name,age,rank
 1,andi,25,120
 2,budi,28,115
 3,cinta,19,142
 4,derry,33,121

Other ways:

 % csv-add-fields 1.csv linenum --at 1 -e '$rownum-1'
 % csv-add-fields 1.csv linenum --at 1 -e '$data_rownum'

See also: L</Adding line number to CSV rows>.

=head1 ADDING ROWS

TODO.

=head1 ADDING SUMMARY ROW (TOTAL, AVERAGE, ETC)

TODO.

=head1 CONVERTING TO OTHER FORMATS

=head2 To CSV

TODO.

=head2 To JSON

TODO.

=head2 To Perl data structure

TODO.

=head2 To TSV

TODO.

=head2 To YAML

TODO.

=head1 DEALING WITH NEWLINES IN CSV

TODO.

=head1 DEALING WITH NON-STANDARD CSV

The utilities allow you to set input's field separator (`--sep-char`), quote
character (`--quote-char`), and escape character (`--escape-char`), so if you
have semicolon as the field separator, e.g.:

 name;age;rank
 andi;20;staff
 budi;30;manager
 cinta;17;associate

and you want to sort by age:

 % csv-sort-rows INPUT.CSV --sep-char ';' --by-field age

These parameters will be passed to L<Text::CSV>'s attributes with the
corresponding names.

Likewise, you can customize output's field separator (`--output-sep-char`),
quote character (`--output-quote-char`), and escape character
(`--output-escape-char`).

=head1 FILTERING FIELDS

Keywords: selecting fields, grepping fields

With L<csv-select-fields>:

 % csv-select-fields 1.csv -f age -f name
 age,name
 25,andi
 28,budi
 19,cinta
 33,derry

Note that the order of the fields is as specified.

You can select multiple fields using C<--include-field-pat> option. You can
exclude fields using C<--exclude-field> and C<--exclude-field-pat>.

=head1 FILTERING (SELECTING) ROWS

TODO.

=head1 GETTING INFORMATION ABOUT CSV

 % csv-info 1.csv
 {
    "data_row_count" : 6,
    "field_count" : 3,
    "fields" : [
       "name",
       "age",
       "rank"
    ],
    "file_size" : 78,
    "header_row_count" : 0,
    "row_count" : 6
 }

=head2 Listing the field names

 % csv-list-field-names 1.csv
 +------+-------+
 | name | index |
 +------+-------+
 | age  | 2     |
 | name | 1     |
 | rank | 3     |
 +------+-------+

 % csv-list-field-names 1.csv --json
 [
    200,
    "OK",
    [
       {
          "index" : 2,
          "name" : "age"
       },
       {
          "index" : 1,
          "name" : "name"
       },
       {
          "index" : 3,
          "name" : "rank"
       }
    ],
    {
       "stream" : 0,
       "table.fields" : [
          "name",
          "index"
       ],
       "title" : "csv-list-field-names 1.csv --json"
    }
 ]

=head1 MERGING CSV FILES

Keywords: concatenating, combining.

See also: L</SPLITTING CSV>

=head2 Merging CSV files

 % csv-concat 1.csv 2.csv
 name,age,rank,name,gender
 andi,25,120,
 budi,28,115,
 cinta,19,142,
 derry,33,121,
 andi,,,M
 budi,,,M
 cinta,,,F
 erni,,,F

=head2 Adding field containing filename

 % csv-concat <(csv-add-fields 1.csv filename --at 1 -e '"1.csv"') <(csv-add-fields 2.csv filename --at 1 -e '"2.csv"')

=head1 MODIFYING FIELDS

Keywords: munging fields

=head1 MODIFYING ROWS

Keywords: munging rows

=head1 Adding line number to CSV rows

 % csv-munge-rows 1.csv -e '$_->[0] = ++$i . "|$_->[0]"'
 name,age,rank
 1|andi,25,120
 2|budi,28,115
 3|cinta,19,142
 4|derry,33,121

Other ways:

 % csv-munge-rows 1.csv -e '$_->[0] = $data_rownum . "|$_->[0]"'

See also: L</Adding a field containing line number>.

=head1 Shuffling every row

 % csv-munge-rows 1.csv -e 'use List::Util "shuffle"; $_=[shuffle @$_]'

=head1 MODIFYING VALUES

=head2 Quoting all values, including where quotes are not necessary

Sample file F<input.csv>:

 name,age
 budi",21
 "toni saputra, s.h",32

 % csv-csv input.csv --output-always-quote
 "name","age"
 "budi","21"
 "toni saputra, s.h","32"

=head2 Removing non-necessary quotes around values

Sample file F<input.csv>:

 "name","age"
 "budi","21"
 "toni saputra, s.h","32"

 % csv-csv input.csv --no-output-always-quote
 name,age
 budi",21
 "toni saputra, s.h",32

=head1 PERFORMING SET OPERATIONS WITH CSV

See L<csv-setop>.

TODO.

=head1 SORTING FIELDS

See L<csv-sort-fields>.

TODO.

=head1 SORTING ROWS

See L<csv-sort-rows>.

TODO.

=head1 SPLITTING CSV

See L<csv-split>.

TODO.

See also L</MERGING CSV FILES>.

=head1 TRANSPOSING

Transposing, like in a two-dimensional matrix, means switching row and colum
indices to produce a new CSV where the fields become rows and vice versa. For
example:

 name,age
 andi,20
 budi,30
 cinta,17

becomes:

 name,andi,budi,cinta
 age,20,30,17

To do this:

 % csv-transpose INPUT.CSV

=head1 HOMEPAGE

Please visit the project's homepage at L<https://metacpan.org/release/App-CSVUtils>.

=head1 SOURCE

Source repository is at L<https://github.com/perlancar/perl-App-CSVUtils>.

=head1 SEE ALSO

L<Acme::CPANModules::WorkingWithCSV>

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 CONTRIBUTING


To contribute, you can send patches by email/via RT, or send pull requests on
GitHub.

Most of the time, you don't need to build the distribution yourself. You can
simply modify the code, then test via:

 % prove -l

If you want to build the distribution (e.g. to try to install it locally on your
system), you can install L<Dist::Zilla>,
L<Dist::Zilla::PluginBundle::Author::PERLANCAR>,
L<Pod::Weaver::PluginBundle::Author::PERLANCAR>, and sometimes one or two other
Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond
that are considered a bug and can be reported to me.

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website L<https://rt.cpan.org/Public/Dist/Display.html?Name=App-CSVUtils>

When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.

=cut
