Add help strings for -a/-r in sub/gsub/ssub (#1721)

* Help strings for `-a`/`-r` in `sub`/`gsub`/`ssub` * `mlr regtest -p test/cases/cli-help` to update expected outputs * artifacts from `make dev`
johnkerl · Nov 23, 2024 · 9f77bbe · 9f77bbe
1 parent 5c65edb
commit 9f77bbe
Show file tree

Hide file tree

Showing 8 changed files with 51 additions and 10 deletions.
diff --git a/docs/src/manpage.md b/docs/src/manpage.md
@@ -1275,6 +1275,8 @@ This is simply a copy of what you should see on running `man mlr` at a command p
        See also the `sub` and `ssub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1mhaving-fields0m
@@ -1910,6 +1912,8 @@ This is simply a copy of what you should see on running `man mlr` at a command p
        the old string, like the `ssub` DSL function. See also the `gsub` and `sub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1mstats10m
@@ -2057,6 +2061,8 @@ This is simply a copy of what you should see on running `man mlr` at a command p
        See also the `gsub` and `ssub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1msummary0m
@@ -3731,5 +3737,5 @@ This is simply a copy of what you should see on running `man mlr` at a command p
        MIME Type for Comma-Separated Values (CSV) Files, the Miller docsite
        https://miller.readthedocs.io
 
-                                  2024-10-17                         4mMILLER24m(1)
+                                  2024-11-23                         4mMILLER24m(1)
 </pre>
diff --git a/docs/src/manpage.txt b/docs/src/manpage.txt
@@ -1254,6 +1254,8 @@
        See also the `sub` and `ssub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1mhaving-fields0m
@@ -1889,6 +1891,8 @@
        the old string, like the `ssub` DSL function. See also the `gsub` and `sub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1mstats10m
@@ -2036,6 +2040,8 @@
        See also the `gsub` and `ssub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1msummary0m
@@ -3710,4 +3716,4 @@
        MIME Type for Comma-Separated Values (CSV) Files, the Miller docsite
        https://miller.readthedocs.io
 
-                                  2024-10-17                         4mMILLER24m(1)
+                                  2024-11-23                         4mMILLER24m(1)
diff --git a/docs/src/record-heterogeneity.md b/docs/src/record-heterogeneity.md
@@ -130,7 +130,6 @@ If you `mlr --csv cat` this, you'll get an error message:
 a,b,c
 1,2,3
 mlr: mlr: CSV header/data length mismatch 3 != 2 at filename data/het/ragged.csv row 3.
-.
 </pre>
 
 There are two kinds of raggedness here. Since CSVs form records by zipping the

diff --git a/docs/src/reference-verbs.md b/docs/src/reference-verbs.md
@@ -986,7 +986,7 @@ Options:
 Since the expression pieces are simply concatenated, please be sure to use intervening
 semicolons to separate expressions.)
 
--s name=value: Predefines out-of-stream variable @name to have 
+-s name=value: Predefines out-of-stream variable @name to have
     Thus mlr put -s foo=97 '$column += @foo' is like
     mlr put 'begin {@foo = 97} $column += @foo'.
     The value part is subject to type-inferencing.
@@ -1464,6 +1464,8 @@ for the old string and handling multiple matches, like the `gsub` DSL function.
 See also the `sub` and `ssub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 </pre>
 
@@ -2321,7 +2323,7 @@ Options:
 Since the expression pieces are simply concatenated, please be sure to use intervening
 semicolons to separate expressions.)
 
--s name=value: Predefines out-of-stream variable @name to have 
+-s name=value: Predefines out-of-stream variable @name to have
     Thus mlr put -s foo=97 '$column += @foo' is like
     mlr put 'begin {@foo = 97} $column += @foo'.
     The value part is subject to type-inferencing.
@@ -3210,6 +3212,8 @@ Replaces old string with new string in specified field(s), without regex support
 the old string, like the `ssub` DSL function. See also the `gsub` and `sub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 </pre>
 
@@ -3714,6 +3718,8 @@ for the old string and not handling multiple matches, like the `sub` DSL functio
 See also the `gsub` and `ssub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 </pre>
 

diff --git a/man/manpage.txt b/man/manpage.txt
@@ -1254,6 +1254,8 @@
        See also the `sub` and `ssub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1mhaving-fields0m
