App-CSVUtils/lib/App/CSVUtils/Manual/Cookbook.pod
## 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.036 of App::CSVUtils::Manual::Cookbook (from Perl distribution App-CSVUtils), released on 2025-02-04.
=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) 2025 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