document sv

sh/sv

@@ -5,15 +5,31 @@
 
 sv() { ### @-
     ### collect the lastmost value of every key.
-    ### the field separator can be given as its sole argument.
+    ### the field separator can be given as its sole argument,
+    ### it defaults to a single space otherwise.
     ###
     ### ```
-    ### echo "this=that\nthem=those\nthis=cat" | sv =
-    ### this=cat
-    ### them=those
+    ### $ echo "alpha=first\nbeta=second\nalpha=third" | sv =
+    ### alpha=third
+    ### beta=second
     ### ```
     ###
-    ### **TODO:** add multi-file grep example.
+    ### this next example uses `sv` to only print the lastmost line
+    ### matching a pattern in each file. in other words, it uses
+    ### the filename printed by grep as the key in its key-value pairs.
+    ###
+    ### ```
+    ### $ cd ~/play/hash && grep -r 'ing$' . | sv :
+    ### ./dic_win32.txt:WriteProfileString
+    ### ./cracklib-small.txt:zoning
+    ### ./english-words.txt:zooming
+    ### ./usernames-125k.txt:flats_gaming
+    ### ./cain.txt:zoografting
+    ### ./pokemon.txt:Fletchling
+    ### ./pokemon8.txt:Fletchling
+    ### ```
+    ###
+    ### **TODO:** rename because busybox(1) sv already exists.
     [ $# -le 1 ] || { printf "%s\n" "$0: too many arguments" >&2; return 1; }
     awk "-F${1:- }" '
     NF>1{f[$1]=substr($0,length($1)+1+length(FS))}END{for(k in f)print k FS f[k]}