From 4227b0f10409e930e6cfab3956d2aaabbb61aee2 Mon Sep 17 00:00:00 2001 From: John Kerl Date: Sat, 1 Oct 2016 12:56:16 -0400 Subject: [PATCH] keyword-help alphabetize --- c/mapping/mlr_dsl_cst_keywords.c | 347 +++++++++++++++++-------------- doc/manpage.html | 192 ++++++++--------- doc/manpage.txt | 192 ++++++++--------- doc/mkman.rb | 2 +- doc/mlr.1 | 234 ++++++++++----------- doc/reference.html | 167 ++++++++------- 6 files changed, 583 insertions(+), 551 deletions(-) diff --git a/c/mapping/mlr_dsl_cst_keywords.c b/c/mapping/mlr_dsl_cst_keywords.c index 456602b6c..d7e9d6ae4 100644 --- a/c/mapping/mlr_dsl_cst_keywords.c +++ b/c/mapping/mlr_dsl_cst_keywords.c @@ -4,124 +4,133 @@ #include "mlr_dsl_cst.h" #include "context_flags.h" -static void mlr_dsl_filter_keyword_usage (FILE* ostream); -static void mlr_dsl_unset_keyword_usage (FILE* ostream); -static void mlr_dsl_tee_keyword_usage (FILE* ostream); -static void mlr_dsl_emit_keyword_usage (FILE* ostream); -static void mlr_dsl_emitp_keyword_usage (FILE* ostream); -static void mlr_dsl_emitf_keyword_usage (FILE* ostream); static void mlr_dsl_dump_keyword_usage (FILE* ostream); static void mlr_dsl_edump_keyword_usage (FILE* ostream); -static void mlr_dsl_print_keyword_usage (FILE* ostream); -static void mlr_dsl_printn_keyword_usage (FILE* ostream); +static void mlr_dsl_emit_keyword_usage (FILE* ostream); +static void mlr_dsl_emitf_keyword_usage (FILE* ostream); +static void mlr_dsl_emitp_keyword_usage (FILE* ostream); static void mlr_dsl_eprint_keyword_usage (FILE* ostream); static void mlr_dsl_eprintn_keyword_usage (FILE* ostream); -static void mlr_dsl_stdout_keyword_usage (FILE* ostream); +static void mlr_dsl_filter_keyword_usage (FILE* ostream); +static void mlr_dsl_print_keyword_usage (FILE* ostream); +static void mlr_dsl_printn_keyword_usage (FILE* ostream); static void mlr_dsl_stderr_keyword_usage (FILE* ostream); +static void mlr_dsl_stdout_keyword_usage (FILE* ostream); +static void mlr_dsl_tee_keyword_usage (FILE* ostream); +static void mlr_dsl_unset_keyword_usage (FILE* ostream); + +// xxx make table w/ func ptrs etc. reduce code/data dup. + +// filter +// unset +// tee +// emit +// emitf +// emitp +// dump +// edump +// print +// printn +// eprint +// eprintn +// stderr +// stdout + +// E +// ENV +// FILENAME +// FILENUM +// FNR +// NF +// NR +// PI + +// all +// begin +// break +// call +// continue +// do +// elif +// else +// end +// for +// func +// if +// in +// local +// return +// subr +// while + // ================================================================ // Pass function_name == NULL to get usage for all keywords. // Note keywords are defined in dsls/mlr_dsl_lexer.l. void mlr_dsl_keyword_usage(FILE* ostream, char* keyword) { if (keyword == NULL) { - mlr_dsl_filter_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_unset_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_tee_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_emit_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_emitp_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_emitf_keyword_usage(ostream); fprintf(ostream, "\n"); mlr_dsl_dump_keyword_usage(ostream); fprintf(ostream, "\n"); mlr_dsl_edump_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_print_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_printn_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_emit_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_emitf_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_emitp_keyword_usage(ostream); fprintf(ostream, "\n"); mlr_dsl_eprint_keyword_usage(ostream); fprintf(ostream, "\n"); mlr_dsl_eprintn_keyword_usage(ostream); fprintf(ostream, "\n"); - mlr_dsl_stdout_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_filter_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_print_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_printn_keyword_usage(ostream); fprintf(ostream, "\n"); mlr_dsl_stderr_keyword_usage(ostream); + mlr_dsl_stdout_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_tee_keyword_usage(ostream); fprintf(ostream, "\n"); + mlr_dsl_unset_keyword_usage(ostream); fprintf(ostream, "\n"); return; } - if (streq(keyword, "filter")) { - mlr_dsl_filter_keyword_usage(ostream); - } else if (streq(keyword, "unset")) { - mlr_dsl_unset_keyword_usage(ostream); - } else if (streq(keyword, "tee")) { - mlr_dsl_tee_keyword_usage(ostream); - } else if (streq(keyword, "emit")) { - mlr_dsl_emit_keyword_usage(ostream); - } else if (streq(keyword, "emitp")) { - mlr_dsl_emitp_keyword_usage(ostream); - } else if (streq(keyword, "emitf")) { - mlr_dsl_emitf_keyword_usage(ostream); - } else if (streq(keyword, "dump")) { - mlr_dsl_dump_keyword_usage(ostream); - } else if (streq(keyword, "edump")) { - mlr_dsl_edump_keyword_usage(ostream); - } else if (streq(keyword, "print")) { - mlr_dsl_print_keyword_usage(ostream); - } else if (streq(keyword, "printn")) { - mlr_dsl_print_keyword_usage(ostream); - } else if (streq(keyword, "eprint")) { - mlr_dsl_eprint_keyword_usage(ostream); - } else if (streq(keyword, "eprintn")) { - mlr_dsl_eprint_keyword_usage(ostream); - } else if (streq(keyword, "stdout")) { - mlr_dsl_stdout_keyword_usage(ostream); - } else if (streq(keyword, "stderr")) { - mlr_dsl_stderr_keyword_usage(ostream); + if (streq(keyword, "dump")) { mlr_dsl_dump_keyword_usage(ostream); + } else if (streq(keyword, "edump")) { mlr_dsl_edump_keyword_usage(ostream); + } else if (streq(keyword, "emit")) { mlr_dsl_emit_keyword_usage(ostream); + } else if (streq(keyword, "emitf")) { mlr_dsl_emitf_keyword_usage(ostream); + } else if (streq(keyword, "emitp")) { mlr_dsl_emitp_keyword_usage(ostream); + } else if (streq(keyword, "eprint")) { mlr_dsl_eprint_keyword_usage(ostream); + } else if (streq(keyword, "eprintn")) { mlr_dsl_eprint_keyword_usage(ostream); + } else if (streq(keyword, "filter")) { mlr_dsl_filter_keyword_usage(ostream); + } else if (streq(keyword, "print")) { mlr_dsl_print_keyword_usage(ostream); + } else if (streq(keyword, "printn")) { mlr_dsl_print_keyword_usage(ostream); + } else if (streq(keyword, "stderr")) { mlr_dsl_stderr_keyword_usage(ostream); + } else if (streq(keyword, "stdout")) { mlr_dsl_stdout_keyword_usage(ostream); + } else if (streq(keyword, "tee")) { mlr_dsl_tee_keyword_usage(ostream); + } else if (streq(keyword, "unset")) { mlr_dsl_unset_keyword_usage(ostream); + } else { fprintf(ostream, "%s: unrecognized keyword \"%s\".\n", MLR_GLOBALS.bargv0, keyword); } } void mlr_dsl_list_all_keywords_raw(FILE* ostream) { - printf("filter\n"); - printf("unset\n"); - printf("tee\n"); - printf("emit\n"); - printf("emitp\n"); - printf("emitf\n"); printf("dump\n"); printf("edump\n"); - printf("print\n"); - printf("printn\n"); + printf("emit\n"); + printf("emitf\n"); + printf("emitp\n"); printf("eprint\n"); printf("eprintn\n"); - printf("stdout\n"); + printf("filter\n"); + printf("print\n"); + printf("printn\n"); printf("stderr\n"); + printf("stdout\n"); + printf("tee\n"); + printf("unset\n"); } // ---------------------------------------------------------------- -static void mlr_dsl_filter_keyword_usage(FILE* ostream) { +static void mlr_dsl_dump_keyword_usage(FILE* ostream) { fprintf(ostream, - "filter: includes/excludes the record in the output record stream.\n" + "dump: prints all currently defined out-of-stream variables immediately\n" + " to stdout as JSON.\n" "\n" - " Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)'\n" - "\n" - " Instead of put with 'filter false' you can simply use put -q. The following\n" - " uses the input record to accumulate data but only prints the running sum\n" - " without printing the input record:\n" - "\n" - " Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum'\n"); -} - -static void mlr_dsl_unset_keyword_usage(FILE* ostream) { - fprintf(ostream, - "unset: clears field(s) from the current record, or an out-of-stream variable.\n" - "\n" - " Example: mlr --from f.dat put 'unset $x'\n" - " Example: mlr --from f.dat put 'unset $*'\n" - " Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ \"a.*\") { unset $[k] } }'\n" - " Example: mlr --from f.dat put '...; unset @sums'\n" - " Example: mlr --from f.dat put '...; unset @sums[\"green\"]'\n" - " Example: mlr --from f.dat put '...; unset @*'\n"); -} - -static void mlr_dsl_tee_keyword_usage(FILE* ostream) { - fprintf(ostream, - "tee: prints the current record to specified file.\n" - " This is an immediate print to the specified file (except for pprint format\n" - " which of course waits until the end of the input stream to format all output).\n" + " With >, >>, or |, the data do not become part of the output record stream but\n" + " are instead redirected.\n" "\n" " The > and >> are for write and append, as in the shell, but (as with awk) the\n" " file-overwrite for > is on first write, not per record. The | is for piping to\n" @@ -130,17 +139,18 @@ static void mlr_dsl_tee_keyword_usage(FILE* ostream) { " value of the piped-to command (for |). Output-formatting flags are taken from\n" " the main command line.\n" "\n" - " You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,\n" - " etc., to control the format of the output. See also %s -h.\n" + " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }'\n" + " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > \"mytap.dat\"}'\n" + " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> \"mytap.dat\"}'\n" + " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | \"jq .[]\"}'\n"); +} + +static void mlr_dsl_edump_keyword_usage(FILE* ostream) { + fprintf(ostream, + "edump: prints all currently defined out-of-stream variables immediately\n" + " to stderr as JSON.\n" "\n" - " Example: mlr --from f.dat put 'tee > \"/tmp/data-\".$a, $*'\n" - " Example: mlr --from f.dat put 'tee >> \"/tmp/data-\".$a.$b, $*'\n" - " Example: mlr --from f.dat put 'tee > stderr, $*'\n" - " Example: mlr --from f.dat put -q 'tee | \"tr \[a-z\\] \[A-Z\\]\", $*'\n" - " Example: mlr --from f.dat put -q 'tee | \"tr \[a-z\\] \[A-Z\\] > /tmp/data-\".$a, $*'\n" - " Example: mlr --from f.dat put -q 'tee | \"gzip > /tmp/data-\".$a.\".gz\", $*'\n" - " Example: mlr --from f.dat put -q --ojson 'tee | \"gzip > /tmp/data-\".$a.\".gz\", $*'\n", - MLR_GLOBALS.bargv0); + " Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }'\n"); } static void mlr_dsl_emit_keyword_usage(FILE* ostream) { @@ -175,6 +185,37 @@ static void mlr_dsl_emit_keyword_usage(FILE* ostream) { MLR_GLOBALS.bargv0); } +static void mlr_dsl_emitf_keyword_usage(FILE* ostream) { + fprintf(ostream, + "emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the\n" + " output record stream.\n" + "\n" + " With >, >>, or |, the data do not become part of the output record stream but\n" + " are instead redirected.\n" + "\n" + " The > and >> are for write and append, as in the shell, but (as with awk) the\n" + " file-overwrite for > is on first write, not per record. The | is for piping to\n" + " a process which will process the data. There will be one open file for each\n" + " distinct file name (for > and >>) or one subordinate process for each distinct\n" + " value of the piped-to command (for |). Output-formatting flags are taken from\n" + " the main command line.\n" + "\n" + " You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,\n" + " etc., to control the format of the output if the output is redirected. See also %s -h.\n" + "\n" + " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a'\n" + " Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > \"tap-\".$i.\".dat\", @a'\n" + " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c'\n" + " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > \"mytap.dat\", @a, @b, @c'\n" + " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> \"mytap.dat\", @a, @b, @c'\n" + " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c'\n" + " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | \"grep somepattern\", @a, @b, @c'\n" + " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | \"grep somepattern > mytap.dat\", @a, @b, @c'\n" + "\n" + " Please see http://johnkerl.org/miller/doc for more information.\n", + MLR_GLOBALS.bargv0); +} + static void mlr_dsl_emitp_keyword_usage(FILE* ostream) { fprintf(ostream, "emitp: inserts an out-of-stream variable into the output record stream.\n" @@ -208,64 +249,32 @@ static void mlr_dsl_emitp_keyword_usage(FILE* ostream) { MLR_GLOBALS.bargv0); } -static void mlr_dsl_emitf_keyword_usage(FILE* ostream) { +static void mlr_dsl_eprint_keyword_usage(FILE* ostream) { fprintf(ostream, - "emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the\n" - " output record stream.\n" - "\n" - " With >, >>, or |, the data do not become part of the output record stream but\n" - " are instead redirected.\n" - "\n" - " The > and >> are for write and append, as in the shell, but (as with awk) the\n" - " file-overwrite for > is on first write, not per record. The | is for piping to\n" - " a process which will process the data. There will be one open file for each\n" - " distinct file name (for > and >>) or one subordinate process for each distinct\n" - " value of the piped-to command (for |). Output-formatting flags are taken from\n" - " the main command line.\n" - "\n" - " You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,\n" - " etc., to control the format of the output if the output is redirected. See also %s -h.\n" - "\n" - " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a'\n" - " Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > \"tap-\".$i.\".dat\", @a'\n" - " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c'\n" - " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > \"mytap.dat\", @a, @b, @c'\n" - " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> \"mytap.dat\", @a, @b, @c'\n" - " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c'\n" - " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | \"grep somepattern\", @a, @b, @c'\n" - " Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | \"grep somepattern > mytap.dat\", @a, @b, @c'\n" - "\n" - " Please see http://johnkerl.org/miller/doc for more information.\n", - MLR_GLOBALS.bargv0); + "eprint: prints expression immediately to stderr.\n" + " Example: mlr --from f.dat put -q 'eprint \"The sum of x and y is \".($x+$y)'\n" + " Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . \" => \" . v }'\n" + " Example: mlr --from f.dat put '(NR %% 1000 == 0) { eprint \"Checkpoint \".NR}'\n"); } -static void mlr_dsl_dump_keyword_usage(FILE* ostream) { +static void mlr_dsl_eprintn_keyword_usage(FILE* ostream) { fprintf(ostream, - "dump: prints all currently defined out-of-stream variables immediately\n" - " to stdout as JSON.\n" - "\n" - " With >, >>, or |, the data do not become part of the output record stream but\n" - " are instead redirected.\n" - "\n" - " The > and >> are for write and append, as in the shell, but (as with awk) the\n" - " file-overwrite for > is on first write, not per record. The | is for piping to\n" - " a process which will process the data. There will be one open file for each\n" - " distinct file name (for > and >>) or one subordinate process for each distinct\n" - " value of the piped-to command (for |). Output-formatting flags are taken from\n" - " the main command line.\n" - "\n" - " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }'\n" - " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > \"mytap.dat\"}'\n" - " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> \"mytap.dat\"}'\n" - " Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | \"jq .[]\"}'\n"); + "eprintn: prints expression immediately to stderr, without trailing newline.\n" + " Example: mlr --from f.dat put -q 'eprintn \"The sum of x and y is \".($x+$y); eprint \"\"'\n"); } -static void mlr_dsl_edump_keyword_usage(FILE* ostream) { +// ---------------------------------------------------------------- +static void mlr_dsl_filter_keyword_usage(FILE* ostream) { fprintf(ostream, - "edump: prints all currently defined out-of-stream variables immediately\n" - " to stderr as JSON.\n" + "filter: includes/excludes the record in the output record stream.\n" "\n" - " Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }'\n"); + " Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)'\n" + "\n" + " Instead of put with 'filter false' you can simply use put -q. The following\n" + " uses the input record to accumulate data but only prints the running sum\n" + " without printing the input record:\n" + "\n" + " Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum'\n"); } static void mlr_dsl_print_keyword_usage(FILE* ostream) { @@ -282,18 +291,10 @@ static void mlr_dsl_printn_keyword_usage(FILE* ostream) { " Example: mlr --from f.dat put -q 'printn \".\"; end { print \"\" }'\n"); } -static void mlr_dsl_eprint_keyword_usage(FILE* ostream) { +static void mlr_dsl_stderr_keyword_usage(FILE* ostream) { fprintf(ostream, - "eprint: prints expression immediately to stderr.\n" - " Example: mlr --from f.dat put -q 'eprint \"The sum of x and y is \".($x+$y)'\n" - " Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . \" => \" . v }'\n" - " Example: mlr --from f.dat put '(NR %% 1000 == 0) { eprint \"Checkpoint \".NR}'\n"); -} - -static void mlr_dsl_eprintn_keyword_usage(FILE* ostream) { - fprintf(ostream, - "eprintn: prints expression immediately to stderr, without trailing newline.\n" - " Example: mlr --from f.dat put -q 'eprintn \"The sum of x and y is \".($x+$y); eprint \"\"'\n"); + "stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename\n" + " to print to standard error.\n"); } static void mlr_dsl_stdout_keyword_usage(FILE* ostream) { @@ -302,8 +303,40 @@ static void mlr_dsl_stdout_keyword_usage(FILE* ostream) { " to print to standard output.\n"); } -static void mlr_dsl_stderr_keyword_usage(FILE* ostream) { +static void mlr_dsl_tee_keyword_usage(FILE* ostream) { fprintf(ostream, - "stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename\n" - " to print to standard error.\n"); + "tee: prints the current record to specified file.\n" + " This is an immediate print to the specified file (except for pprint format\n" + " which of course waits until the end of the input stream to format all output).\n" + "\n" + " The > and >> are for write and append, as in the shell, but (as with awk) the\n" + " file-overwrite for > is on first write, not per record. The | is for piping to\n" + " a process which will process the data. There will be one open file for each\n" + " distinct file name (for > and >>) or one subordinate process for each distinct\n" + " value of the piped-to command (for |). Output-formatting flags are taken from\n" + " the main command line.\n" + "\n" + " You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,\n" + " etc., to control the format of the output. See also %s -h.\n" + "\n" + " Example: mlr --from f.dat put 'tee > \"/tmp/data-\".$a, $*'\n" + " Example: mlr --from f.dat put 'tee >> \"/tmp/data-\".$a.$b, $*'\n" + " Example: mlr --from f.dat put 'tee > stderr, $*'\n" + " Example: mlr --from f.dat put -q 'tee | \"tr \[a-z\\] \[A-Z\\]\", $*'\n" + " Example: mlr --from f.dat put -q 'tee | \"tr \[a-z\\] \[A-Z\\] > /tmp/data-\".$a, $*'\n" + " Example: mlr --from f.dat put -q 'tee | \"gzip > /tmp/data-\".$a.\".gz\", $*'\n" + " Example: mlr --from f.dat put -q --ojson 'tee | \"gzip > /tmp/data-\".$a.\".gz\", $*'\n", + MLR_GLOBALS.bargv0); +} + +static void mlr_dsl_unset_keyword_usage(FILE* ostream) { + fprintf(ostream, + "unset: clears field(s) from the current record, or an out-of-stream variable.\n" + "\n" + " Example: mlr --from f.dat put 'unset $x'\n" + " Example: mlr --from f.dat put 'unset $*'\n" + " Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ \"a.*\") { unset $[k] } }'\n" + " Example: mlr --from f.dat put '...; unset @sums'\n" + " Example: mlr --from f.dat put '...; unset @sums[\"green\"]'\n" + " Example: mlr --from f.dat put '...; unset @*'\n"); } diff --git a/doc/manpage.html b/doc/manpage.html index 407e8dbb4..645efc2e1 100644 --- a/doc/manpage.html +++ b/doc/manpage.html @@ -1595,32 +1595,13 @@ FUNCTIONS FOR FILTER/PUT (class=time #args=0): Floating-point seconds since the epoch, e.g. 1440768801.748936. -KEYWORDS FOR PUT - filter - filter: includes/excludes the record in the output record stream. +KEYWORDS FOR PUT AND FILTER + dump + dump: prints all currently defined out-of-stream variables immediately + to stdout as JSON. - Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)' - - Instead of put with 'filter false' you can simply use put -q. The following - uses the input record to accumulate data but only prints the running sum - without printing the input record: - - Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum' - - unset - unset: clears field(s) from the current record, or an out-of-stream variable. - - Example: mlr --from f.dat put 'unset $x' - Example: mlr --from f.dat put 'unset $*' - Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }' - Example: mlr --from f.dat put '...; unset @sums' - Example: mlr --from f.dat put '...; unset @sums["green"]' - Example: mlr --from f.dat put '...; unset @*' - - tee - tee: prints the current record to specified file. - This is an immediate print to the specified file (except for pprint format - which of course waits until the end of the input stream to format all output). + With >, >>, or |, the data do not become part of the output record stream but + are instead redirected. The > and >> are for write and append, as in the shell, but (as with awk) the file-overwrite for > is on first write, not per record. The | is for piping to @@ -1629,16 +1610,16 @@ KEYWORDS FOR PUT value of the piped-to command (for |). Output-formatting flags are taken from the main command line. - You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, - etc., to control the format of the output. See also mlr -h. + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > "mytap.dat"}' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}' - Example: mlr --from f.dat put 'tee > "/tmp/data-".$a, $*' - Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*' - Example: mlr --from f.dat put 'tee > stderr, $*' - Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\]", $*' - Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\] > /tmp/data-".$a, $*' - Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*' - Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*' + edump + edump: prints all currently defined out-of-stream variables immediately + to stderr as JSON. + + Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }' emit emit: inserts an out-of-stream variable into the output record stream. Hashmap @@ -1669,6 +1650,34 @@ KEYWORDS FOR PUT Please see http://johnkerl.org/miller/doc for more information. + emitf + emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the + output record stream. + + With >, >>, or |, the data do not become part of the output record stream but + are instead redirected. + + The > and >> are for write and append, as in the shell, but (as with awk) the + file-overwrite for > is on first write, not per record. The | is for piping to + a process which will process the data. There will be one open file for each + distinct file name (for > and >>) or one subordinate process for each distinct + value of the piped-to command (for |). Output-formatting flags are taken from + the main command line. + + You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, + etc., to control the format of the output if the output is redirected. See also mlr -h. + + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a' + Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c' + + Please see http://johnkerl.org/miller/doc for more information. + emitp emitp: inserts an out-of-stream variable into the output record stream. Hashmap indices present in the data but not slotted by emitp arguments are @@ -1699,58 +1708,28 @@ KEYWORDS FOR PUT Please see http://johnkerl.org/miller/doc for more information. - emitf - emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the - output record stream. + eprint + eprint: prints expression immediately to stderr. + Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' + Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' + Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' - With >, >>, or |, the data do not become part of the output record stream but - are instead redirected. + eprintn + eprint: prints expression immediately to stderr. + Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' + Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' + Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' - The > and >> are for write and append, as in the shell, but (as with awk) the - file-overwrite for > is on first write, not per record. The | is for piping to - a process which will process the data. There will be one open file for each - distinct file name (for > and >>) or one subordinate process for each distinct - value of the piped-to command (for |). Output-formatting flags are taken from - the main command line. + filter + filter: includes/excludes the record in the output record stream. - You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, - etc., to control the format of the output if the output is redirected. See also mlr -h. + Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a' - Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c' + Instead of put with 'filter false' you can simply use put -q. The following + uses the input record to accumulate data but only prints the running sum + without printing the input record: - Please see http://johnkerl.org/miller/doc for more information. - - dump - dump: prints all currently defined out-of-stream variables immediately - to stdout as JSON. - - With >, >>, or |, the data do not become part of the output record stream but - are instead redirected. - - The > and >> are for write and append, as in the shell, but (as with awk) the - file-overwrite for > is on first write, not per record. The | is for piping to - a process which will process the data. There will be one open file for each - distinct file name (for > and >>) or one subordinate process for each distinct - value of the piped-to command (for |). Output-formatting flags are taken from - the main command line. - - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > "mytap.dat"}' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}' - - edump - edump: prints all currently defined out-of-stream variables immediately - to stderr as JSON. - - Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }' + Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum' print print: prints expression immediately to stdout. @@ -1764,25 +1743,46 @@ KEYWORDS FOR PUT Example: mlr --from f.dat put -q 'for (k, v in $*) { print k . " => " . v }' Example: mlr --from f.dat put '(NR % 1000 == 0) { print > stderr, "Checkpoint ".NR}' - eprint - eprint: prints expression immediately to stderr. - Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' - Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' - Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' - - eprintn - eprint: prints expression immediately to stderr. - Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' - Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' - Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' + stderr + stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename + to print to standard error. stdout stdout: Used for tee, emit, emitf, emitp, print, and dump in place of filename to print to standard output. - stderr - stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename - to print to standard error. + tee + tee: prints the current record to specified file. + This is an immediate print to the specified file (except for pprint format + which of course waits until the end of the input stream to format all output). + + The > and >> are for write and append, as in the shell, but (as with awk) the + file-overwrite for > is on first write, not per record. The | is for piping to + a process which will process the data. There will be one open file for each + distinct file name (for > and >>) or one subordinate process for each distinct + value of the piped-to command (for |). Output-formatting flags are taken from + the main command line. + + You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, + etc., to control the format of the output. See also mlr -h. + + Example: mlr --from f.dat put 'tee > "/tmp/data-".$a, $*' + Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*' + Example: mlr --from f.dat put 'tee > stderr, $*' + Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\]", $*' + Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\] > /tmp/data-".$a, $*' + Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*' + Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*' + + unset + unset: clears field(s) from the current record, or an out-of-stream variable. + + Example: mlr --from f.dat put 'unset $x' + Example: mlr --from f.dat put 'unset $*' + Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }' + Example: mlr --from f.dat put '...; unset @sums' + Example: mlr --from f.dat put '...; unset @sums["green"]' + Example: mlr --from f.dat put '...; unset @*' AUTHOR Miller is written by John Kerl <kerl.john.r@gmail.com>. @@ -1797,7 +1797,7 @@ SEE ALSO - 2016-09-30 MILLER(1) + 2016-10-01 MILLER(1)

