Turn a CSV into JSON and vice-versa.
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Flavio Poletti 5a9f78a1c7 Fix bug in percent-decoding 4 months ago
.gitignore Initial import 4 months ago
LICENSE Initial import 4 months ago
README.md Generate README.md from csv2json's POD documentation 4 months ago
cpanfile Add a cpanfile and the snapshot 4 months ago
cpanfile.snapshot Add a cpanfile and the snapshot 4 months ago
csv2json Fix bug in percent-decoding 4 months ago
csv2json.bundle Fix bug in percent-decoding 4 months ago
refresh.sh Add script to regenerate ancillary, derived artifacts 4 months ago

README.md

NAME

csv2json - Turn a CSV into JSON and vice-versa

VERSION

The version can be retrieved with option --version:

$ csv2json --version

USAGE

csv2json [--help] [--man] [--usage] [--version]

csv2json [--bom|-B]
         [--csv|c CSV-text]
         [--eol|e percent-enc-string]
         [--input|-i path-or-minus]
         [--inverse|json2csv|-I]
         [--json|-j JSON-text]
         [--output|-o path-or-minus]
         [--sep|--separator|--sep_char|--sep-char|-s percent-enc-string]

EXAMPLES

# CSV to JSON using standard filehandles
$ csv2json <file.csv >file.json

# inputs and outputs can be specified explicitly
$ csv2json -i file.csv -o file.json

# also to explicitly set input and output with file name "-"
$ cat file.csv | csv2json -i - -o - > file.json

# the CSV can be provided as a command-line parameter
$ csv2json --csv "$csv_string"

# separator is ";", can be changed with a percent-encoded string
$ csv2json --sep %2C     # ","

# the end-of-line character can be set with a percent-encoded string
$ csv2json --eol %0D%0A  # "\r\n"

# the inverse operation is possible too
$ csv2json --inverse -i file.json -o file.csv

# this can be triggered automatically with proper naming
$ ln -s /path/to/csv2json /path/to/json2csv
$ json2csv -i file.json -o file.csv

# the JSON string can be provided as a command-line parameter
$ csv2json --inverse --json "$json_string"

DESCRIPTION

Turn a CSV file into a JSON array of objects, or the other way around.

By default the standard input/output channels are used, taking a CSV as input and emitting JSON output:

$ cat file.csv | csv2json > file.json

It's possible to go the other way around:

$ cat file.json | csv2json --inverse > file.csv

If the program is saved (or aliased) as json2csv, the inverse behaviour is automatic:

$ cat file.json | json2csv > file.csv

If the input file contains a JSON object, it's fit inside an array and then turned into a CSV string/file.

It's possible to set the field separator with option --sep and set the end-of-line separator for records --eol. Both are interpreted as percent-encoded strings.

If the input CSV file has a Byte-Order Mark (BOM), it's possible to set the progrma to honor it with option --bom. When the BOM is not present this option should be left out.

Last, the input can be set as strings provided directly on the command-line; depending on the specific direction, this can be done with either option --csv or option --json.

When both --csv and --eol are set, the input string is checked to ensure that it ends with the end-of-line set. This tries to address the way shells get rid of trailing newlines in sub-processes.

OPTIONS

csv2json supports the following command-line options:

  • --bom|-B

    set the automatic detection of the Byte-Order Marker (BOM) when reading the input file. Setting this option when there is no BOM in the file is... not recommended.

  • --csv|-c CSV-text

    pass the CSV text for input parsing directly as a string.

  • --eol|-e percent-encoded-string

    set the sequence for end-of-line. The string is considered a percent-encoded string, i.e. any sub-sequence %XX interprets the XX part as a hexadecimal-encoded value that is then turned into a character.

    As an example, setting the end-of-line to \r\n can be done by using sequence %0D%0A.

    By default, anything set by module Text::CSV_PP is taken.

    This option can also be set via environment variable CSV2JSON_EOL.

  • --help

    print out some help and exit.

  • --input|-i path-or-minus

    set the input file/channel. When not set, or set to the string -, standard input is used; otherwise the value is interpreted as a path.

  • --inverse|--json2csv|-I

    set the program to operate the other way around, i.e. read a JSON file and generate a CSV out of it.

    This is also the default behaviour when this program is invoked as json2csv.

  • --json|-j JSON-text

    when operating in inverse mode (see "--inverse|--json2csv|-I") this option allows passing the input directly as a string.

  • --man

    show the manual page for csv2json.

  • --output|-o path-or-minus

    set the output file/channel. When not set, or set to the string -, standard output is used; otherwise the value is interpreted as a path.

  • --sep|--separator|--sep_char|--sep-char|-s percent-encoded-string

    set the sequence for separating fields. The string is considered a percent-encoded string, i.e. any sub-sequence %XX interprets the XX part as a hexadecimal-encoded value that is then turned into a character.

    As an example, setting the separator to a comma can be done setting %2C.

    By default, the semicolon character ; (i.e. %3B) is used.

    This option can also be set via environment variable CSV2JSON_SEP_CHAR.

  • --usage

    show usage instructions.

  • --version

    show version.

CONFIGURATION

This program supports two environment variables:

DEPENDENCIES

This program depends on the following non-CORE modules:

BUGS AND LIMITATIONS

Please report any bugs or feature requests through the repository at https://codeberg.org/polettix/csv2json.

AUTHOR

Flavio Poletti

LICENSE AND COPYRIGHT

Copyright 2023 by Flavio Poletti (flavio@polettix.it).

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

or look for file LICENSE in this project's root directory.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.