/ 
App-CSVUtils-1.023
River stage one • 3 direct dependents • 4 total dependents
/ App::CSVUtils::csv2paras

NAME

App::CSVUtils::csv2paras - Convert CSV to paragraphs

VERSION

This document describes version 1.023 of App::CSVUtils::csv2paras (from Perl distribution App-CSVUtils), released on 2023-03-31.

FUNCTIONS

csv2paras

Usage:

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

Convert CSV to paragraphs.

This utility converts CSV format like this:

name,email,phone,notes
bill,bill@example.com,555-1236,+
lisa,lisa@example.com,555-1235,from work
jimmy,jimmy@example.com,555-1237,

into paragraphs format like this, which resembles (but not strictly follows) email headers (RFC-822) or internet message headers (RFC-5322):

name: bill
email: bill@example.com
phone: 555-1236
notes: +

name: lisa
email: lisa@example.com
phone: 555-1235
notes: from work

name: jimmy
email: jimmy@example.com
phone: 555-1237
notes:

Why display in this format? It might be more visually readable or diff-able especially if there are a lot of fields and/or there are long values.

If a CSV value contains newline, it will escaped "\n", e.g.:

# CSV
name,email,phone,notes
beth,beth@example.com,555-1231,"Has no last name
Might be adopted sometime by Jimmy"
matthew,matthew@example.com,555-1239,"Quit

  or fired?"

# paragraph
name: beth
email: beth@example.com
phone: 555-1231
notes: Has no last name\nMight be adopted sometime by Jimmy

name: matthew
email: matthew@example.com
phone: 555-1239
notes: Quit\n\n  or fired?

If a CSV value contains literal "\" (backslash) it will be escaped as "\".

Long lines are also by default folded at 78 columns (but you can customize with the --width option); if a line is folded a literal backslash is added to the end of each physical line and the next line will be indented by two spaces:

notes: This is a long note. This is a long note. This is a long note. This is
  a long note. This is a long note.

A long word is also folded and the next line will be indented by one space:

notes: Thisisalongwordthisisalongwordthisisalongwordthisisalongwordthisisalongw
 ord

Newline and backslash are also escaped in header; additionally a literal ":" (colon) is escaped into "\:".

There is option to skip displaying empty fields (--hide-empty-values) and to align the ":" header separator.

Keywords: paragraphs, cards, pages, headers

This function is not exported.

Arguments ('*' denotes required arguments):

  • align => bool

    Whether to align header separator across lines.

    Note that if you want to convert the paragraphs back to CSV later using paras2csv, the padding spaces added by this option will become part of header value, unless you use its --trim-header or --rtrim-header option.

  • hide_empty_values => bool

    Whether to skip showing empty values.

  • input_escape_char => str

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

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

  • input_filename => filename (default: "-")

    Input CSV file.

    Use - to read from stdin.

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

  • input_header => bool (default: 1)

    Specify whether input CSV has a header row.

    By default, the first row of the input CSV will be assumed to contain field names (and the second row contains the first data row). When you declare that input CSV does not have header row (--no-input-header), the first row of the CSV is assumed to contain the first data row. Fields will be named field1, field2, and so on.

  • input_quote_char => str

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

    Defaults to " (double quote). Overrides --input-tsv option.

  • input_sep_char => str

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

    Defaults to , (comma). Overrides --input-tsv option.

  • input_tsv => true

    Inform that input file is in TSV (tab-separated) format instead of CSV.

    Overriden by --input-sep-char, --input-quote-char, --input-escape-char options. If one of those options is specified, then --input-tsv will be ignored.

  • width => int (default: 78)

    The width at which to fold long lines, -1 means to never fold.

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code (200 means OK, 4xx caller error, 5xx function error). Second element ($reason) is a string containing error message, or something like "OK" if status is 200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth element (%result_meta) is called result metadata and is optional, a hash that contains extra information, much like how HTTP response headers provide additional metadata.

Return value: (any)

HOMEPAGE

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

SOURCE

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

SEE ALSO

Acme::MetaSyntactic::newsradio

AUTHOR

perlancar <perlancar@cpan.org>

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 Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, 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.

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.

BUGS

Please report any bugs or feature requests on the bugtracker website 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.