diff --git a/doc/manpage.txt b/doc/manpage.txt index 5d81d5fea..4ebc2f82e 100644 --- a/doc/manpage.txt +++ b/doc/manpage.txt @@ -1448,32 +1448,13 @@ FUNCTIONS FOR FILTER/PUT (class=time #args=0): Floating-point seconds since the epoch, e.g. 1440768801.748936. -KEYWORDS FOR PUT - filter - filter: includes/excludes the record in the output record stream. +KEYWORDS FOR PUT AND FILTER + dump + dump: prints all currently defined out-of-stream variables immediately + to stdout as JSON. - Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)' - - Instead of put with 'filter false' you can simply use put -q. The following - uses the input record to accumulate data but only prints the running sum - without printing the input record: - - Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum' - - unset - unset: clears field(s) from the current record, or an out-of-stream variable. - - Example: mlr --from f.dat put 'unset $x' - Example: mlr --from f.dat put 'unset $*' - Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }' - Example: mlr --from f.dat put '...; unset @sums' - Example: mlr --from f.dat put '...; unset @sums["green"]' - Example: mlr --from f.dat put '...; unset @*' - - tee - tee: prints the current record to specified file. - This is an immediate print to the specified file (except for pprint format - which of course waits until the end of the input stream to format all output). + With >, >>, or |, the data do not become part of the output record stream but + are instead redirected. The > and >> are for write and append, as in the shell, but (as with awk) the file-overwrite for > is on first write, not per record. The | is for piping to @@ -1482,16 +1463,16 @@ KEYWORDS FOR PUT value of the piped-to command (for |). Output-formatting flags are taken from the main command line. - You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, - etc., to control the format of the output. See also mlr -h. + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > "mytap.dat"}' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}' - Example: mlr --from f.dat put 'tee > "/tmp/data-".$a, $*' - Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*' - Example: mlr --from f.dat put 'tee > stderr, $*' - Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\]", $*' - Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\] > /tmp/data-".$a, $*' - Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*' - Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*' + edump + edump: prints all currently defined out-of-stream variables immediately + to stderr as JSON. + + Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }' emit emit: inserts an out-of-stream variable into the output record stream. Hashmap @@ -1522,6 +1503,34 @@ KEYWORDS FOR PUT Please see http://johnkerl.org/miller/doc for more information. + emitf + emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the + output record stream. + + With >, >>, or |, the data do not become part of the output record stream but + are instead redirected. + + The > and >> are for write and append, as in the shell, but (as with awk) the + file-overwrite for > is on first write, not per record. The | is for piping to + a process which will process the data. There will be one open file for each + distinct file name (for > and >>) or one subordinate process for each distinct + value of the piped-to command (for |). Output-formatting flags are taken from + the main command line. + + You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, + etc., to control the format of the output if the output is redirected. See also mlr -h. + + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a' + Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c' + + Please see http://johnkerl.org/miller/doc for more information. + emitp emitp: inserts an out-of-stream variable into the output record stream. Hashmap indices present in the data but not slotted by emitp arguments are @@ -1552,58 +1561,28 @@ KEYWORDS FOR PUT Please see http://johnkerl.org/miller/doc for more information. - emitf - emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the - output record stream. + eprint + eprint: prints expression immediately to stderr. + Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' + Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' + Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' - With >, >>, or |, the data do not become part of the output record stream but - are instead redirected. + eprintn + eprint: prints expression immediately to stderr. + Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' + Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' + Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' - The > and >> are for write and append, as in the shell, but (as with awk) the - file-overwrite for > is on first write, not per record. The | is for piping to - a process which will process the data. There will be one open file for each - distinct file name (for > and >>) or one subordinate process for each distinct - value of the piped-to command (for |). Output-formatting flags are taken from - the main command line. + filter + filter: includes/excludes the record in the output record stream. - You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, - etc., to control the format of the output if the output is redirected. See also mlr -h. + Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a' - Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c' + Instead of put with 'filter false' you can simply use put -q. The following + uses the input record to accumulate data but only prints the running sum + without printing the input record: - Please see http://johnkerl.org/miller/doc for more information. - - dump - dump: prints all currently defined out-of-stream variables immediately - to stdout as JSON. - - With >, >>, or |, the data do not become part of the output record stream but - are instead redirected. - - The > and >> are for write and append, as in the shell, but (as with awk) the - file-overwrite for > is on first write, not per record. The | is for piping to - a process which will process the data. There will be one open file for each - distinct file name (for > and >>) or one subordinate process for each distinct - value of the piped-to command (for |). Output-formatting flags are taken from - the main command line. - - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > "mytap.dat"}' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}' - - edump - edump: prints all currently defined out-of-stream variables immediately - to stderr as JSON. - - Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }' + Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum' print print: prints expression immediately to stdout. @@ -1617,25 +1596,46 @@ KEYWORDS FOR PUT Example: mlr --from f.dat put -q 'for (k, v in $*) { print k . " => " . v }' Example: mlr --from f.dat put '(NR % 1000 == 0) { print > stderr, "Checkpoint ".NR}' - eprint - eprint: prints expression immediately to stderr. - Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' - Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' - Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' - - eprintn - eprint: prints expression immediately to stderr. - Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' - Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' - Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' + stderr + stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename + to print to standard error. stdout stdout: Used for tee, emit, emitf, emitp, print, and dump in place of filename to print to standard output. - stderr - stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename - to print to standard error. + tee + tee: prints the current record to specified file. + This is an immediate print to the specified file (except for pprint format + which of course waits until the end of the input stream to format all output). + + The > and >> are for write and append, as in the shell, but (as with awk) the + file-overwrite for > is on first write, not per record. The | is for piping to + a process which will process the data. There will be one open file for each + distinct file name (for > and >>) or one subordinate process for each distinct + value of the piped-to command (for |). Output-formatting flags are taken from + the main command line. + + You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, + etc., to control the format of the output. See also mlr -h. + + Example: mlr --from f.dat put 'tee > "/tmp/data-".$a, $*' + Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*' + Example: mlr --from f.dat put 'tee > stderr, $*' + Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\]", $*' + Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\] > /tmp/data-".$a, $*' + Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*' + Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*' + + unset + unset: clears field(s) from the current record, or an out-of-stream variable. + + Example: mlr --from f.dat put 'unset $x' + Example: mlr --from f.dat put 'unset $*' + Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }' + Example: mlr --from f.dat put '...; unset @sums' + Example: mlr --from f.dat put '...; unset @sums["green"]' + Example: mlr --from f.dat put '...; unset @*' AUTHOR Miller is written by John Kerl . @@ -1650,4 +1650,4 @@ SEE ALSO - 2016-09-30 MILLER(1) + 2016-10-01 MILLER(1) diff --git a/doc/mkman.rb b/doc/mkman.rb index a105126ed..35c48adb3 100755 --- a/doc/mkman.rb +++ b/doc/mkman.rb @@ -108,7 +108,7 @@ output separator to the given value.""" end keywords = `mlr --list-all-keywords-raw` - print make_section('KEYWORDS FOR PUT', [ + print make_section('KEYWORDS FOR PUT AND FILTER', [ "" ]) keywords = keywords.strip.split("\n").uniq diff --git a/doc/mlr.1 b/doc/mlr.1 index 6774924a8..2facaee7d 100644 --- a/doc/mlr.1 +++ b/doc/mlr.1 @@ -2,12 +2,12 @@ .\" Title: mlr .\" Author: [see the "AUTHOR" section] .\" Generator: ./mkman.rb -.\" Date: 2016-09-30 +.\" Date: 2016-10-01 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "MILLER" "1" "2016-09-30" "\ \&" "\ \&" +.TH "MILLER" "1" "2016-10-01" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Portability definitions .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2433,50 +2433,19 @@ e.g. 1440768801.748936. .fi .if n \{\ .RE -.SH "KEYWORDS FOR PUT" +.SH "KEYWORDS FOR PUT AND FILTER" .sp -.SS "filter" +.SS "dump" .if n \{\ .RS 0 .\} .nf -filter: includes/excludes the record in the output record stream. +dump: prints all currently defined out-of-stream variables immediately + to stdout as JSON. - Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)' - - Instead of put with 'filter false' you can simply use put -q. The following - uses the input record to accumulate data but only prints the running sum - without printing the input record: - - Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum' -.fi -.if n \{\ -.RE -.SS "unset" -.if n \{\ -.RS 0 -.\} -.nf -unset: clears field(s) from the current record, or an out-of-stream variable. - - Example: mlr --from f.dat put 'unset $x' - Example: mlr --from f.dat put 'unset $*' - Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }' - Example: mlr --from f.dat put '...; unset @sums' - Example: mlr --from f.dat put '...; unset @sums["green"]' - Example: mlr --from f.dat put '...; unset @*' -.fi -.if n \{\ -.RE -.SS "tee" -.if n \{\ -.RS 0 -.\} -.nf -tee: prints the current record to specified file. - This is an immediate print to the specified file (except for pprint format - which of course waits until the end of the input stream to format all output). + With >, >>, or |, the data do not become part of the output record stream but + are instead redirected. The > and >> are for write and append, as in the shell, but (as with awk) the file-overwrite for > is on first write, not per record. The | is for piping to @@ -2485,16 +2454,22 @@ tee: prints the current record to specified file. value of the piped-to command (for |). Output-formatting flags are taken from the main command line. - You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, - etc., to control the format of the output. See also mlr -h. + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > "mytap.dat"}' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}' +.fi +.if n \{\ +.RE +.SS "edump" +.if n \{\ +.RS 0 +.\} +.nf +edump: prints all currently defined out-of-stream variables immediately + to stderr as JSON. - Example: mlr --from f.dat put 'tee > "/tmp/data-".$a, $*' - Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*' - Example: mlr --from f.dat put 'tee > stderr, $*' - Example: mlr --from f.dat put -q 'tee | "tr [a-z\e] [A-Z\e]", $*' - Example: mlr --from f.dat put -q 'tee | "tr [a-z\e] [A-Z\e] > /tmp/data-".$a, $*' - Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*' - Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*' + Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }' .fi .if n \{\ .RE @@ -2533,6 +2508,40 @@ emit: inserts an out-of-stream variable into the output record stream. Hashmap .fi .if n \{\ .RE +.SS "emitf" +.if n \{\ +.RS 0 +.\} +.nf +emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the + output record stream. + + With >, >>, or |, the data do not become part of the output record stream but + are instead redirected. + + The > and >> are for write and append, as in the shell, but (as with awk) the + file-overwrite for > is on first write, not per record. The | is for piping to + a process which will process the data. There will be one open file for each + distinct file name (for > and >>) or one subordinate process for each distinct + value of the piped-to command (for |). Output-formatting flags are taken from + the main command line. + + You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, + etc., to control the format of the output if the output is redirected. See also mlr -h. + + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a' + Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c' + Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c' + + Please see http://johnkerl.org/miller/doc for more information. +.fi +.if n \{\ +.RE .SS "emitp" .if n \{\ .RS 0 @@ -2569,74 +2578,44 @@ emitp: inserts an out-of-stream variable into the output record stream. .fi .if n \{\ .RE -.SS "emitf" +.SS "eprint" .if n \{\ .RS 0 .\} .nf -emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the - output record stream. - - With >, >>, or |, the data do not become part of the output record stream but - are instead redirected. - - The > and >> are for write and append, as in the shell, but (as with awk) the - file-overwrite for > is on first write, not per record. The | is for piping to - a process which will process the data. There will be one open file for each - distinct file name (for > and >>) or one subordinate process for each distinct - value of the piped-to command (for |). Output-formatting flags are taken from - the main command line. - - You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, - etc., to control the format of the output if the output is redirected. See also mlr -h. - - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a' - Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c' - Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c' - - Please see http://johnkerl.org/miller/doc for more information. +eprint: prints expression immediately to stderr. + Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' + Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' + Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' .fi .if n \{\ .RE -.SS "dump" +.SS "eprintn" .if n \{\ .RS 0 .\} .nf -dump: prints all currently defined out-of-stream variables immediately - to stdout as JSON. - - With >, >>, or |, the data do not become part of the output record stream but - are instead redirected. - - The > and >> are for write and append, as in the shell, but (as with awk) the - file-overwrite for > is on first write, not per record. The | is for piping to - a process which will process the data. There will be one open file for each - distinct file name (for > and >>) or one subordinate process for each distinct - value of the piped-to command (for |). Output-formatting flags are taken from - the main command line. - - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump > "mytap.dat"}' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}' - Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}' +eprint: prints expression immediately to stderr. + Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' + Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' + Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' .fi .if n \{\ .RE -.SS "edump" +.SS "filter" .if n \{\ .RS 0 .\} .nf -edump: prints all currently defined out-of-stream variables immediately - to stderr as JSON. +filter: includes/excludes the record in the output record stream. - Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }' + Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)' + + Instead of put with 'filter false' you can simply use put -q. The following + uses the input record to accumulate data but only prints the running sum + without printing the input record: + + Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum' .fi .if n \{\ .RE @@ -2664,27 +2643,13 @@ print: prints expression immediately to stdout. .fi .if n \{\ .RE -.SS "eprint" +.SS "stderr" .if n \{\ .RS 0 .\} .nf -eprint: prints expression immediately to stderr. - Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' - Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' - Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' -.fi -.if n \{\ -.RE -.SS "eprintn" -.if n \{\ -.RS 0 -.\} -.nf -eprint: prints expression immediately to stderr. - Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)' - Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }' - Example: mlr --from f.dat put '(NR % 1000 == 0) { eprint "Checkpoint ".NR}' +stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename + to print to standard error. .fi .if n \{\ .RE @@ -2698,13 +2663,48 @@ stdout: Used for tee, emit, emitf, emitp, print, and dump in place of filename .fi .if n \{\ .RE -.SS "stderr" +.SS "tee" .if n \{\ .RS 0 .\} .nf -stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename - to print to standard error. +tee: prints the current record to specified file. + This is an immediate print to the specified file (except for pprint format + which of course waits until the end of the input stream to format all output). + + The > and >> are for write and append, as in the shell, but (as with awk) the + file-overwrite for > is on first write, not per record. The | is for piping to + a process which will process the data. There will be one open file for each + distinct file name (for > and >>) or one subordinate process for each distinct + value of the piped-to command (for |). Output-formatting flags are taken from + the main command line. + + You can use any of the output-format command-line flags, e.g. --ocsv, --ofs, + etc., to control the format of the output. See also mlr -h. + + Example: mlr --from f.dat put 'tee > "/tmp/data-".$a, $*' + Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*' + Example: mlr --from f.dat put 'tee > stderr, $*' + Example: mlr --from f.dat put -q 'tee | "tr [a-z\e] [A-Z\e]", $*' + Example: mlr --from f.dat put -q 'tee | "tr [a-z\e] [A-Z\e] > /tmp/data-".$a, $*' + Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*' + Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*' +.fi +.if n \{\ +.RE +.SS "unset" +.if n \{\ +.RS 0 +.\} +.nf +unset: clears field(s) from the current record, or an out-of-stream variable. + + Example: mlr --from f.dat put 'unset $x' + Example: mlr --from f.dat put 'unset $*' + Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }' + Example: mlr --from f.dat put '...; unset @sums' + Example: mlr --from f.dat put '...; unset @sums["green"]' + Example: mlr --from f.dat put '...; unset @*' .fi .if n \{\ .RE diff --git a/doc/reference.html b/doc/reference.html index 88d1f246d..f9f8136f1 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -4579,28 +4579,11 @@ eks pan 2 0.7586799647899636 0.5221511083334797 

 $ mlr --help-all-keywords
-filter: includes/excludes the record in the output record stream.
+dump: prints all currently defined out-of-stream variables immediately
+  to stdout as JSON.
 
-  Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)'
-
-  Instead of put with 'filter false' you can simply use put -q.  The following
-  uses the input record to accumulate data but only prints the running sum
-  without printing the input record:
-
-  Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum'
-
-unset: clears field(s) from the current record, or an out-of-stream variable.
-
-  Example: mlr --from f.dat put 'unset $x'
-  Example: mlr --from f.dat put 'unset $*'
-  Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }'
-  Example: mlr --from f.dat put '...; unset @sums'
-  Example: mlr --from f.dat put '...; unset @sums["green"]'
-  Example: mlr --from f.dat put '...; unset @*'
-
-tee: prints the current record to specified file.
-  This is an immediate print to the specified file (except for pprint format
-  which of course waits until the end of the input stream to format all output).
+  With >, >>, or |, the data do not become part of the output record stream but
+  are instead redirected.
 
   The > and >> are for write and append, as in the shell, but (as with awk) the
   file-overwrite for > is on first write, not per record. The | is for piping to
