Add zkdb function.

4 files changed, 308 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index efd9b640d..7c1a2211a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2001-03-17  Bart Schaefer  <schaefer@zsh.org>
+
+	* unposted (but see 13646 and users/3563): Doc/Zsh/contrib.yo,
+	Functions/Misc/.distfiles, Functions/Misc/zkdb: Function to read
+	keyboard sequences and save them in an associative array for later
+	reference (much improved from posted version, which was broken).
+
 2001-03-15  Peter Stephenson  <pws@csr.com>
 
 	* users/3671: Completion/User/_java: complete in middle of
diff --git a/Doc/Zsh/contrib.yo b/Doc/Zsh/contrib.yo
index 7025292fc..cff9f2d39 100644
--- a/Doc/Zsh/contrib.yo
+++ b/Doc/Zsh/contrib.yo
@@ -75,6 +75,8 @@ installation; if it is not, copy tt(Functions/Misc/run-help) to an
 appropriate directory.
 
 subsect(Recompiling Functions)
+cindex(functions, recompiling)
+cindex(zrecompile utility)
 
 If you frequently edit your zsh functions, or periodically update your zsh
 installation to track the latest developments, you may find that function
@@ -82,7 +84,7 @@ digests compiled with the tt(zcompile) builtin are frequently out of date
 with respect to the function source files.  This is not usually a problem,
 because zsh always looks for the newest file when loading a function, but
 it may cause slower shell startup and function loading.  Also, if a digest
-file is explicitly used as element of tt(fpath), zsh won't check whether
+file is explicitly used as an element of tt(fpath), zsh won't check whether
 any of its source files has changed.
 
 The tt(zrecompile) autoloadable function, found in tt(Functions/Misc), can
@@ -160,7 +162,51 @@ Once the digests have been created and your tt(fpath) modified to refer to
 them, you can keep them up to date by running tt(zrecompile) with no
 arguments.
 
