view release on metacpan or  search on metacpan

lib/App/CSVUtils/csv_select_fields.pm  view on Meta::CPAN

=head2 csv_select_fields

Usage:

 csv_select_fields(%args) -> [$status_code, $reason, $payload, \%result_meta]

Select (only output) field(s) using a combination of excludesE<sol>includes, including by regex.

Examples:

=over

=item * Select a single field from CSV:

 csv_select_fields(input_filename => "file.csv", include_fields => ["f1"]);

=item * Select several fields from CSV:

 csv_select_fields(input_filename => "file.csv", include_fields => ["f1", "f2", "f3"]);

=item * Select fields matching regex from CSV:

 csv_select_fields(input_filename => "file.csv", include_field_pat => "/^extra_/");

=item * Select all fields except specified from CSV:

 csv_select_fields(
     input_filename    => "file.csv",
   include_field_pat => ".*",
   include_fields    => ["f1", "f2"]
 );

=item * Only show what fields would be included, then exit:

 csv_select_fields(
     input_filename       => "file.csv",
   include_field_pat    => "/^extra_/",
   show_selected_fields => 1
 );

=back

(No description)

This function is not exported.

Arguments ('*' denotes required arguments):

=over 4

=item * B<exclude_field_pat> => I<re>

Field regex pattern to exclude, takes precedence over --field-pat.

=item * B<exclude_fields> => I<array[str]>

Field names to exclude, takes precedence over --fields.

=item * B<ignore_unknown_fields> => I<bool>

When unknown fields are specified in --include-field (--field) or --exclude-field options, ignore them instead of throwing an error.

=item * B<include_field_pat> => I<re>

Field regex pattern to select, overidden by --exclude-field-pat.

=item * B<include_fields> => I<array[str]>

Field names to include, takes precedence over --exclude-field-pat.

=item * B<inplace> => I<true>

Output to the same file as input.

Normally, you output to a different file than input. If you try to output to the
same file (C<-o INPUT.csv -O>) you will clobber the input file; thus the utility
prevents you from doing it. However, with this C<--inplace> option, you can
output to the same file. Like perl's C<-i> option, this will first output to a
temporary file in the same directory as the input file then rename to the final
file at the end. You cannot specify output file (C<-o>) when using this option,
but you can specify backup extension with C<-b> option.

Some caveats:

=over

=item * if input file is a symbolic link, it will be replaced with a regular file;

=item * renaming (implemented using C<rename()>) can fail if input filename is too long;

=item * value specified in C<-b> is currently not checked for acceptable characters;

=item * things can also fail if permissions are restrictive;

=back

=item * B<inplace_backup_ext> => I<str> (default: "")

Extension to add for backup of input file.

In inplace mode (C<--inplace>), if this option is set to a non-empty string, will
rename the input file using this extension as a backup. The old existing backup
will be overwritten, if any.

=item * B<input_escape_char> => I<str>

Specify character to escape value in field in input CSV, will be passed to Text::CSV_XS.

Defaults to C<\\> (backslash). Overrides C<--input-tsv> option.

=item * B<input_filename> => I<filename> (default: "-")

Input CSV file.

Use C<-> to read from stdin.

Encoding of input file is assumed to be UTF-8.

=item * B<input_header> => I<bool> (default: 1)

Specify whether input CSV has a header row.