@@ -4609,16 +4592,15 @@ tee: prints the current record to specified file.
   value of the piped-to command (for |). Output-formatting flags are taken from
   the main command line.
 
-  You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,
-  etc., to control the format of the output. See also mlr -h.
+  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }'
+  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >  "mytap.dat"}'
+  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}'
+  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}'
 
-  Example: mlr --from f.dat put 'tee >  "/tmp/data-".$a, $*'
-  Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*'
-  Example: mlr --from f.dat put 'tee >  stderr, $*'
-  Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\]", $*'
-  Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\] > /tmp/data-".$a, $*'
-  Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*'
-  Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*'
+edump: prints all currently defined out-of-stream variables immediately
+  to stderr as JSON.
+
+  Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }'
 
 emit: inserts an out-of-stream variable into the output record stream. Hashmap
   indices present in the data but not slotted by emit arguments are not output.
@@ -4648,6 +4630,33 @@ emit: inserts an out-of-stream variable into the output record stream. Hashmap
 
   Please see http://johnkerl.org/miller/doc for more information.
 
+emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the
+  output record stream.
+
+  With >, >>, or |, the data do not become part of the output record stream but
+  are instead redirected.
+
+  The > and >> are for write and append, as in the shell, but (as with awk) the
+  file-overwrite for > is on first write, not per record. The | is for piping to
+  a process which will process the data. There will be one open file for each
+  distinct file name (for > and >>) or one subordinate process for each distinct
+  value of the piped-to command (for |). Output-formatting flags are taken from
+  the main command line.
+
+  You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,
+  etc., to control the format of the output if the output is redirected. See also mlr -h.
+
+  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a'
+  Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a'
+  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c'
+  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c'
+  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c'
+  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c'
+  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c'
+  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c'
+
+  Please see http://johnkerl.org/miller/doc for more information.
+
 emitp: inserts an out-of-stream variable into the output record stream.
   Hashmap indices present in the data but not slotted by emitp arguments are
   output concatenated with ":".
