[menu] Update manual. Add file completion example.

Makefile

@@ -4,6 +4,7 @@ include $(ROOT)/mk/wmii.mk
 
 DIRS = \
 	doc	     \
+	examples     \
 	man	     \
 	lib	     \
 	cmd	     \

cmd/wmii.sh.sh

@@ -85,21 +85,26 @@ _wi_script() {
 }
 
 _wi_text() {
-	cat <<'!'
-Event Key
-	Key "$@"
-!
 	eval "cat <<!
 $( (test ! -t 0 && cat; for a; do eval "$a"; done) | sed '/^[ 	]/s/\([$`\\]\)/\\\1/g')
 !
 "
 }
 
+_wi_events=""
 wi_events() {
-	#cho "$(_wi_text "$@" | awk "$(_wi_script)")" | cat -n
+	eval=""; [ "$1" = -e ] && eval=1 && shift
-	eval "$(_wi_text "$@" | awk "$(_wi_script)")"
+	_wi_events="$(_wi_text "$@")
+$_wi_events"
+	# -n "$eval" ] && echo "$_wi_events" | awk "$(_wi_script)" >&2
+	[ -n "$eval" ] && eval "$(echo "$_wi_events" | awk "$(_wi_script)")"
 }
 
+wi_events <<'!'
+Event Key
+	Key "$@"
+!
+
 wi_fatal() {
 	echo $scriptname: Fatal: $*
 	exit 1

examples/Makefile

@@ -0,0 +1,7 @@
+ROOT=..
+include $(ROOT)/mk/hdr.mk
+include $(ROOT)/mk/wmii.mk
+
+DOCS   = wimenu-file-completion.sh
+DOCDIR = $(DOC)/examples
+

examples/wimenu-file-completion.sh

@@ -0,0 +1,98 @@
+#!/bin/sh
+# This script will launch wimenu and provide command
+# completion for the first argument and filename completion
+# for each following argument, and execute the result.
+# Program name completion requires that a program list already
+# exist in $(wmiir namespace)/.proglist
+
+fifo="$HOME/.wmii/menu_fifo"
+mkfifo $fifo 2>/dev/null
+
+script=$(cat <<'!'
+    BEGIN {
+        progs = "cat $(wmiir namespace)/.proglist"
+
+        # Print the first set of completions to wimenu’s fifo
+        print read(progs) >fifo
+        fflush(fifo)
+    }
+
+    # Process the input and provide the completions
+    {
+        # Skip the trailing part of the command.
+        # If there is none, this is the result.
+        if (!getline rest) {
+            print
+            exit
+        }
+
+        if (!match($0, /.*[ \t]/))
+            # First argument, provide the program list
+            update(0, progs)
+        else {
+            # Set the offset to the location of the last
+            # space, and save that part of the completion
+            offset = RLENGTH
+            str = substr($0, offset + 1)
+
+            # If we're completing a sub-directory, adjust
+            # the offset to the position of the last /
+            if (match(str, ".*/"))
+                offset += RLENGTH
+
+            # If the last component of the path begins with
+            # a ., include hidden files
+            arg = ""
+            if(match(str, "(^|/)\\.[^/]*$"))
+                    arg = "-A"
+
+            # Substitute ~/ for $HOME/
+            sub("^~/", ENVIRON["HOME"] "/", str)
+
+            # Strip the trailing filename
+            sub("[^/]+$", "", str)
+
+            update(offset, "ls " arg quote(str))
+        }
+    }
+
+    # Push out a new set of completions
+    function update(offset, cmd) {
+        # Only push out the completion if the offset or the
+        # option of ls has changed. The behavior will be the
+        # same regardless, but this is a minor optimization
+        if (offset != loffset || cmd != lcmd) {
+            loffset = offset
+            lcmd = cmd
+
+            cmpl = read(cmd)
+            print offset >fifo
+            print cmpl >fifo
+            fflush(fifo)
+        }
+    }
+
+    # Quote a string. This should work in any Bourne
+    # or POSIX compatible shell.
+    function quote(str) {
+        if (!match(str, /[\[\](){}$'"^#~!&;*?|<>]/))
+            return str
+        gsub(/\\/, "'\\\\'", str)
+        gsub(/'/, "'\\''", str)
+        return "'" str "'"
+    }
+
+    # Read the output of a command and return it
+    function read(cmd) {
+        if (cmd in cache)
+            return cache[cmd]
+        res = ""
+        while (cmd | getline)
+            res = res quote($0) "\n"
+        close(cmd)
+        return cache[cmd] = res
+    }
+!
+)
+res="$(wimenu -c "$@" <$fifo | awk -v "fifo=$fifo" "$script")"
+exec ${SHELL:-sh} -c "exec $res"

man/wimenu.1

@@ -42,6 +42,11 @@ sliding window before this limit is imposed.
 \-p \fI<prompt>\fR
 The string \fI<prompt>\fR will be show before the input field
 when the menu is opened.
+.TP
+\-r \fI<rows>\fR
+Display completion items as a vertical list, one per
+row, rather than a horizontal list, side\-by\-side. A
+maximum of \fI<rows>\fR rows will be displayed.
 
 
 .SH ADVANCED ARGUMENTS
@@ -151,9 +156,7 @@ the following script provides the appropriate completions:
   		print cmds >fifo; fflush(fifo)
   	}
   
-  	# Store the last line we get and print it when done
+          { print; fflush() }
-  	{ last = $0 }
-  	END { print last }
   
   	# Push out a new set of completions
   	function update(str, opts) {
@@ -173,14 +176,14 @@ the following script provides the appropriate completions:
   		# Skip the trailing part of the command
   		getline rest
   	}
-  \&'
+  \&' | tail -1
 .fi
 
 
 .P
 In theory, this facility can be used for myriad purposes,
 including hijacking the programmable completion facilities of
-most shells.
+most shells. See also the provided examples\fI[1]\fR.
 
 .SH ENVIRONMENT
 .TP
@@ -197,6 +200,8 @@ wmii(1), wmiir(1), wistrug(1), wmii9menu(1), dmenu(1)
 
 .P
 \fI[1]\fR http://www.suckless.org/wiki/wmii/tips/9p_tips 
+.P
+\fI[2]\fR @EXAMPLES@
 
 
 .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net)

man/wimenu.man1

@@ -41,6 +41,10 @@ following. More advanced options are documented below.
 : -p <prompt>
         The string <prompt> will be show before the input field
         when the menu is opened.
+: -r <rows>
+        Display completion items as a vertical list, one per
+        row, rather than a horizontal list, side-by-side. A
+        maximum of <rows> rows will be displayed.
 :
 
 = ADVANCED ARGUMENTS =
@@ -130,9 +134,7 @@ wimenu -c <fifo | awk '
 		print cmds >fifo; fflush(fifo)
 	}
 
-	# Store the last line we get and print it when done
+        { print; fflush() }
-	{ last = $0 }
-	END { print last }
 
 	# Push out a new set of completions
 	function update(str, opts) {
@@ -152,12 +154,12 @@ wimenu -c <fifo | awk '
 		# Skip the trailing part of the command
 		getline rest
 	}
-'
+' | tail -1
 ```
 
 In theory, this facility can be used for myriad purposes,
 including hijacking the programmable completion facilities of
-most shells.
+most shells. See also the provided examples[1].
 
 = ENVIRONMENT =
 
@@ -170,5 +172,5 @@ most shells.
 = SEE ALSO =
 wmii(1), wmiir(1), wistrug(1), wmii9menu(1), dmenu(1)
 
-[1] http://www.suckless.org/wiki/wmii/tips/9p_tips
+[1] http://www.suckless.org/wiki/wmii/tips/9p_tips +
-
+[2] @EXAMPLES@

rc/wmiirc.sh

@@ -78,8 +78,8 @@ startup
 echo colors $WMII_NORMCOLORS | wmiir create $noticebar
 
 # Event processing
-events() {
+local_events | wi_events
-	cat <<'!'
+wi_events <<'!'
 # Events
 Event CreateTag
 	echo colors "$WMII_NORMCOLORS$wi_newline" label "$@" | wmiir create "/lbar/$@"
@@ -237,15 +237,14 @@ Key $MODKEY-b	    # Move to the previous tag
 	wmiir xwrite /ctl view $(wi_tags | sort -r | wi_nexttag)
 !
 	for i in 0 1 2 3 4 5 6 7 8 9; do
-		cat <<!
+		wi_events <<!
 Key $MODKEY-$i		 # Move to the numbered view
 	wmiir xwrite /ctl view "$i"
 Key $MODKEY-Shift-$i     # Retag selected client with the numbered tag
 	wmiir xwrite /client/sel/ctl tags "$i"
 !
-	done
+done
-}
+wi_events -e
-wi_events events local_events
 
 # WM Configuration
 wmiir write /ctl <<!