CSV(1)

📦
version 0.08 · 2 versions
, in fedora 43

👑 CSV(1) 👑

okay so hi bestie 💖 you're looking at the CSV(1) page, straight out of the User Contributed Perl Documentation (perl v5.42.0, dated 2025-07-25, but we'll get to that at the end, mwah). This is the whole thing, every last flag, and I'm gonna make it make sense. no cap.

✨ NAME ✨

csv — process CSV files from the command line. that's it. that's the job. 🎀

🌸 SYNOPSIS 🌸

  # On the command line:

  csv 1 2 -1 < report.csv

  # Reads the first two fields, as well as the last one, from "report.csv".
  # Data is cleaned up and emitted as CSV.

  csv --fields Revenue,Q1,Q2 < report.csv   # or "-f" for short

  # First line of the input (from file "report.csv") is considered as
  # header line; the fields are emitted in the order "Revenue", "Q1",
  # and "Q2". Data is cleaned up and emitted as CSV.

  csv --input report.csv --to_tsv

  # Converts the whole report to TSV (tab-separated values).

let me translate that real quick for the girlies who skim:

  1. csv 1 2 -1 < report.csv — grabs the first two fields and the last one out of report.csv, cleans the data up, and spits it back out as CSV. 💅
  2. csv --fields Revenue,Q1,Q2 < report.csv — the first line of the input (that's report.csv) gets treated as a header line, and then you get your fields back in the order Revenue, Q1, Q2. (-f is the short version, iykyk.)
  3. csv --input report.csv --to_tsv — converts the entire report to TSV (tab-separated values). slay. 🔥

💜 DESCRIPTION 💜

CSV (comma-separated value) files are, like, the lowest common denominator of structured data interchange formats. so humble. so basic. and yet?? for such a humble little file format it is genuinely difficult to get right: embedded quote marks, embedded linebreaks, slipshod delimiters, and literally no One True Validity Test — which is exactly why the CSV data you find in the wild is so hard to parse correctly. 😭

Text::CSV_XS gives you flexible and performant access to CSV files from Perl, but ngl it's cumbersome to use in one-liners and on the command line.

csv is here to make commandline processing of CSV files as easy as plain text is meant to be on Unix. ✨ internally, it holds two Text::CSV objects (one for input, one for output) which come with reasonable defaults, but bestie you can reconfigure them to suit your needs. then you can extract just the fields you want, change the delimiter, clean up the data, etc. main character energy, honestly.

in the simplest usage, csv filters stdio and takes a list of integers. those are 1-based column numbers to select from the input CSV stream. negative numbers are counted from the line end. and if you don't give it any column list at all, csv selects all columns — which is still useful, because it normalizes the quoting style etc. 🦋

🎀 Command line options 🎀

the following options get passed straight to Text::CSV. when they're preceded by the prefix output_, the destination is affected. otherwise, these options affect both input and output. ⭐

  • --quote_char
  • --escape_char
  • --sep_char
  • --eol
  • --always_quote
  • --binary
  • --keep_meta_info
  • --allow_loose_quotes
  • --allow_loose_escapes
  • --allow_whitespace
  • --verbatim
NOTE: binary is set to 1 by default in csv. the other options have their Text::CSV defaults.

the following additional options are available:

  • --input, -i
  • --output, -o

filenames for input and output. - means stdio. useful to trigger TSV mode (--from_tsv and --to_tsv). 💫

  • --columns, -c

column numbers may be specified using this option.

  • --fields, -f

when this option is specified, the first line of the input file is considered as a header line. this option takes a comma-separated list of column-names from the first line.

for convenience, this option also accepts a comma-separated list of column numbers as well. multiple --fields options are allowed, and both column names and numbers can be mixed together. 🫶

  • --from_tsv, --from-tsv
  • --to_tsv, --to-tsv

use tabs instead of commas as the delimiter. when csv has the input or output filenames available, this is inferred when they end with ".tsv". to disable this dwimmery, you may say --to_tsv=0 and --from_tsv=0. (the dwimmery, bestie. it's giving magic. 🧚)

🌈 SEE ALSO 🌈

Text::CSV, Text::CSV_XS

💖 AUTHOR 💖

Gaal Yahas "<gaal@forum2.org>"

🫶 THANKS 🫶

nothingmuch, gphat, t0m, themoniker, Prakash Kailasa, tsibley, srezic, and ether. icons, all of them. 👑

💀 BUGS 💀

please report any bugs or feature requests to "bug-app-csv at rt.cpan.org", or through the web interface at:

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-CSV>

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. no ghosting, fr fr.

you're also invited to work on a patch. the source repo is at:

<git://github.com/gaal/app-csv.git>

<http://github.com/gaal/app-csv/tree/master>

Copyright 2013 Gaal Yahas.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

okay that's the whole page, bestie, nothing skipped, nothing gatekept. 💅✨ this one shipped as perl v5.42.0, dated 2025-07-25, and it lives under the name CSV(1). go parse something pretty. 🎀🦋💖

📦 where this page comes from