@@ -4677,55 +4686,23 @@ emitp: inserts an out-of-stream variable into the output record stream.
 
   Please see http://johnkerl.org/miller/doc for more information.
 
-emitf: inserts non-indexed out-of-stream variable(s) side-by-side into the
-  output record stream.
+eprint: prints expression immediately to stderr.
+  Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)'
+  Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }'
+  Example: mlr --from f.dat put  '(NR % 1000 == 0) { eprint "Checkpoint ".NR}'
 
-  With >, >>, or |, the data do not become part of the output record stream but
-  are instead redirected.
+eprintn: prints expression immediately to stderr, without trailing newline.
+  Example: mlr --from f.dat put -q 'eprintn "The sum of x and y is ".($x+$y); eprint ""'
 
-  The > and >> are for write and append, as in the shell, but (as with awk) the
-  file-overwrite for > is on first write, not per record. The | is for piping to
-  a process which will process the data. There will be one open file for each
-  distinct file name (for > and >>) or one subordinate process for each distinct
-  value of the piped-to command (for |). Output-formatting flags are taken from
-  the main command line.
+filter: includes/excludes the record in the output record stream.
 
-  You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,
-  etc., to control the format of the output if the output is redirected. See also mlr -h.
+  Example: mlr --from f.dat put 'filter (NR == 2 || $x > 5.4)'
 
