sort: add a --debug option to highlight key extents

* src/sort (usage): Add description for --debug.
(write_bytes): Pass a line structure so it can subsequently
be passed to compare to highlight the keys when in debug mode.
Also transform TAB and NUL characters written to stdout so
that the highlighting in debug mode aligns correctly.
(human_numcompare): Pass an "endptr" so we can record the extent
of the number matched.
(general_numcompare): Likewise.
(find_unit_order): Likewise.
(getmonth): Likewise.
(numcompare): Likewise.  Note we reuse find_unit_order() for this,
which is a good enough approximation, and means we don't need to
change the strnumcmp() interface.
(check_mixed_SI_IEC): Return whether iec_present, so that can be
used to set the "endptr" in find_unit_order.  Also make the key
parameter optional, which will be the case from numcompare().
(count_tabs): A new function to determine how much to adjust
the mbswidth() values by (TABs don't have a width).
(mark_key): A new function to output the key highlighting to stdout.
(debug_key): A new function to determine the offset and width
of the key highlighting.
(key_compare): Pass the show_debug parameter so the key highlighting
is only displayed when explicitly called.  For each key type, set
the length (lena) and whether leading blanks are auto skipped (skipb)
which are then used by debug_key() to highlight the portion of the
key used in the comparison.
(compare): Pass the show_debug parameter so the key highlighting
is only displayed when explicitly called.  Call debug_key() to
highlight the last resort comparison.
(check): Output highlighting for disorder line to stdout.
(main): Process the --debug option and make it mutually exlusive
with the -o option as I don't see it useful there, even potentially
harmful if someone left a --debug in by mistake when updating a file.
Also restricting debug output to stdout, simplifies the logic
for dealing with temporary files.
* doc/coreutils.texi (sort invocation): Describe the --debug option,
and reference it from the --key description.
* tests/misc/sort-debug-keys: A new test for highlighting keys.
* tests/Makefile.am: Reference the new test.
* NEWS: Mention the new feature.

2 files changed, 318 insertions, 0 deletions

diff --git a/tests/Makefile.am b/tests/Makefile.am
index 1049b2b36..46d388ada 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -224,6 +224,7 @@ TESTS =						\
   misc/sort					\
   misc/sort-compress				\
   misc/sort-continue				\
+  misc/sort-debug-keys				\
   misc/sort-files0-from				\
   misc/sort-float				\
   misc/sort-merge				\
diff --git a/tests/misc/sort-debug-keys b/tests/misc/sort-debug-keys
new file mode 100755
index 000000000..043767844
--- /dev/null
+++ b/tests/misc/sort-debug-keys
@@ -0,0 +1,317 @@
+#!/bin/sh
+# Test annotation of sort keys
+
+# Copyright (C) 2010 Free Software Foundation, Inc.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+if test "$VERBOSE" = yes; then
+  set -x
+  sort --version
+fi
+
+. $srcdir/test-lib.sh
+
+number() { cat -n | sed 's/^ *//'; }
+
+cat <<\EOF > exp
+1
+ ^ no match for key
+
+^ no match for key
+44
+  ^ no match for key
+33
+  ^ no match for key
+2
+ ^ no match for key
+1
+ ^ no match for key
+
+^ no match for key
+44
+  ^ no match for key
+33
+  ^ no match for key
+2
+ ^ no match for key
+
+^ no match for key
+1
+_
+2
+_
+33
+__
+44
+__
+2>
+  ^ no match for key
+3>1
+  _
+1>2
+  _
+1
+ ^ no match for key
+
+^ no match for key
+44
+  ^ no match for key
+33
+  ^ no match for key
+2
+ ^ no match for key
+1
+ ^ no match for key
+
+^ no match for key
+44
+  ^ no match for key
+33
+  ^ no match for key
+2
+ ^ no match for key
+
+^ no match for key
+1
+_
+2
+_
+33
+__
+44
+__
+2>
+  ^ no match for key
+3>1
+  _
+1>2
+  _
+1
+ ^ no match for key
+
+^ no match for key
+44
+  ^ no match for key
+33
+  ^ no match for key
+2
+ ^ no match for key
+1
+ ^ no match for key
+
+^ no match for key
+44
+  ^ no match for key
+33
+  ^ no match for key
+2
+ ^ no match for key
+
+^ no match for key
+1
+_
+2
+_
+33
+__
+44
+__
+2>
+  ^ no match for key
+3>1
+  _
+1>2
+  _
+
+^ no match for key
+JAN
+___
+FEB
+___
+FEB
+   ^ no match for key
+
+^ no match for key
+JAN
+   ^ no match for key
+JAZZ
+^ no match for key
+
+^ no match for key
+JAN
+___
+FEB
+___
+2>JAZZ
+  ^ no match for key
+3>
+  ^ no match for key
+4>JAN
+  ___
+1>FEB
+  ___
+
+^ no match for key
+JANZ
+___
+JAN
+___
+FEB
+___
+3>
+  ^ no match for key
+2>JANZ
+  ___
+4>JAN
+  ___
+1>FEB
+  ___
+ 1.2ignore
+ ___
+ 1.1e4ignore
+ _____
+>>a
+___
+>b
+__
+a
+ ^ no match for key
+
+^ no match for key
+a
+_
+b
+_
+-3
+__
+-2
+__
+-0
+__
+--Mi-1
+_
+-0
+__
+1
+_
+ 1
+ _
+__
+1
+_
+_
+ 1
+ _
+1
+_
+ 1
+__
+1
+_
+2,5
+_
+2.4
+___
+2.,,3
+_
+2.4
+___
+2,,3
+_
+2.4
+___
+1a
+_
+2b
+_
+EOF
+
+(
+for type in n h g; do
+  printf "1\n\n44\n33\n2\n" | sort -s -k2$type --debug
+  printf "1\n\n44\n33\n2\n" | sort -s -k1.3$type --debug
+  printf "1\n\n44\n33\n2\n" | sort -s -k1$type --debug
+  printf "2\n\n1\n" | number | sort -s -k2g --debug
+done
+
+printf "FEB\n\nJAN\n" | sort -s -k1M --debug
+printf "FEB\n\nJAN\n" | sort -s -k2,2M --debug
+printf "FEB\nJAZZ\n\nJAN\n" | sort -s -k1M --debug
+printf "FEB\nJAZZ\n\nJAN\n" | number | sort -s -k2,2M --debug
+printf "FEB\nJANZ\n\nJAN\n" | sort -s -k1M --debug
+printf "FEB\nJANZ\n\nJAN\n" | number | sort -s -k2,2M --debug
+
+printf " 1.2ignore\n 1.1e4ignore\n" | sort -s -g --debug
+
+printf "\tb\n\t\ta\n" | sort -s -d --debug # ignore = 1
+
+printf "a\n\n" | sort -s -k2,2 --debug #lena = 0
+
+printf "b\na\n" | sort -s -k1 --debug #otherwise key compare
+
+printf -- "-0\n1\n-2\n--Mi-1\n-3\n-0\n" | sort -s --debug -k1,1h
+
+printf " 1\n1\n" | sort -b --debug
+printf " 1\n1\n" | sort -sb --debug
+printf " 1\n1\n" | sort --debug
+
+# strnumcmp is a bit weird, so we don't match exactly
+printf "2,5\n2.4\n" | sort -s -k1n --debug
+printf "2.,,3\n2.4\n" | sort -s -k1n --debug
+printf "2,,3\n2.4\n" | sort -s -k1n --debug
+
+# -z means we convert \0 to \n
+printf "1a\x002b\x00" | sort -s -n -z --debug
+) > out
+
+compare out exp || fail=1
+
+cat <<\EOF > exp
+   1²---++3   1,234  Mi
+               _
+   _________
+________________________
+   1²---++3   1,234  Mi
+              _____
+   ________
+_______________________
++1234 1234Gi 1,234M
+^ no match for key
+_____
+^ no match for key
+      ____
+      ____
+      ______
+             _____
+             _____
+             ______
+___________________
+EOF
+
+(
+if test "$LOCALE_FR_UTF8"; then
+  echo "   1²---++3   1,234  Mi" |
+    LC_ALL=C sort --debug -k2g -k1b,1
+  echo "   1²---++3   1,234  Mi" |
+    LC_ALL=$LOCALE_FR_UTF8 sort --debug -k2g -k1b,1
+  echo "+1234 1234Gi 1,234M" |
+    LC_ALL=$LOCALE_FR_UTF8 sort --debug -k1,1n -k1,1g \
+    -k1,1h -k2,2n -k2,2g -k2,2h -k3,3n -k3,3g -k3,3h
+fi
+) > out
+
+compare out exp || fail=1
+
+Exit $fail