Right-align headers over all-numeric columns with --right-align-numeric (#380) (#2167)

With --right-align-numeric, PPRINT data cells right-align but headers
stayed left-aligned, so a header did not line up with its own column's
data -- the original ask in #380. Now a header is right-aligned when
every value in its column is numeric, for both non-barred and barred
PPRINT output. Mixed columns keep left-aligned headers.

For --omd-aligned, the raw header text of right-aligned columns is now
right-justified too, matching how Markdown viewers render the ---:
marker; this follows the same all-values-numeric per-column rule
already used for the separator markers.

Man-page regeneration also picks up previously-merged reorder help-text
edits that had not been regenerated.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

docs/src/file-formats.md

@@ -532,13 +532,14 @@ Since Miller 6.11.0, you can use `--barred-input` with pprint input format:
 </pre>
 
 Use `--right` to right-align all cells, or `--right-align-numeric` to right-align only the cells
-having numeric values, leaving other cells (and the header line) left-aligned:
+having numeric values, leaving other cells left-aligned. Headers are right-aligned over columns
+whose values are all numeric, so that header and data share the same alignment:
 
 <pre class="pre-highlight-in-pair">
 <b>mlr --icsv --opprint --right-align-numeric cat example.csv</b>
 </pre>
 <pre class="pre-non-highlight-in-pair">
-color  shape    flag  k  index quantity rate
+color  shape    flag   k index quantity   rate
 yellow triangle true   1    11  43.6498 9.8870
 red    square   true   2    15  79.2778 0.0130
 red    circle   true   3    16  13.8103 2.9010
@@ -556,7 +557,7 @@ purple square   false 10    91  72.3735 8.2430
 </pre>
 <pre class="pre-non-highlight-in-pair">
 +--------+----------+-------+----+-------+----------+--------+
-| color  | shape    | flag  | k  | index | quantity | rate   |
+| color  | shape    | flag  |  k | index | quantity |   rate |
 +--------+----------+-------+----+-------+----------+--------+
 | yellow | triangle | true  |  1 |    11 |  43.6498 | 9.8870 |
 | red    | square   | true  |  2 |    15 |  79.2778 | 0.0130 |
@@ -624,13 +625,14 @@ The `--right-align-numeric` flag also applies to markdown output: numeric column
 right-alignment marker (`---:`) in the header-separator line, so they render right-aligned in
 Markdown viewers. With `--omd`, since output is streaming, the marker for each column is chosen
 from the first record of each same-schema group; with `--omd-aligned`, a column gets the marker
-when all its values are numeric, and its cell text is right-justified in the raw markdown as well:
+when all its values are numeric, and its header and cell text are right-justified in the raw
+markdown as well:
 
 <pre class="pre-highlight-in-pair">
 <b>mlr --icsv --omd-aligned --right-align-numeric cat example.csv</b>
 </pre>
 <pre class="pre-non-highlight-in-pair">
-| color  | shape    | flag  | k    | index | quantity | rate   |
+| color  | shape    | flag  |    k | index | quantity |   rate |
 | ---    | ---      | ---   | ---: |  ---: |     ---: |   ---: |
 | yellow | triangle | true  |    1 |    11 |  43.6498 | 9.8870 |
 | red    | square   | true  |    2 |    15 |  79.2778 | 0.0130 |

docs/src/file-formats.md.in

@@ -213,7 +213,8 @@ mlr -o pprint --barred cat data/small | mlr -i pprint --barred-input -o json fil
 GENMD-EOF
 
 Use `--right` to right-align all cells, or `--right-align-numeric` to right-align only the cells
-having numeric values, leaving other cells (and the header line) left-aligned:
+having numeric values, leaving other cells left-aligned. Headers are right-aligned over columns
+whose values are all numeric, so that header and data share the same alignment:
 
 GENMD-RUN-COMMAND
 mlr --icsv --opprint --right-align-numeric cat example.csv
@@ -258,7 +259,8 @@ The `--right-align-numeric` flag also applies to markdown output: numeric column
 right-alignment marker (`---:`) in the header-separator line, so they render right-aligned in
 Markdown viewers. With `--omd`, since output is streaming, the marker for each column is chosen
 from the first record of each same-schema group; with `--omd-aligned`, a column gets the marker
-when all its values are numeric, and its cell text is right-justified in the raw markdown as well:
+when all its values are numeric, and its header and cell text are right-justified in the raw
+markdown as well:
 
 GENMD-RUN-COMMAND
 mlr --icsv --omd-aligned --right-align-numeric cat example.csv

docs/src/manpage.md

@@ -802,10 +802,12 @@ This is simply a copy of what you should see on running `man mlr` at a command p
        --fw {string}            Shortcut for --fixed left-align-multi-word
        --right                  Right-justifies all fields for PPRINT output.
        --right-align-numeric    Right-justifies fields with numeric values for PPRINT
-                                output, leaving other fields (and header lines)
-                                left-justified. Also applies to markdown output,
-                                where numeric columns get right-alignment markers
-                                (`---:`) in the header-separator line.
+                                output, leaving other fields left-justified. Headers
+                                are right-justified over columns whose values are all
+                                numeric, so that header and data share the same
+                                alignment. Also applies to markdown output, where
+                                numeric columns get right-alignment markers (`---:`)
+                                in the header-separator line.
 
 1mPROFILING FLAGS0m
        These are flags for profiling Miller performance.
@@ -1848,8 +1850,10 @@ This is simply a copy of what you should see on running `man mlr` at a command p
                   record start.
        -f {a,b,c} Field names to reorder.
        -r {a,b,c} Treat field names as regular expressions. Matched fields are moved to
-                  start or end in record order. Example: -r '^YYY,^XXX' puts all YYY-
-                  and XXX-prefixed fields first (in record order), then the rest.
+                  start or end, grouped by the order the regexes are given; within each
+                  group, fields keep their record order. Example: -r '^YYY,^XXX' puts
+                  all YYY-prefixed fields first, then all XXX-prefixed fields, then the
+                  rest.
        -b {x}     Put field names specified with -f before field name specified by {x},
                   if any. If {x} isn't present in a given record, the specified fields
                   will not be moved.
@@ -1861,7 +1865,7 @@ This is simply a copy of what you should see on running `man mlr` at a command p
        Examples:
        mlr reorder    -f a,b sends input record "d=4,b=2,a=1,c=3" to "a=1,b=2,d=4,c=3".
        mlr reorder -e -f a,b sends input record "d=4,b=2,a=1,c=3" to "d=4,c=3,a=1,b=2".
-       mlr reorder -r '^YYY,^XXX' puts YYY- and XXX-prefixed fields first (record order), then rest.
+       mlr reorder -r '^YYY,^XXX' puts YYY-prefixed fields first, then XXX-prefixed fields, then rest.
 
    1mrepeat0m
        Usage: mlr repeat [options]
@@ -2457,6 +2461,9 @@ This is simply a copy of what you should see on running `man mlr` at a command p
        count-distinct. For uniq, -f is a synonym for -g. Output fields are
        written in the order in which they are named with -g or -f, not in the
        order in which they appear in the input records.
+       To deduplicate records by one or more fields while keeping all other
+       fields, use head: e.g. "mlr head -n 1 -g hash" keeps the first record
+       for each distinct value of the hash field, with all fields intact.
 
        Options:
        -g {d,e,f} Group-by field names for uniq counts.

docs/src/manpage.txt

@@ -781,10 +781,12 @@
        --fw {string}            Shortcut for --fixed left-align-multi-word
        --right                  Right-justifies all fields for PPRINT output.
        --right-align-numeric    Right-justifies fields with numeric values for PPRINT
-                                output, leaving other fields (and header lines)
-                                left-justified. Also applies to markdown output,
-                                where numeric columns get right-alignment markers
-                                (`---:`) in the header-separator line.
+                                output, leaving other fields left-justified. Headers
+                                are right-justified over columns whose values are all
+                                numeric, so that header and data share the same
+                                alignment. Also applies to markdown output, where
+                                numeric columns get right-alignment markers (`---:`)
+                                in the header-separator line.
 
 1mPROFILING FLAGS0m
        These are flags for profiling Miller performance.
@@ -1827,8 +1829,10 @@
                   record start.
        -f {a,b,c} Field names to reorder.
        -r {a,b,c} Treat field names as regular expressions. Matched fields are moved to
-                  start or end in record order. Example: -r '^YYY,^XXX' puts all YYY-
-                  and XXX-prefixed fields first (in record order), then the rest.
+                  start or end, grouped by the order the regexes are given; within each
+                  group, fields keep their record order. Example: -r '^YYY,^XXX' puts
+                  all YYY-prefixed fields first, then all XXX-prefixed fields, then the
+                  rest.
        -b {x}     Put field names specified with -f before field name specified by {x},
                   if any. If {x} isn't present in a given record, the specified fields
                   will not be moved.
@@ -1840,7 +1844,7 @@
        Examples:
        mlr reorder    -f a,b sends input record "d=4,b=2,a=1,c=3" to "a=1,b=2,d=4,c=3".
        mlr reorder -e -f a,b sends input record "d=4,b=2,a=1,c=3" to "d=4,c=3,a=1,b=2".
-       mlr reorder -r '^YYY,^XXX' puts YYY- and XXX-prefixed fields first (record order), then rest.
+       mlr reorder -r '^YYY,^XXX' puts YYY-prefixed fields first, then XXX-prefixed fields, then rest.
 
    1mrepeat0m
        Usage: mlr repeat [options]

docs/src/reference-main-flag-list.md

@@ -415,7 +415,7 @@ These are flags which are applicable to PPRINT format.
 * `--fixed {string}`: Fixed width specification. One of 'widths:<col1-width>,<col2-width>,...', left-align, left-align-multi-word, right-align, right-align-multi-word
 * `--fw {string}`: Shortcut for --fixed left-align-multi-word
 * `--right`: Right-justifies all fields for PPRINT output.
-* `--right-align-numeric`: Right-justifies fields with numeric values for PPRINT output, leaving other fields (and header lines) left-justified. Also applies to markdown output, where numeric columns get right-alignment markers (`---:`) in the header-separator line.
+* `--right-align-numeric`: Right-justifies fields with numeric values for PPRINT output, leaving other fields left-justified. Headers are right-justified over columns whose values are all numeric, so that header and data share the same alignment. Also applies to markdown output, where numeric columns get right-alignment markers (`---:`) in the header-separator line.
 
 ## Profiling flags