Adding TSV/CSV documentation

LibreCat · Nov 6, 2023 · 71f34be · 71f34be
1 parent 3e0fe11
commit 71f34be
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 0 deletions.
diff --git a/Changes b/Changes
@@ -2,6 +2,7 @@ Revision history for Catmandu
 
 {{$NEXT}}
   - #397: Support empty paths
+  - Updating documentation about CSV, TSV exports
 
 1.2020  2023-02-08 16:29:37 CET
   - Reordering documentation focussing on command line functionality

diff --git a/lib/Catmandu/Exporter/CSV.pm b/lib/Catmandu/Exporter/CSV.pm
@@ -90,6 +90,11 @@ Catmandu::Exporter::CSV - a CSV exporter
 
     $ catmandu convert JSON to CSV --fix myfixes.txt --sep_char ';' < data.json
 
+    # Provide a hint to the exporter which fields to export from the JSON
+    # input. By default the CSV exporter will export the fields that are
+    # found in the first JSON record.
+    $ catmandu convert JSON to CSV --fields "id,title,year" < data.json
+
     # In a Perl script
 
     use Catmandu;
@@ -121,6 +126,10 @@ will be included if option C<header> is set. See L<Catmandu::TabularExporter>
 on how to configure the field mapping and column names. Newlines and tabulator
 values in field values are escaped as C<\n>, C<\r>, and C<\t>.
 
+Hint: by default, the exporter will output all the fields that are found in the 
+first record of the data input. This can be changed by setting the C<fields>
+option of the exporter.
+
 =head1 CONFIGURATION
 
 =over

diff --git a/lib/Catmandu/Exporter/TSV.pm b/lib/Catmandu/Exporter/TSV.pm
@@ -42,6 +42,9 @@ Catmandu::Exporter::TSV - a tab-delimited TSV exporter
 
     # From the command line
 
+    # Provide a hint to the exporter which fields to export from the JSON
+    # input. By default the TSV exporter will export the fields that are
+    # found in the first JSON record.
     $ catmandu convert JSON to TSV --fields "id,title,year" < data.json
 
     # In a Perl script
@@ -74,6 +77,10 @@ set. See L<Catmandu::TabularExporter> on how to configure the field mapping
 and column names. Newlines and tabulator values in field values are escaped
 as C<\n>, C<\r>, and C<\t>.
 
+Hint: by default, the exporter will output all the fields that are found in the 
+first record of the data input. This can be changed by setting the C<fields>
+option of the exporter.
+
 =head1 CONFIGURATION
 
 =over