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 0.049 of App::CSVUtils::Manual::Cookbook (from Perl distribution App-CSVUtils), released on 2022-12-02.

=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

=head2 ADDING COLUMNS

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

 % csv-add-field 1.csv foo '$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 column will be using one of the
options C<--at>, C<--after>, C<--before>:

TODO EXAMPLE.

=head2 ADDING ROWS

TODO.

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

TODO.

=head2 CONVERTING TO OTHER FORMATS

=head3 To CSV

TODO.

=head3 To JSON

TODO.

=head3 To Perl data structure

TODO.

=head3 To TSV

TODO.

=head3 To YAML

TODO.

=head2 DEALING WITH NEWLINES IN CSV

TODO.

=head2 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`).

=head2 FILTERING (SELECTING) COLUMNS

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>.

=head2 FILTERING (SELECTING) ROWS

TODO.

=head2 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
 }

=head3 Listing the column 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"
    }
 ]

=head2 MERGING CSV

TODO.

See also L</SPLITTING CSV>.

=head2 MODIFYING COLUMNS

TODO.

=head2 MODIFYING ROWS

TODO.

=head2 PERFORMING SET OPERATIONS WITH CSV

TODO.

=head2 SORTING COLUMNS

TODO.

=head2 SORTING ROWS

TODO.

=head2 SPLITTING CSV

TODO.

See also L</MERGING CSV>.

=head2 TRANSPOSING

Transposing, like in a two-dimensional matrix, means switching row and colum
indices to produce a new CSV where the columns 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) 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
