WIMENU
wmii-@VERSION@
Oct, 2009

%!includeconf: header.t2t

= NAME =

wimenu - The wmii menu program

= SYNOPSIS =

wimenu [-i] [-h <history file>] [-n <history count>] [-p <prompt>] +
wimenu -v

= DESCRIPTION =

`wimenu` is `wmii`'s standard menu program. It's used
extensively by `wmii` and related programs to prompt the user
for input. The standard configuration uses it to launch
programs, select views, and perform standard actions. It
supports basic item completion and history searching.

= BASIC ARGUMENTS =

Normal use of `wimenu` shouldn't require any arguments other than the
following. More advanced options are documented below.

: -h <history file>
        Causes `wimenu` to read its command history from
        <history file> and to append its result to that file if
        _-n_ is given.
: -i
        Causes matching of completion items to be performed in a
        case insensitive manner.
: -n <count>
        Write at most <count> items back to the history file.
        The file is never modified unless this option is
        provided. Duplicates are filtered out within a 20 item
        sliding window before this limit is imposed.
: -p <prompt>
        The string <prompt> will be show before the input field
        when the menu is opened.
:

= ADVANCED ARGUMENTS =

: -a
        The address at which to connect to `wmii`.
: -K
        Prevents `wimenu` from initializing its default key
        bindings. WARNING: If you do this, be sure to bind a key
        with the Accept or Reject action, or you will have no way
        to exit `wimenu`.
: -k <key file>
        Key bindings will be read from <key file>. Bindings
        appear as:

                <key> [action] [args]

        where <key> is a key name, similar to the format used by
        wmii. For action and args, please refer to the default
        bindings, provided in the source distribution under
        cmd/menu/keys.txt, or use strings(1) on the `wimenu`
        executable (this level of customization is reserved for the
        determined).
: -s <screen>
        Suggests that the menu open on Xinerama screen <screen>.
: -S <command separator>
	Causes each input item to be split at the first occurance of
	<command sep>. The text to the left of the separator is displayed
	as a menu option, and the text to the right is displayed when a
	selection is made.

= CUSTOM COMPLETION =

Custom, multipart completion data may be proveded by an
external application. When the standard input is not a TTY,
processing of a set of completions stops at every blank line.
After the first new line or EOF, `wimenu` displays the first
set of menu items, and waits for further input. The completion
items may be replaced by writing out a new set, again followed
by a new line. Every set following the first must begin with a
line containing a single decimal number specifying where the
new completion results are to be spliced into the input. When
an item is selected, text from this position to the position
of the caret is replaced.

== ARGUMENTS ==

: -c
        Prints the contents of the input buffer each time the
        user inputs a character, as such:

                <text before caret>\n<text after caret>\n
:

== EXAMPLE ==

Let's assume that a script would like to provide a menu with
completions first for a command name, then for arguments
to that command. Given three commands and argument sets,

: foo
	1, 2, 3
: bar
	4, 5, 6
: baz
	7, 8, 9

the following script provides the appropriate completions:

```
#!/bin/sh -f

rm fifo
mkfifo fifo

# Open wimenu with a fifo as its stdin
wimenu -c <fifo | awk '
	BEGIN {
		# Define the completion results
		cmds = "foo\nbar\nbaz\n"
		cmd["foo"] = "1\n2\n3\n"
		cmd["bar"] = "4\n5\n6\n"
		cmd["baz"] = "7\n8\n9\n"

		# Print the first set of completions to wimenu’s fifo
		fifo = "fifo"
		print cmds >fifo; fflush(fifo)
	}

	# Store the last line we get and print it when done
	{ last = $0 }
	END { print last }

	# Push out a new set of completions
	function update(str, opts) {
		print length(str) >fifo # Print the length of the preceding string
		print opts >fifo        # and the options themself
		fflush(fifo)
	}

	# Ensure correct argument count with trailing spaces
	/ $/ { $0 = $0 "#"; }

	{ # Process the input and provide the completions
		if (NF == 1)
			update("", cmds)        # The first arg, command choices
		else
			update($1 " ", cmd[$1]) # The second arg, command arguments
		# Skip the trailing part of the command
		getline rest
	}
'
```

In theory, this facility can be used for myriad purposes,
including hijacking the programmable completion facilities of
most shells.

= ENVIRONMENT =

: $WMII_ADDRESS
        The address at which to connect to wmii.
: $NAMESPACE
        The namespace directory to use if no address is
        provided.
:
= SEE ALSO =
wmii(1), wmiir(1), wistrug(1), wmii9menu(1), dmenu(1)

[1] http://www.suckless.org/wiki/wmii/tips/9p_tips