-  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a'
-  Example: mlr --from f.dat put --oxtab '@a=$i;@b+=$x;@c+=$y; emitf > "tap-".$i.".dat", @a'
-  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf @a, @b, @c'
-  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > "mytap.dat", @a, @b, @c'
-  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf >> "mytap.dat", @a, @b, @c'
-  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf > stderr, @a, @b, @c'
-  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern", @a, @b, @c'
-  Example: mlr --from f.dat put '@a=$i;@b+=$x;@c+=$y; emitf | "grep somepattern > mytap.dat", @a, @b, @c'
+  Instead of put with 'filter false' you can simply use put -q.  The following
+  uses the input record to accumulate data but only prints the running sum
+  without printing the input record:
 
-  Please see http://johnkerl.org/miller/doc for more information.
-
-dump: prints all currently defined out-of-stream variables immediately
-  to stdout as JSON.
-
-  With >, >>, or |, the data do not become part of the output record stream but
-  are instead redirected.
-
-  The > and >> are for write and append, as in the shell, but (as with awk) the
-  file-overwrite for > is on first write, not per record. The | is for piping to
-  a process which will process the data. There will be one open file for each
-  distinct file name (for > and >>) or one subordinate process for each distinct
-  value of the piped-to command (for |). Output-formatting flags are taken from
-  the main command line.
-
-  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump }'
-  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >  "mytap.dat"}'
-  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump >> "mytap.dat"}'
-  Example: mlr --from f.dat put -q '@v[NR]=$*; end { dump | "jq .[]"}'
-
-edump: prints all currently defined out-of-stream variables immediately
-  to stderr as JSON.
-
-  Example: mlr --from f.dat put -q '@v[NR]=$*; end { edump }'
+  Example: mlr --from f.dat put -q '@running_sum += $x * $y; emit @running_sum'
 
 print: prints expression immediately to stdout.
   Example: mlr --from f.dat put -q 'print "The sum of x and y is ".($x+$y)'
