From 003455bc7c4044bce532934ad8dbdde3979d9e8a Mon Sep 17 00:00:00 2001 From: John Kerl Date: Wed, 19 Aug 2020 11:26:03 -0400 Subject: [PATCH] mlrrc in mlr --help and man mlr --- c/cli/mlrcli.c | 42 ++++++++++++++++++++++++++++++++++++++++++ doc/manpage.html | 33 +++++++++++++++++++++++++++++++++ doc/manpage.txt | 33 +++++++++++++++++++++++++++++++++ doc/mkman.rb | 4 ++++ doc/mlr.1 | 39 +++++++++++++++++++++++++++++++++++++++ doc/reference.html | 33 +++++++++++++++++++++++++++++++++ 6 files changed, 184 insertions(+) diff --git a/c/cli/mlrcli.c b/c/cli/mlrcli.c index 2fb2e82a6..9da3e0da6 100644 --- a/c/cli/mlrcli.c +++ b/c/cli/mlrcli.c @@ -136,6 +136,7 @@ static void main_usage_examples(FILE* o, char* argv0, char* leader); static void list_all_verbs_raw(FILE* o); static void list_all_verbs(FILE* o, char* leader); static void main_usage_help_options(FILE* o, char* argv0); +static void main_usage_mlrrc(FILE* o, char* argv0); static void main_usage_functions(FILE* o, char* argv0, char* leader); static void main_usage_data_format_examples(FILE* o, char* argv0); static void main_usage_data_format_options(FILE* o, char* argv0); @@ -517,6 +518,10 @@ static void main_usage_long(FILE* o, char* argv0) { main_usage_help_options(o, argv0); fprintf(o, "\n"); + fprintf(o, "Customization via .mlrrc:\n"); + main_usage_mlrrc(o, argv0); + fprintf(o, "\n"); + fprintf(o, "Verbs:\n"); list_all_verbs(o, " "); fprintf(o, "\n"); @@ -644,6 +649,40 @@ static void main_usage_help_options(FILE* o, char* argv0) { fprintf(o, " -K Show a bare listing of keywords by name.\n"); } +static void main_usage_mlrrc(FILE* o, char* argv0) { + fprintf(o, "You can set up personal defaults via a $HOME/.mlrrc and/or ./.mlrrc.\n"); + fprintf(o, "For example, if you usually process CSV, then you can put \"--csv\" in your .mlrrc file\n"); + fprintf(o, "and that will be the default input/output format unless otherwise specified on the command line.\n"); + fprintf(o, "\n"); + fprintf(o, "The .mlrrc file format is one \"--flag\" or \"--option value\" per line, with the leading \"--\" optional.\n"); + fprintf(o, "Hash-style comments and blank lines are ignored.\n"); + fprintf(o, "\n"); + fprintf(o, "Sample .mlrrc:\n"); + fprintf(o, "# Input and output formats are CSV by default (unless otherwise specified\n"); + fprintf(o, "# on the mlr command line):\n"); + fprintf(o, "csv\n"); + fprintf(o, "# These are no-ops for CSV, but when I do use JSON output, I want these\n"); + fprintf(o, "# pretty-printing options to be used:\n"); + fprintf(o, "jvstack\n"); + fprintf(o, "jlistwrap\n"); + fprintf(o, "\n"); + fprintf(o, "How to specify location of .mlrrc:\n"); + fprintf(o, "* If $MLRRC is set:\n"); + fprintf(o, " o If its value is \"__none__\" then no .mlrrc files are processed.\n"); + fprintf(o, " o Otherwise, its value (as a filename) is loaded and processed. If there are syntax\n"); + fprintf(o, " errors, they abort mlr with a usage message (as if you had mistyped something on the\n"); + fprintf(o, " command line). If the file can't be loaded at all, though, it is silently skipped.\n"); + fprintf(o, " o Any .mlrrc in your home directory or current directory is ignored whenever $MLRRC is\n"); + fprintf(o, " set in the environment.\n"); + fprintf(o, "* Otherwise:\n"); + fprintf(o, " o If $HOME/.mlrrc exists, it's then processed as above.\n"); + fprintf(o, " o If ./.mlrrc exists, it's then also processed as above.\n"); + fprintf(o, " (I.e. current-directory .mlrrc defaults are stacked over home-directory .mlrrc defaults.)\n"); + fprintf(o, "\n"); + fprintf(o, "See also:\n"); + fprintf(o, "https://johnkerl.org/miller/doc/customization.html\n"); +} + static void main_usage_functions(FILE* o, char* argv0, char* leader) { fmgr_t* pfmgr = fmgr_alloc(); fmgr_list_functions(pfmgr, o, leader); @@ -1532,6 +1571,9 @@ static int handle_terminal_usage(char** argv, int argc, int argi) { } else if (streq(argv[argi], "--usage-help-options")) { main_usage_help_options(stdout, MLR_GLOBALS.bargv0); return TRUE; + } else if (streq(argv[argi], "--usage-mlrrc")) { + main_usage_mlrrc(stdout, MLR_GLOBALS.bargv0); + return TRUE; } else if (streq(argv[argi], "--usage-functions")) { main_usage_functions(stdout, MLR_GLOBALS.bargv0, ""); return TRUE; diff --git a/doc/manpage.html b/doc/manpage.html index 618dbdf38..77ba45b67 100644 --- a/doc/manpage.html +++ b/doc/manpage.html @@ -470,6 +470,39 @@ OPTIONS netbsd-strptime For more information, please invoke mlr {subcommand} --help +MLRRC + You can set up personal defaults via a $HOME/.mlrrc and/or ./.mlrrc. + For example, if you usually process CSV, then you can put "--csv" in your .mlrrc file + and that will be the default input/output format unless otherwise specified on the command line. + + The .mlrrc file format is one "--flag" or "--option value" per line, with the leading "--" optional. + Hash-style comments and blank lines are ignored. + + Sample .mlrrc: + # Input and output formats are CSV by default (unless otherwise specified + # on the mlr command line): + csv + # These are no-ops for CSV, but when I do use JSON output, I want these + # pretty-printing options to be used: + jvstack + jlistwrap + + How to specify location of .mlrrc: + * If $MLRRC is set: + o If its value is "__none__" then no .mlrrc files are processed. + o Otherwise, its value (as a filename) is loaded and processed. If there are syntax + errors, they abort mlr with a usage message (as if you had mistyped something on the + command line). If the file can't be loaded at all, though, it is silently skipped. + o Any .mlrrc in your home directory or current directory is ignored whenever $MLRRC is + set in the environment. + * Otherwise: + o If $HOME/.mlrrc exists, it's then processed as above. + o If ./.mlrrc exists, it's then also processed as above. + (I.e. current-directory .mlrrc defaults are stacked over home-directory .mlrrc defaults.) + + See also: + https://johnkerl.org/miller/doc/customization.html + VERBS altkv Usage: mlr altkv [no options] diff --git a/doc/manpage.txt b/doc/manpage.txt index eae82fa1e..380e0c3b7 100644 --- a/doc/manpage.txt +++ b/doc/manpage.txt @@ -396,6 +396,39 @@ OPTIONS netbsd-strptime For more information, please invoke mlr {subcommand} --help +MLRRC + You can set up personal defaults via a $HOME/.mlrrc and/or ./.mlrrc. + For example, if you usually process CSV, then you can put "--csv" in your .mlrrc file + and that will be the default input/output format unless otherwise specified on the command line. + + The .mlrrc file format is one "--flag" or "--option value" per line, with the leading "--" optional. + Hash-style comments and blank lines are ignored. + + Sample .mlrrc: + # Input and output formats are CSV by default (unless otherwise specified + # on the mlr command line): + csv + # These are no-ops for CSV, but when I do use JSON output, I want these + # pretty-printing options to be used: + jvstack + jlistwrap + + How to specify location of .mlrrc: + * If $MLRRC is set: + o If its value is "__none__" then no .mlrrc files are processed. + o Otherwise, its value (as a filename) is loaded and processed. If there are syntax + errors, they abort mlr with a usage message (as if you had mistyped something on the + command line). If the file can't be loaded at all, though, it is silently skipped. + o Any .mlrrc in your home directory or current directory is ignored whenever $MLRRC is + set in the environment. + * Otherwise: + o If $HOME/.mlrrc exists, it's then processed as above. + o If ./.mlrrc exists, it's then also processed as above. + (I.e. current-directory .mlrrc defaults are stacked over home-directory .mlrrc defaults.) + + See also: + https://johnkerl.org/miller/doc/customization.html + VERBS altkv Usage: mlr altkv [no options] diff --git a/doc/mkman.rb b/doc/mkman.rb index dfbd0d60e..1cadc1dcd 100755 --- a/doc/mkman.rb +++ b/doc/mkman.rb @@ -95,6 +95,10 @@ output separator to the given value.""" print make_subsection('AUXILIARY COMMANDS', []) print make_code_block(`mlr --usage-auxents`) + print make_section('MLRRC', []) + + print make_code_block(`mlr --usage-mlrrc`) + verbs = `mlr --list-all-verbs-raw` print make_section('VERBS', [ "" diff --git a/doc/mlr.1 b/doc/mlr.1 index 7df5a7cca..7ce67562f 100644 --- a/doc/mlr.1 +++ b/doc/mlr.1 @@ -513,6 +513,45 @@ For more information, please invoke mlr {subcommand} --help .fi .if n \{\ .RE +.SH "MLRRC" +.if n \{\ +.RS 0 +.\} +.nf +You can set up personal defaults via a $HOME/.mlrrc and/or ./.mlrrc. +For example, if you usually process CSV, then you can put "--csv" in your .mlrrc file +and that will be the default input/output format unless otherwise specified on the command line. + +The .mlrrc file format is one "--flag" or "--option value" per line, with the leading "--" optional. +Hash-style comments and blank lines are ignored. + +Sample .mlrrc: +# Input and output formats are CSV by default (unless otherwise specified +# on the mlr command line): +csv +# These are no-ops for CSV, but when I do use JSON output, I want these +# pretty-printing options to be used: +jvstack +jlistwrap + +How to specify location of .mlrrc: +* If $MLRRC is set: + o If its value is "__none__" then no .mlrrc files are processed. + o Otherwise, its value (as a filename) is loaded and processed. If there are syntax + errors, they abort mlr with a usage message (as if you had mistyped something on the + command line). If the file can't be loaded at all, though, it is silently skipped. + o Any .mlrrc in your home directory or current directory is ignored whenever $MLRRC is + set in the environment. +* Otherwise: + o If $HOME/.mlrrc exists, it's then processed as above. + o If ./.mlrrc exists, it's then also processed as above. + (I.e. current-directory .mlrrc defaults are stacked over home-directory .mlrrc defaults.) + +See also: +https://johnkerl.org/miller/doc/customization.html +.fi +.if n \{\ +.RE .SH "VERBS" .sp diff --git a/doc/reference.html b/doc/reference.html index 81074565f..e96065962 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -1323,6 +1323,39 @@ Help options: -k or --help-all-keywords Show help on all keywords. -K Show a bare listing of keywords by name. +Customization via .mlrrc: +You can set up personal defaults via a $HOME/.mlrrc and/or ./.mlrrc. +For example, if you usually process CSV, then you can put "--csv" in your .mlrrc file +and that will be the default input/output format unless otherwise specified on the command line. + +The .mlrrc file format is one "--flag" or "--option value" per line, with the leading "--" optional. +Hash-style comments and blank lines are ignored. + +Sample .mlrrc: +# Input and output formats are CSV by default (unless otherwise specified +# on the mlr command line): +csv +# These are no-ops for CSV, but when I do use JSON output, I want these +# pretty-printing options to be used: +jvstack +jlistwrap + +How to specify location of .mlrrc: +* If $MLRRC is set: + o If its value is "__none__" then no .mlrrc files are processed. + o Otherwise, its value (as a filename) is loaded and processed. If there are syntax + errors, they abort mlr with a usage message (as if you had mistyped something on the + command line). If the file can't be loaded at all, though, it is silently skipped. + o Any .mlrrc in your home directory or current directory is ignored whenever $MLRRC is + set in the environment. +* Otherwise: + o If $HOME/.mlrrc exists, it's then processed as above. + o If ./.mlrrc exists, it's then also processed as above. + (I.e. current-directory .mlrrc defaults are stacked over home-directory .mlrrc defaults.) + +See also: +https://johnkerl.org/miller/doc/customization.html + Verbs: altkv bar bootstrap cat check clean-whitespace count count-distinct count-similar cut decimate fill-down filter format-values fraction grep