feat: Introduce formatters (#455)

BREAKING CHANGE: In the JavaScript modules, `formatters` are introduced and the `quote`, `escapedQuote` and `excelStrings` options are removed. See the migration notes in the readme. CLI hasn't changed.

.eslintrc

@@ -4,7 +4,7 @@
     "es6": true
   },
   "parserOptions": {
-    "ecmaVersion": 8
+    "ecmaVersion": 9
   },
   "extends": "eslint:recommended"
 }

bin/json2csv.js

@@ -16,6 +16,7 @@ const readFile = promisify(readFileOrig);
 const writeFile = promisify(writeFileOrig);
 
 const { unwind, flatten } = json2csv.transforms;
+const { string: stringFormatterCtr, stringExcel: stringExcelFormatter } = json2csv.formatters;
 const JSON2CSVParser = json2csv.Parser;
 const Json2csvTransform = json2csv.Transform;
 
@@ -149,18 +150,24 @@ async function processStream(config, opts) {
         separator: config.flattenSeparator
       }));
     }
+
+    const stringFormatter = stringFormatterCtr({
+      quote: config.quote,
+      escapedQuote: config.escapedQuote,
+    });
+    const formatters = {
+      string: config.excelStrings ? stringExcelFormatter({ stringFormatter }) : stringFormatter
+    };
 
     const opts = {
       transforms,
+      formatters,
       fields: config.fields
         ? (Array.isArray(config.fields) ? config.fields : config.fields.split(','))
         : config.fields,
       defaultValue: config.defaultValue,
-      quote: config.quote,
-      escapedQuote: config.escapedQuote,
       delimiter: config.delimiter,
       eol: config.eol,
-      excelStrings: config.excelStrings,
       header: config.header,
       includeEmptyRows: config.includeEmptyRows,
       withBOM: config.withBom

docs/cli-examples.md

@@ -0,0 +1,77 @@
+# CLI examples
+
+All examples use this example [input file](https://github.com/zemirco/json2csv/blob/master/test/fixtures/json/default.json).
+
+## Input file and specify fields
+
+```sh
+$ json2csv -i input.json -f carModel,price,color
+carModel,price,color
+"Audi",10000,"blue"
+"BMW",15000,"red"
+"Mercedes",20000,"yellow"
+"Porsche",30000,"green"
+```
+
+## Input file, specify fields and use pretty logging
+
+```sh
+$ json2csv -i input.json -f carModel,price,color -p
+```
+
+![Screenshot](https://s3.amazonaws.com/zeMirco/github/json2csv/json2csv-pretty.png)
+
+## Generating CSV containing only specific fields
+
+```sh
+$ json2csv -i input.json -f carModel,price,color -o out.csv
+$ cat out.csv
+carModel,price,color
+"Audi",10000,"blue"
+"BMW",15000,"red"
+"Mercedes",20000,"yellow"
+"Porsche",30000,"green"
+```
+
+Same result will be obtained passing the fields config as a file.
+
+```sh
+$ json2csv -i input.json -c fieldsConfig.json -o out.csv
+```
+
+where the file `fieldsConfig.json` contains
+
+```json
+[
+  "carModel",
+  "price",
+  "color"
+]
+```
+
+## Read input from stdin
+
+```sh
+$ json2csv -f price
+[{"price":1000},{"price":2000}]
+```
+
+Hit <kbd>Enter</kbd> and afterwards <kbd>CTRL</kbd> + <kbd>D</kbd> to end reading from stdin. The terminal should show
+
+```sh
+price
+1000
+2000
+```
+
+## Appending to existing CSV
+
+Sometimes you want to add some additional rows with the same columns.
+This is how you can do that.
+
+```sh
+# Initial creation of csv with headings
+$ json2csv -i test.json -f name,version > test.csv
+# Append additional rows
+$ json2csv -i test.json -f name,version --no-header >> test.csv
+```