+subsect(Keyboard Definition)
+cindex(keyboard definition)
+
+findex(zkbd)
+The large number of possible combinations of keyboards, workstations,
+terminals, emulators, and window systems makes it impossible for zsh to
+have built-in key bindings for every situation.  The tt(zkbd) utility,
+found in Functions/Misc, can help you quickly create key bindings for your
+configuration.
+
+Run tt(zkbd) either as an autoloaded function, or as a shell script:
+
+example(zsh -f ~/zsh-version()/Functions/Misc/zkbd)
+
+When you run tt(zkbd), it first asks you to enter your terminal type; if
+the default it offers is correct, just press return.  It then asks you to
+press a number of different keys to determine characteristics of your
+keyboard and terminal; tt(zkbd) warns you if it finds anything out of the
+ordinary, such as a Delete key that sends neither tt(^H) nor tt(^?).
+
+The keystrokes read by tt(zkbd) are recorded as a definition for an
+associative array named tt(key), written to a file in the subdirectory
+tt(.zkbd) within either your tt(HOME) or tt(ZDOTDIR) directory.  The name
+of the file is composed from the tt(TERM), tt(VENDOR) and tt(OSTYPE)
+parameters, joined by hyphens.
+
+You may read this file into your tt(.zshrc) or another startup file with
+the "source" or "." commands, then reference the tt(key) parameter in
+bindkey commands, like this:
+
+example(source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
+[[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
+[[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
+# etc.)
+
+Note that in order for `tt(autoload zkbd)' to work, the tt(zkdb) file must
+be in one of the directories named in your tt(fpath) array (see
+ifzman(zmanref(zshparam))\
+ifnzman(noderef(Parameters Used By The Shell))\
+).  This should already be the case if you have a standard zsh
+installation; if it is not, copy tt(Functions/Misc/zkbd) to an
+appropriate directory.
+
 subsect(Dumping Shell State)
+cindex(reporter utility)
 
 Occasionally you may encounter what appears to be a bug in the shell,
 particularly if you are using a beta version of zsh or a development
@@ -748,6 +794,11 @@ Same as tt(zmv -C) and tt(zmv -L), respectively.  These functions do not
 appear in the zsh distribution, but can be created by linking tt(zmv) to
 the names tt(zcp) and tt(zln) in some directory in your tt(fpath).
 )
+item(tt(zkbd))(
+See `Keyboard Definition'
+ifzman(above)\
+ifnzman((noderef(Utilities))).
+)
 findex(zmv)
 item(tt(zmv) [ tt(-finqQsvw) ] [ -C | -L | -M | -p var(program) ] [ -o var(optstring) ] var(srcpat) var(dest) )(
 Move (usually, rename) files matching the pattern var(srcpat) to
diff --git a/Functions/Misc/.distfiles b/Functions/Misc/.distfiles
index eba35794c..5ed84ece7 100644
--- a/Functions/Misc/.distfiles
+++ b/Functions/Misc/.distfiles
@@ -2,5 +2,5 @@ DISTFILES_SRC='
     .distfiles
     acx allopt cat cdmatch cdmatch2 checkmail colors cx harden 
     is-at-least mere multicomp nslookup proto pushd randline
-    run-help yp yu zed zless zls zmv zrecompile zstyle+
+    run-help yp yu zed zkbd zless zls zmv zrecompile zstyle+
 '
diff --git a/Functions/Misc/zkbd b/Functions/Misc/zkbd
new file mode 100644
index 000000000..30cb4a248
--- /dev/null
+++ b/Functions/Misc/zkbd
@@ -0,0 +1,248 @@
+#! /bin/zsh -f
+
+[[ -o interactive ]] && {
+    local -i ARGC
+    (ARGC=0) 2>/dev/null || {
+        print -u2 ${0}: must be run as a function or shell script, not sourced
+        return 1
+    }
+}
+
+emulate -RL zsh
+local zkbd term key seq
+
+zkbd=${ZDOTDIR:-$HOME}/.zkbd
+[[ -d $zkbd ]] || mkdir $zkbd || return 1
+
+print 'typeset -g -A key\n' > $zkbd/$TERM.tmp || return 1
+trap "unfunction getkey getseq; command rm -f $zkbd/$TERM.tmp" 0
+trap "return 1" 1 2 15
+
+getkey () {
+    local k='' i
+    for ((i=10; i>0; --i))
+    do
+	read -t -k 1 k && break
+	sleep 1
+    done
+    [[ -n $k ]] || return 1
+    [[ $k = $'\012' || $k = $'\015' || $k = ' ' ]] && return 0
+    print -Rn $k
+}
+
+getseq () {
+    trap "stty ${$(stty -g 2>/dev/null):-echo -raw}" 0 1 2 15
+    stty raw -echo
+    local k='' seq='' i
+    for ((i=10; i>0; --i))
+    do
+	read -t -k 1 k && break
+	sleep 1
+    done
+    [[ -n $k ]] || return 1
+    [[ $k = $'\012' || $k = $'\015' || $k = ' ' ]] && return 0
+    seq=$k
+    while read -t -k 1 k
+    do
+       seq=$seq$k 
+    done
+    print -Rn ${(V)seq}
+}
+
+read term"?Enter current terminal type: [$TERM] "
+[[ -n $term ]] && TERM=$term
+
+cat <<\EOF
+
+We will now test some features of your keyboard and terminal.
+
+If you do not press the requested keys within 10 seconds, key reading will
+abort.  If your keyboard does not have a requested key, press Space to
+skip to the next key.
+
+EOF
+
+local ctrl alt meta
+
+print -n "Hold down Ctrl and press X: "
+ctrl=$(getkey) || return 1
+print
+
+if [[ $ctrl != $'\030' ]]
+then
+    print "Your keyboard does not have a working Ctrl key?"
+    print "Giving up ..."
+    return 1
+else
+    print
+fi
+
+print "Your Meta key may have a Microsoft Windows logo on the cap."
+print -n "Hold down Meta and press X: "
+meta=$(getkey) || return 1
+print
+
+if [[ $meta == x ]]
+then
+    print "Your keyboard or terminal does not recognize the Meta key."
+    unset meta
+elif [[ $meta > $'\177' ]]
+then
+    print "Your keyboard uses the Meta key to send high-order characters."
+else
+    unset meta
+fi
+print
+
+print -n "Hold down Alt and press X: "
+alt=$(getkey) || return 1
+print
+
+if [[ $alt == x ]]
+then
+    print "Your keyboard or terminal does not recognize the Alt key."
+    unset alt
+elif [[ $alt == $meta ]]
+then
+    print "Your keyboard does not distinguish Alt from Meta."
+elif [[ $alt > $'\177' ]]
+then
+    print "Your keyboard uses the Alt key to send high-order characters."
+else
+    unset alt
+fi
+
+(( $+alt + $+meta == 0 )) && cat <<EOF
+
+---------
+
+Your current terminal and keyboard configuration does not appear to use
+high-order characters.  You may be able to enable the Meta or Alt keys
+with a command such as
+
+    stty pass8
+
+If you want to use these extra keys with zsh, try adding the above command
+to your ${ZDOTDIR:-$HOME}/.zshrc file.
+
+See also "man stty" or the documentation for your terminal or emulator.
+EOF
+
+(( $+alt || $+meta )) && cat <<EOF
+
+---------
+
+You may enable keybindings that use the \
+${meta:+Meta}${meta:+${alt:+ and }}${alt:+Alt} key${meta:+${alt:+s}} \
+by adding
+
+    bindkey -m
+
+to your ${ZDOTDIR:-$HOME}/.zshrc file.
+EOF
+
+cat <<\EOF
+
+---------
+
+You will now be asked to press in turn each of the 12 function keys, then
+the Backspace key, the 6 common keypad keys found on typical PC keyboards,
+plus the 4 arrow keys, and finally the Menu key (near Ctrl on the right).
+If your keyboard does not have the requested key, press Space to skip to
+the next key.
+
+Do not type ahead!  Wait at least one second after pressing each key for
+zsh to read the entire sequence and prompt for the next key.  If a key
+sequence does not echo within 2 seconds after you press it, that key may
+not be sending any sequence at all.  In this case zsh is not able to make
+use of that key.  Press Space to skip to the next key.
+
+EOF
+
+read -k 1 key"?Press any key when ready to begin: "
+[[ $key != $'\n' ]] && print
+
+cat <<\EOF
+
+If you do not press a key within 10 seconds, key reading will abort.
+If you make a mistake, stop typing and wait, then run this program again.
+
+EOF
+
+# There are 509 combinations of the following three arrays that represent
+# possible keystrokes.  (Actually, Sun keyboards don't have Meta or Menu,
+# though some have R{1..12} keys as well, so really there are either 433
+# or 517 combinations; but some X11 apps map Shift-F{1..11} to emulate the
+# unmodified Sun keys, so really only the 345 PC combinations are usable.
+# Let's not even get into distinguishing Left and Right Shift/Alt/Meta.)
+# No one would ever want to type them all into this program (would they?),
+# so by default ask for the 23 unmodified PC keys.  If you uncomment more,
+# you should fix the introductory text above.
+
+local -a pckeys sunkeys modifiers
+pckeys=(F{1..12}
+        Backspace  Insert  Home   PageUp 
+                   Delete  End   PageDown
+                            Up
+                    Left   Down   Right
+        Menu
+       )
+sunkeys=(Stop  Again
+         Props Undo
+         Front Copy
+         Open  Paste
+         Find  Cut
+            Help
+        )
+modifiers=(Shift- # Control- Alt- Meta-
+           # Control-Shift- Alt-Shift- Meta-Shift-
+           # Control-Alt- Control-Meta- Alt-Meta-
+           # Control-Alt-Shift- Control-Meta-Shift-
+           # Alt-Meta-Shift- Control-Alt-Meta-Shift-
+          )
+
+exec 3>/dev/tty
+
+for key in $pckeys # $^modifiers$^pckeys $sunkeys $^modifiers$^sunkeys
+do
+    print -u3 -Rn "Press $key: "
+    seq="$(getseq)" || return 1
+    print "key[$key]='${(q)seq}'"
+    print -u3 -R $seq
+done >> $zkbd/$TERM.tmp
+
+source $zkbd/$TERM.tmp || return 1
+if [[ "${key[Delete]}" == "${key[Backspace]}" ]]
+then
+    print
+    print Warning: Backspace and Delete key both send "${(q)key[Delete]}"
+else
+    if [[ "${key[Delete]}" != "^?" ]]
+    then
+	print
+        print Warning: Delete key sends "${(q)key[Delete]}" '(not ^?)'
+    fi
+    if [[ "${key[Backspace]}" != "^H" ]]
+    then
+	print
+        print Warning: Backspace sends "${(q)key[Backspace]}"
+    fi
+fi
+
+command mv $zkbd/$TERM.tmp $zkbd/$TERM-$VENDOR-$OSTYPE
+
+cat <<EOF
+
+Parameter assignments for the keys you typed have been written to the file:
+$zkbd/$TERM-$VENDOR-$OSTYPE
+
+You may read this file into ${ZDOTDIR:-$HOME}/.zshrc or another startup
+file with the "source" or "." commands, then reference the \$key parameter
+in bindkey commands, like this:
+
+    source ${zkbd/$HOME/~}/\$TERM-\$VENDOR-\$OSTYPE
+    [[ -n \${key[Left]} ]] && bindkey "\${key[Left]}" backward-char
+    [[ -n \${key[Right]} ]] && bindkey "\${key[Right]}" forward-char
+    # etc.
+
+EOF