zsh-hints: Initial public commit

README.md

@@ -0,0 +1,85 @@
+# zsh-hints #
+
+
+``zsh-hints`` is a small helper utility that displays hints right below your editing buffer.  Intended use is to make incompletable trivia like zsh flags available without interfering with your work flow. 
+
+The hints, or definitions, are read from a file, where the characters before the first space are considered as a key, and the rest as the explanation.  This means that it is extremely easy to create and use your own hint files.  
+
+The output is adjusted to the size of the terminal, and some of its looks are configurable. 
+
+## The basic setup ##
+To make use of this script, you need to do the following things: 
+
+1.  autoload ``zsh-hints``
+2.  Make a ``hints``-file available
+3.  Set up some key bindings in ``~/.zshrc``
+4.  Optionally, configure some decorations
+
+First, the file ``zsh-hints`` needs to be ``autoload``ed.  If you don't have a directory for autoloadable zsh-functions yet, you need to set one up.  Putting this in ``~/.zshrc`` will autoload all files in ``~/.zfun``: 
+
+    fpath=(~/.zfun $fpath)
+    autoload ~/.zfun/*(:t)
+
+For the hint files, without any configuration, zsh-hints will look in
+``$XDG_DATA_HOME/zsh``, or in ``~/.local/share/zsh``.  Just drop 'em there, and you will be fine.  
+
+Then, we need to tell ``zsh`` every time an interactive session is started.  For every hint file you want to dedicate a keyboard shortctut to, there you need to make some arrangements.  To make the ``param.hints`` file available when pressing ``CTRL-x p``, you first need to tell that ``zsh-hints-param`` really is just another name of ``zsh-hints`` with ``zle -N zsh-hints-param zsh-hints``.  Once that is set, you can call this function with ``CTRL-x p`` through a key binding with ``bindkey "^Xp" zsh-hints-param``.  
+
+These lines are used by the author to enable the included hint-files: 
+
+    zle -N zsh-hints-param zsh-hints
+    bindkey "^Xp" zsh-hints-param
+    zle -N zsh-hints-paramflags zsh-hints
+    bindkey "^Xf" zsh-hints-paramflags
+    zle -N zsh-hints-glob zsh-hints
+    bindkey "^Xg" zsh-hints-glob
+
+The effect of this is, that ``zsh-hints`` will be called under the name ``zsh-hints-param``.  Without any further configuration, ``zsh-hints`` will try to use a file ``param.hints`` in the directory ``$XDG_DATA_HOME/zsh``. 
+
+
+### Configuring looks ###
+
+The first thing you might want to adjust, is how the function behaves if the contents of the file does not fit within the terminal window.  The style ``margin`` determines the minimum amount of the normal terminal that will remain visible. If not set, it the default is 6 lines. 
+
+    zstyle ':zsh-hints:*:' margin 8
+    zstyle ':zsh-hints:param:' verbose no
+
+When lines need to be omitted due to space constraints, the verbose option takes one line to tell how many lines needed to be omitted from the result.  This is enabled by default, and can be disabled like this: 
+
+    zstyle ':zsh-hints:*:' verbose no
+
+The separators separating the keys from their explanation are configurable. Without configuration, the primary separator, that is, when there is no newline since the key, is a ``#``.  By default, the secondary separator takes on the value of the primary separator.  I have mine currently set as follows: 
+
+    zstyle ':zsh-hints:*:' pri_sep ▶
+    zstyle ':zsh-hints:param:' sec_sep " "
+
+
+### Overriding the default file location ###
+``zsh-hints`` will look in a configurable directory for a file named after the function with a configurable extension.  These settings can be made for all hint files, or for a specific one.  Alternatively, you can specify a file to use directly. 
+
+If not explicitly set, the directory ``${XDG_DATA_HOME}/zsh`` will be used, and if ``$XDG_DATA_HOME`` is not set, its default location ``~/.local/share/zsh`` is assumed.  This can be overridden as follows: 
+
+    zstyle ':zsh-hints:*:' dir "/path/to/dir"
+    zstyle ':zsh-hints:param:' dir "/path/to/dir2"
+
+In this directory, a file is attempted to be found with the name of the hint, with the extension ``.hints``.  The extension can be disabled or changed by the following directives: 
+
+    zstyle ':zsh-hints:*:' ext "txt"
+    zstyle ':zsh-hints:glob:' ext ""
+
+To set a file path directly, use: 
+
+    zstyle ':zsh-hints:param:' file "/path/to/file"
+
+### Making your own hints-file ###
+Making the hints file is straight forward: The only mark-up is the first word of the line.  When you want to make this available, store the file with the directions of the previous paragraph, and make a new key binding: 
+
+    zle -N zsh-hints-FILE zsh-hints
+    bindkey "keybind" zsh-hints-FILE
+
+## Bugs, patches, comments ##
+
+Yes, there are.  I'd be happy to receive problem reports and patches.  Including new and adjustments to hints-files.  Let me know what is or would be helpful for _you_!  You can send pull requests through it's public repository, or contact the author by mail. 
+
+Written by Joep van Delft, licensed under the ZSH-license. 
+

glob.hints

@@ -0,0 +1,32 @@
+/             directories
+F             non-empty directories (`full`)
+.             plain files
++             executable plain files
+l[-+]n        link count 
+r,w,x         owner (r)eadable (w)ritable, e(x)ecutable files
+A,I,E         group re(A)dable wr(I)table, (E)xecutable files
+R,W,X         world (R)readable, (W)ritable, e(X)ecutable files
+s,G,t         setuid, setgid, sticky bit files
+f[+=-]NNN     files with access rights matching +,-,= octal number
+{U,G}NNN      owned by effective (U)ser,(G)roup ID
+{u,g}NNN      owned by user, group id `NNN`
+{u,g}:name:   owned by user, group name `name`
+a,m,c         Access, Mod, and inode change time: File system attributes
+Mwhms][-+]n   Month, week, hours, minutes, seconds; less or more than n. 
+L[+|-]n[km]   files -,+ n bytes (kbytes, mbytes)
+n             numeric sort for current pattern
+(oO)[nLlamdN] order{, reversely} by name, size, link count, time(access,mod), subdirs first
+(oO)N         no order
+i,I           Case insensitive, sensitive
+l             Lowercase in pattern is case insensitive
+b,B           Activate, deactivate Backreferences. 
+m,M           Faster backreferences that do not work for filenames
+^             negates subsequent qualifiers
+1.            toggle follow symbolic links (default: on)
+[beg[,end]]   range
+N             NULL_GLOB for current pattern
+D             GLOB_DOTS for current pattern
+M             sets the MARK_DIRS option for the current pattern
+T             appends trailing qualifier mark to filenames
+Pstring       prepend: *(P:-f:) --> -f file1 -f file2
+estring       execute string as shell code

param.hints

@@ -0,0 +1,26 @@
+${+n}   1 if n is set, 0 otherwise
+${n-w}  if n is set, $n, else w
+${n:-w} if n is set an nonzero, $n, else w
+${n+w}  if n is set, substitute w, else empty   
+${n:+w} if n is set and non-zero, substitute w, else empty
+${n=w}  if n is unset, set it to w
+${n:=w} if n is unset or null, set it to w
+${n::=w} Equivalent to n=w
+${n?w}  if n is set, substitute value, else exit/return with w
+${n:?w} if n is set, n != ""; substitute value, else exit/return with w
+${n#p}  remove pattern p from start
+${n##p} greedily remove pattern p from start
+${n%p}  remove pattern p from end
+${n%%p} greedily remove pattern p from end
+${n:#p} if p matches $p, then empty. reverse result with (M)
+${n/p/r} replace leftmost longest possible match of pattern p value of n with r.
+${n//p/r} globally replace match of p in n with r
+${#spec} return length of result
+${^spec} RC_EXPAND_PARAM on: Operate on all array items
+${^^spec} disable RC_EXPAND_PARAM
+${=spec} SH_WORD_SPLIT
+${==spec} no SH_WORD_SPLIT
+${~spec} enable GLOB_SUBST
+${~~spec} disable GLOB_SUBST
+
+

paramflags.hints

@@ -0,0 +1,36 @@
+@          array elements
+c          count elements of array/string
+k,v        returns keys, values of associative array
+u          unique, deduplicate entries
+A(A)       create (associative) array, useful with ${(A)...=...}
+s:string:  field splitting at string
+f          split at newlines (ps:\\n:)
+z (Z:opt:) split result into shell words
+0          split with 0-bytes: ps:\\0:
+j:string:  join words of array with string as separator
+F          join words of array with newlines (pj:\\n:)
+w          count words, use s to define word delimiter
+W          count words, double delimiters count doubly
+i          sort case insensitive. Combine with n, O
+n          sort numerically
+o          sort in ascending order
+O          reverse sort order
+a          sort in array index order (with O reversed)
+U          convert to uppercase
+L          convert to lowercase
+V          make special characters visible
+q          quote, double quote, single quote, 
+Q          remove level of quoting
+C          capitalize first letters of words in result
+l:e:       pad (e)expression to the left. 
+r:e:       right pad (e)xpression
+D          substitute shortened names for directories (~)
+%          expand %-escapes as in prompts
+p          recognize same escape sequences as print
+g:opts:    process escape sequences
+e          eval: parameter expansion, command substitution and arithmetic expansion on result
+P          interpret value of parameter as a parameter
+t          diplay variable type
+X          report errors with pattern matching forms
+#          interpret as numeric expression
+m          multibyte magic

zsh-hints

@@ -0,0 +1,93 @@
+# zsh-hints
+# Easily display non-completable information below the buffer. 
+# Written by Joep van Delft, 2014. 
+
+emulate -L zsh
+setopt extended_glob
+
+name=${WIDGET#zsh-hints-}
+
+# Locate the library file by explicit setting or guesswork: 
+zstyle -s ":zsh-hints:$name:" file hintfile || {
+    zstyle -s ":zsh-hints:$name:" dir hintdir || \
+        hintdir="${XDG_DATA_HOME:-~/.local/share}/zsh"
+    zstyle -s ":zsh-hints:$name:" ext hintext || \
+        hintext="hints"
+    hintfile="$hintdir/${name}${hintext:+.$hintext}"
+}
+if [[ ! -r "$~hintfile" ]]; then
+    print "Library file $~hintfile not found for $WIDGET." >&2
+    return 1
+fi
+
+# Get the configuration for the styles: 
+zstyle -b ":zsh-hints:$name:" verbose verbose || verbose=yes
+zstyle -s ":zsh-hints:$name:" pri_sep pri_sep || pri_sep='#'
+zstyle -s ":zsh-hints:$name:" sec_sep sec_sep || sec_sep="$pri_sep"
+zstyle -s ":zsh-hints:$name:" margin  margin  || margin=6
+
+# Establish the available lines for display: 
+if [[ $verbose == "yes" ]]; then
+    dl=$((${LINES}-${margin}-1))
+else
+    dl=$((${LINES}-$margin))
+fi
+
+# Store the contents of the help file in an array. The reason that
+# this is separated from the output generation, is because the 
+# output depends on the longest 'key', or first word of a line. 
+# As ZSH does not support multidimensional arrays, an emulation
+# of multidimensional arrays is attempted by the names of the
+# keys of the associative array txt, with the keys of the form 
+# 02_03. Pattern matching on the keys makes it work like an 
+# associative array. 
+declare -A txt      # The main data structure. 
+declare -Z 2 i j    # Counters with leading zeros. 
+len_k=0
+i=0
+
+for line in "${(f)$(<${~hintfile})}"; do
+    i=$(($i+1))
+    for j in {1..${#${(s: :)line}}}; do
+        txt[${i}_${j}]=${${(s: :)line}[$j]}
+    done
+    # Get a reasonable estimate len_k of the maximum length 
+    # of the relevant keys:
+    #print $i, $dl
+    (( $i<=$dl )) && (( $#txt[${i}_01]>$len_k )) && len_k=$#txt[${i}_01]
+done
+
+output_txt() {
+    for hint_no in ${(ou)${(k)txt[@]}%_*}; do
+        # Looping over the (unique and ordered) numerical part before 
+        # the underscore of the keys of txt-array. A.K.A. the hint_no
+        # identifying a line. 
+        v=$(($v+1))
+        if (( $v > $dl )); then
+            [[ "$verbose" == "yes" ]] && print "   ...$(( $i-$hint_no )) hints omitted."
+            break
+        fi
+        # Get the ordered indexes of words belonging matching the current line: 
+        for word in ${(oM)${(k)txt[@]}:#$hint_no*}; do
+            if [[ -z ${word:#*01} ]]; then
+                # It is the first word: Special treatment. 
+                printf "%-${len_k}s %s" "$txt[$word]" "$pri_sep"
+                d=$(($len_k+2))
+            elif (( $d+1+$#txt[$word] <= $COLUMNS )); then
+                # It is not a key, and it fits on the current line.
+                printf " %s" "$txt[$word]"
+                d=$(($d+1+$#txt[$word]))
+            else
+                # It is not a key and does not fit on current line.
+                printf "\n%-${len_k}s %s %s" " " "$sec_sep" "$txt[$word]"
+                d=$(($len_k+$#txt[$word]))
+                v=$(($v+1))
+            fi
+        done
+        printf "\n"
+    done
+}
+
+zle -M "$(output_txt)"
+
+# vim: ft=zsh