csvmode(3am)

💖 csvmode(3am) — like, the CSV one 💖

okay bestie so real talk: this is csvmode, a page from the GNU Awk Extension Modules set, and it's genuinely one of my faves because it lets gawk just… eat CSV files directly. no preprocessing era, we're going straight in ✨

---

✨ NAME ✨

csvmode — direct processing of Comma-Separated-Values (CSV) data files with gawk. 💅

---

🎀 SYNOPSIS 🎀

@include "csv"
BEGIN { CSVMODE = 1 }
  ... rules with $0, $1, ... $NF, CSVRECORD, ...

csvfield(name, default)
csvprint(record, option...)
csvprint0()

---

🦋 DESCRIPTION 🦋

The gawk-csv extension can directly process CSV data files. it uses a few specific variables, and honestly? they're the whole personality of this module 🌸

• CSVMODE — set CSVMODE=1 and CSV formatted input data records automatically get converted into regular awk records with fixed field separators, delivered as $0. $1 .. $NF are set accordingly too, no cap. Set CSVMODE=0 and it disables the conversion, so input files are processed the usual way. see NOTE 1 💖

The conversion can be customized by some control variables:

• CSVFS — the resulting field separator, which temporarily overrides the FS and OFS predefined variables. if it's not set, a null char '\0' is used. see NOTE 1.
• CSVCOMMA — the input CSV field delimiter. default comma ','.
• CSVQUOTE — the input CSV quoting character. default double quote '"'.
• CSVRECORD — the original CSV input record. the raw one, unbothered, main character energy 👑

If the CSV file has a header record, you can also access the fields by name, which is such a slay:

💜 the functions 💜

• csvfield(name [, missing]) — returns the named field of the current record. if there's no column named name, then it returns missing, or a null value if missing isn't given. simple as 🫶
• csvprint([record, [fs [, comma [, quote]]]]) — a convenience function that formats and prints the given record in a single call. called with no arguments, it prints either $0 formatted as CSV or CSVRECORD, depending on CSVMODE. arguments work like csvformat(). ✨
• csvprint0() — a convenience function that prints the original input record as such. prints either $0 or CSVRECORD, depending on CSVMODE. 🎀

⚠️ heads up bestie: CSVMODE, CSVFS, CSVCOMMA and CSVQUOTE are checked only at BEGINFILE time. changing them in the middle of a file processing takes no effect. like, none. don't try it 💀

CSVRECORD is updated for each CSV input record. 🦋

The CSV input mode accepts fields with embedded newlines, tabs and other control characters, except null characters ('\0'). 😭

---

🌈 EXAMPLES 🌈

Extract CSV records with some specific value in the second field:

BEGIN {CSVMODE = 1}
$2=="some value" {print CSVRECORD}

Process CSV files with fields separated by semicolons instead of commas:

BEGIN {CSVMODE = 1; CSVFS = ";"}
  ... processing rules ...

Print a specific named field of every record:

BEGIN {CSVMODE = 1;}
{ print csvfield("City") }

Print records that contain commas as data, in both normal and CSV modes:

grepcommas.awk:

BEGINFILE {
    CSVMODE = (FILENAME ~ /\.csv$/)
}
/,/ { csvprint0() }

Sample invocation:

gawk -f grepcommas.awk a.txt, b.csv, c.txt

---

🧚 NOTES 🧚

(1) If the user code has a BEGINFILE action that sets CSV-mode variables depending on the current file, this action must appear before the @include "csv" clause:

BEGINFILE {
    CSVMODE = (FILENAME ~ /\.csv$/)  # switch mode depending on the file type
}
@include "csv"

like, order matters here fr fr 🙈

---

💀 BUGS 💀

Null characters are not allowed in fields. a null character terminates the record processing. that's it, that's the bug, and yes it will ruin your whole afternoon if you let it 😭

---

👑 AUTHOR 👑

Manuel Collado, m-collado@users.sourceforge.net.

---

⭐ SEE ALSO ⭐

XML Processing With gawk, csvparse(3am).

---

📜 COPYING PERMISSIONS 📜

Copyright (C) 2018, Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual page provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual page under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual page into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.

---

and that's the whole page, bestie 🫶 this one shipped as part of the GAWK Extension Library (gawkextlib), dated May 2016 — vintage but still iconic 💖✨🎀