@@ -4735,19 +4712,41 @@ print: prints expression immediately to stdout.
 printn: prints expression immediately to stdout, without trailing newline.
   Example: mlr --from f.dat put -q 'printn "."; end { print "" }'
 
-eprint: prints expression immediately to stderr.
-  Example: mlr --from f.dat put -q 'eprint "The sum of x and y is ".($x+$y)'
-  Example: mlr --from f.dat put -q 'for (k, v in $*) { eprint k . " => " . v }'
-  Example: mlr --from f.dat put  '(NR % 1000 == 0) { eprint "Checkpoint ".NR}'
-
-eprintn: prints expression immediately to stderr, without trailing newline.
-  Example: mlr --from f.dat put -q 'eprintn "The sum of x and y is ".($x+$y); eprint ""'
-
+stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename
+  to print to standard error.
 stdout: Used for tee, emit, emitf, emitp, print, and dump in place of filename
   to print to standard output.
 
-stderr: Used for tee, emit, emitf, emitp, print, and dump in place of filename
-  to print to standard error.
+tee: prints the current record to specified file.
+  This is an immediate print to the specified file (except for pprint format
+  which of course waits until the end of the input stream to format all output).
+
+  The > and >> are for write and append, as in the shell, but (as with awk) the
+  file-overwrite for > is on first write, not per record. The | is for piping to
+  a process which will process the data. There will be one open file for each
+  distinct file name (for > and >>) or one subordinate process for each distinct
+  value of the piped-to command (for |). Output-formatting flags are taken from
+  the main command line.
+
+  You can use any of the output-format command-line flags, e.g. --ocsv, --ofs,
+  etc., to control the format of the output. See also mlr -h.
+
+  Example: mlr --from f.dat put 'tee >  "/tmp/data-".$a, $*'
+  Example: mlr --from f.dat put 'tee >> "/tmp/data-".$a.$b, $*'
+  Example: mlr --from f.dat put 'tee >  stderr, $*'
+  Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\]", $*'
+  Example: mlr --from f.dat put -q 'tee | "tr [a-z\] [A-Z\] > /tmp/data-".$a, $*'
+  Example: mlr --from f.dat put -q 'tee | "gzip > /tmp/data-".$a.".gz", $*'
+  Example: mlr --from f.dat put -q --ojson 'tee | "gzip > /tmp/data-".$a.".gz", $*'
+
+unset: clears field(s) from the current record, or an out-of-stream variable.
+
+  Example: mlr --from f.dat put 'unset $x'
+  Example: mlr --from f.dat put 'unset $*'
+  Example: mlr --from f.dat put 'for (k, v in $*) { if (k =~ "a.*") { unset $[k] } }'
+  Example: mlr --from f.dat put '...; unset @sums'
+  Example: mlr --from f.dat put '...; unset @sums["green"]'
+  Example: mlr --from f.dat put '...; unset @*'