@@ -1889,6 +1891,8 @@
        the old string, like the `ssub` DSL function. See also the `gsub` and `sub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1mstats10m
@@ -2036,6 +2040,8 @@
        See also the `gsub` and `ssub` verbs.
        Options:
        -f {a,b,c}  Field names to convert.
+       -r {regex}  Regular expression for field names to convert.
+       -a          Convert all field names.
        -h|--help   Show this message.
 
    1msummary0m
@@ -3710,4 +3716,4 @@
        MIME Type for Comma-Separated Values (CSV) Files, the Miller docsite
        https://miller.readthedocs.io
 
-                                  2024-10-17                         4mMILLER24m(1)
+                                  2024-11-23                         4mMILLER24m(1)
diff --git a/man/mlr.1 b/man/mlr.1
@@ -2,12 +2,12 @@
 .\"     Title: mlr
 .\"    Author: [see the "AUTHOR" section]
 .\" Generator: ./mkman.rb
-.\"      Date: 2024-10-17
+.\"      Date: 2024-11-23
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "MILLER" "1" "2024-10-17" "\ \&" "\ \&"
+.TH "MILLER" "1" "2024-11-23" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Portability definitions
 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1335,7 +1335,7 @@ Options:
 Since the expression pieces are simply concatenated, please be sure to use intervening
 semicolons to separate expressions.)
 
--s name=value: Predefines out-of-stream variable @name to have 
+-s name=value: Predefines out-of-stream variable @name to have
     Thus mlr put -s foo=97 '$column += @foo' is like
     mlr put 'begin {@foo = 97} $column += @foo'.
     The value part is subject to type-inferencing.
@@ -1565,6 +1565,8 @@ for the old string and handling multiple matches, like the `gsub` DSL function.
 See also the `sub` and `ssub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 .fi
 .if n \{\
@@ -1924,7 +1926,7 @@ Options:
 Since the expression pieces are simply concatenated, please be sure to use intervening
 semicolons to separate expressions.)
 
--s name=value: Predefines out-of-stream variable @name to have 
+-s name=value: Predefines out-of-stream variable @name to have
     Thus mlr put -s foo=97 '$column += @foo' is like
     mlr put 'begin {@foo = 97} $column += @foo'.
     The value part is subject to type-inferencing.
@@ -2386,6 +2388,8 @@ Replaces old string with new string in specified field(s), without regex support
 the old string, like the `ssub` DSL function. See also the `gsub` and `sub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 .fi
 .if n \{\
@@ -2557,6 +2561,8 @@ for the old string and not handling multiple matches, like the `sub` DSL functio
 See also the `gsub` and `ssub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 .fi
 .if n \{\

diff --git a/pkg/transformers/subs.go b/pkg/transformers/subs.go
@@ -49,6 +49,8 @@ func transformerSubUsage(
 	fmt.Fprintf(o, "See also the `gsub` and `ssub` verbs.\n")
 	fmt.Fprintf(o, "Options:\n")
 	fmt.Fprintf(o, "-f {a,b,c}  Field names to convert.\n")
+	fmt.Fprintf(o, "-r {regex}  Regular expression for field names to convert.\n")
+	fmt.Fprintf(o, "-a          Convert all field names.\n")
 	fmt.Fprintf(o, "-h|--help   Show this message.\n")
 }
 
@@ -61,6 +63,8 @@ func transformerGsubUsage(
 	fmt.Fprintf(o, "See also the `sub` and `ssub` verbs.\n")
 	fmt.Fprintf(o, "Options:\n")
 	fmt.Fprintf(o, "-f {a,b,c}  Field names to convert.\n")
+	fmt.Fprintf(o, "-r {regex}  Regular expression for field names to convert.\n")
+	fmt.Fprintf(o, "-a          Convert all field names.\n")
 	fmt.Fprintf(o, "-h|--help   Show this message.\n")
 }
 
@@ -72,6 +76,8 @@ func transformerSsubUsage(
 	fmt.Fprintf(o, "the old string, like the `ssub` DSL function. See also the `gsub` and `sub` verbs.\n")
 	fmt.Fprintf(o, "Options:\n")
 	fmt.Fprintf(o, "-f {a,b,c}  Field names to convert.\n")
+	fmt.Fprintf(o, "-r {regex}  Regular expression for field names to convert.\n")
+	fmt.Fprintf(o, "-a          Convert all field names.\n")
 	fmt.Fprintf(o, "-h|--help   Show this message.\n")
 }
 

diff --git a/test/cases/cli-help/0001/expout b/test/cases/cli-help/0001/expout
@@ -392,6 +392,8 @@ for the old string and handling multiple matches, like the `gsub` DSL function.
 See also the `sub` and `ssub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 
 ================================================================
@@ -1058,6 +1060,8 @@ Replaces old string with new string in specified field(s), without regex support
 the old string, like the `ssub` DSL function. See also the `gsub` and `sub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 
 ================================================================
@@ -1209,6 +1213,8 @@ for the old string and not handling multiple matches, like the `sub` DSL functio
 See also the `gsub` and `ssub` verbs.
 Options:
 -f {a,b,c}  Field names to convert.
+-r {regex}  Regular expression for field names to convert.
+-a          Convert all field names.
 -h|--help   Show this message.
 
 ================================================================