wc: add --total={auto,never,always,only} option

without this option, control of when the total is output
is quite awkward. Consider trying to suppress the total line,
which could be achieved with something like:

   wc-no-total() { wc "$@" /dev/null | head -n-2; }

As well as being non obvious, it's also non general.
It would give a non failure, but zero count if passed a file on stdin.
Also it doesn't work in conjunction with the --files0-from option,
which would need to be handled differently with something like:

   { find files -print0; printf '%s\0' /dev/null; } |
   wc --files0-from=- |
   head -n2

Also getting just the total can be awkward as file names
are only suppressed when processing stdin, and
also a total line is only printed if processing more than one file.
For completness this might be achieved currently with:

  wc-only-total() {
    wc "$@" |
    tail -n1 |
    sed 's/^ *//; s/ [^ 0-9]*$//'
  }

* src/wc.c: Add new --total option.
* tests/misc/wc-total.sh: New test suite for the new option.
* tests/local.mk: Reference the new test.
* doc/coreutils.texi (wc invocation): Document the new option.
* THANKS.in: Add suggestor.
* NEWS: Mention the new feature.

1 files changed, 29 insertions, 4 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f4be26b44..699948a8b 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -3769,10 +3769,12 @@ wc [@var{option}]@dots{} [@var{file}]@dots{}
 
 @cindex total counts
 @command{wc} prints one line of counts for each file, and if the file was
-given as an argument, it prints the file name following the counts.  If
-more than one @var{file} is given, @command{wc} prints a final line
-containing the cumulative counts, with the file name @file{total}.  The
-counts are printed in this order: newlines, words, characters, bytes,
+given as an argument, it prints the file name following the counts. By default
+if more than one @var{file} is given, @command{wc} prints a final line
+containing the cumulative counts, with the file name @file{total}.
+This @samp{total} line can be controlled with the @option{--total} option,
+which is a GNU extension.
+The counts are printed in this order: newlines, words, characters, bytes,
 maximum line length.
 Each count is printed right-justified in a field with at least one
 space between fields so that the numbers and file names normally line
@@ -3839,6 +3841,29 @@ Tabs are set at every 8th column.
 Display widths of wide characters are considered.
 Non-printable characters are given 0 width.
 
+@item --total=@var{when}
+@opindex --total=@var{when}
+Control when and how the final line with cumulative counts is printed.
+@var{when} is one of:
+@itemize @bullet
+@item auto
+@vindex auto @r{total option}
+- This is the default mode of @command{wc} when no @option{--total}
+option is specified.  Output a total line if more than one @var{file}
+is specified.
+@item always
+@vindex always @r{total option}
+- Always output a total line, irrespective of the number of files processed.
+@item only
+@vindex only @r{total option}
+- Only output total counts.  I.e., don't print individual file counts,
+suppress any leading spaces, and don't print the @samp{total} word itself,
+to simplify subsequent processing.
+@item never
+@vindex none @r{total option}
+- Never output a total line.
+@end itemize
+
 @macro filesZeroFromOption{cmd,withTotalOption,subListOutput}
 @item --files0-from=@var{file}
 @opindex --files0-from=@var{file}