Mirrors/miller
1
0
Fork 0
mirror of https://github.com/johnkerl/miller.git synced 2026-07-20 18:10:07 +00:00
Code Issues Projects Releases Wiki Activity

comment-handling documentation

Browse source
This commit is contained in:
John Kerl 2018-01-05 10:11:18 -05:00
parent d66f293f04
commit ca07014e94
5 changed files with 100 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

5
c/draft-release-notes.md
View file

@ -1,9 +1,6 @@
## Features:
* **Comment strings in data files:** `mlr --skip-comments` allows you to
filter out input lines starting with `#`, for all file formats. Likewise, `mlr
--skip-comments-with X` lets you specify the comment-string `X`. Comments are
only supported at start of data line.
* [**Comment strings in data files:**](http://johnkerl.org/miller-releases/miller-5.3.0/doc/file-formats.html#Comments_in_data) `mlr --skip-comments` allows you to filter out input lines starting with `#`, for all file formats. Likewise, `mlr --skip-comments-with X` lets you specify the comment-string `X`. Comments are only supported at start of data line. `mlr --pass-comments` and `mlr --pass-comments-with X` allow you to forward comments to program output as they are read.
* The [**count-similar**](http://johnkerl.org/miller-releases/miller-5.3.0/doc/reference-verbs.html#count-similar)
verb lets you compute cluster sizes by cluster labels.

6
c/todo.txt
View file

@ -16,10 +16,10 @@ BUGFIXES
* comment-handling:
o UT for CRLFs
o mlh
o mld
o UT for non-#
! double-check line-number handling for csv/csvlite/other errors
* xxx note for trailing whitespace in json fixed
* sql-setup doc somewhere .......
* bare ./configure ?

19
doc/content-for-file-formats.html
View file

@ -10,7 +10,8 @@ POKI_PUT_TOC_HERE
<p/>Miller handles name-indexed data using several formats: some you probably
know by name, such as CSV, TSV, and JSON &mdash; and other formats you&rsquo;re
likely already seeing and using in your structured data.
likely already seeing and using in your structured data. Additionally, Miller gives
you the option of including comments within your data.
</div>
<h1>Examples</h1>
@ -361,3 +362,19 @@ POKI_PUT_LINK_FOR_PAGE(reference.html#Record/field/pair_separators)HERE for
more information about record/field/pair separators.
</div>
<h1>Comments in data</h1>
<button style="font-weight:bold;color:maroon;border:0" padding=0 onclick="toggle_by_name('section_toggle_comments_in_data');" href="javascript:;">Toggle section visibility</button>
<div id="section_toggle_comments_in_data" style="display: block">
<p/>You can include comments within your data files, and either have them ignored, or passed directly
through to the standard output as soon as they are encountered:
POKI_RUN_COMMAND{{mlr --usage-comments-in-data}}HERE
<p/>Examples:
POKI_RUN_COMMAND{{cat data/budget.csv}}HERE
POKI_RUN_COMMAND{{mlr --skip-comments --icsv --opprint sort -nr quantity data/budget.csv}}HERE
POKI_RUN_COMMAND{{mlr --pass-comments --icsv --opprint sort -nr quantity data/budget.csv}}HERE
</div>

5
doc/data/budget.csv Normal file
View file

@ -0,0 +1,5 @@
# Asana -- here are the budget figure you asked for!
type,quantity
purple,456.78
green,678.12
orange,123.45
1 # Asana -- here are the budget figure you asked for!
2 type,quantity
3 purple,456.78
4 green,678.12
5 orange,123.45

74
doc/file-formats.html
View file

@ -204,6 +204,7 @@ Miller commands were run with pretty-print-tabular output format.
&bull;&nbsp;<a href="#Markdown_tabular">Markdown tabular</a><br/>
&bull;&nbsp;<a href="#Data-conversion_keystroke-savers">Data-conversion keystroke-savers</a><br/>
&bull;&nbsp;<a href="#Autodetect_of_line_endings">Autodetect of line endings</a><br/>
&bull;&nbsp;<a href="#Comments_in_data">Comments in data</a><br/>
</div>
<p/>
@ -217,7 +218,8 @@ Miller commands were run with pretty-print-tabular output format.
<p/>Miller handles name-indexed data using several formats: some you probably
know by name, such as CSV, TSV, and JSON &mdash; and other formats you&rsquo;re
likely already seeing and using in your structured data.
likely already seeing and using in your structured data. Additionally, Miller gives
you the option of including comments within your data.
</div>
<a id="Examples"/><h1>Examples</h1>
@ -1004,6 +1006,76 @@ Unix/Linux/BSD/MacOSX, and CRLF on Windows.
<a href="reference.html#Record/field/pair_separators">Reference</a> for
more information about record/field/pair separators.
</div>
<a id="Comments_in_data"/><h1>Comments in data</h1>
<button style="font-weight:bold;color:maroon;border:0" padding=0 onclick="toggle_by_name('section_toggle_comments_in_data');" href="javascript:;">Toggle section visibility</button>
<div id="section_toggle_comments_in_data" style="display: block">
<p/>You can include comments within your data files, and either have them ignored, or passed directly
through to the standard output as soon as they are encountered:
<p/>
<div class="pokipanel">
<pre>
$ mlr --usage-comments-in-data
--skip-comments Ignore commented lines (prefixed by "#")
within the input.
--skip-comments-with {string} Ignore commented lines within input, with
specified prefix.
--pass-comments Immediately print commented lines (prefixed by "#")
within the input.
--pass-comments-with {string} Immediately print commented lines within input, with
specified prefix.
Notes:
* Comments are only honored at the start of a line.
* In the absence of any of the above four options, comments are data like
any other text.
* When pass-comments is used, comment lines are written to standard output
immediately upon being read; they are not part of the record stream.
Results may be counterintuitive. A suggestion is to place comments at the
start of data files.
</pre>
</div>
<p/>
<p/>Examples:
<p/>
<div class="pokipanel">
<pre>
$ cat data/budget.csv
# Asana -- here are the budget figure you asked for!
type,quantity
purple,456.78
green,678.12
orange,123.45
</pre>
</div>
<p/>
<p/>
<div class="pokipanel">
<pre>
$ mlr --skip-comments --icsv --opprint sort -nr quantity data/budget.csv
type quantity
green 678.12
purple 456.78
orange 123.45
</pre>
</div>
<p/>
<p/>
<div class="pokipanel">
<pre>
$ mlr --pass-comments --icsv --opprint sort -nr quantity data/budget.csv
# Asana -- here are the budget figure you asked for!
type quantity
green 678.12
purple 456.78
orange 123.45
</pre>
</div>
<p/>
</div>
</div>
</td>