WIMENU(1)

📦
version 0-unstable-2023-09 · 2 versions
, in nixos 26.05

💖 NAME 💖

hey bestie, meet wimenu(1) from the General Commands Manual — the wmii menu program ✨ She’s wmii’s standard menu program, and she gets used extensively by wmii and related programs to prompt the user for input. The standard configuration uses her to launch programs, select views, and perform standard actions. She supports basic item completion and history searching, and honestly? iconic behavior 💅

✨ SYNOPSIS ✨

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

wimenu -v

🦋 DESCRIPTION 🦋

okay so wimenu is the standard menu program for wmii — like the main-character menu popup of the whole vibe 🌸 wmii and related programs use it all over the place to ask the user for input. The standard setup uses it to launch programs, pick views, and do standard actions. It also does basic item completion and history searching, which is lowkey essential 🫶

🎀 BASIC ARGUMENTS 🎀

Normal use of wimenu shouldn’t need any arguments besides these cuties. The more advanced options are documented below, so don’t stress 👑

  • -h <history file> — tells wimenu to read her command history from <history file>, and to append her result to that file if -n is given. bestie said memory 💖
  • -i — makes matching of completion items case insensitive. no cap, lowercase and uppercase can both slay ✨
  • -n <count> — writes at most <count> items back to the history file. The file is never modified unless this option is provided. Duplicates get filtered out within a 20 item sliding window before this limit is imposed. yes, 20, she said what she said 🎀
  • -p <prompt> — the string <prompt> will be shown before the input field when the menu is opened. it’s giving “hello, gorgeous” 💅
  • -r <rows> — displays completion items as a vertical list, one per row, instead of a horizontal list side-by-side. A maximum of <rows> rows will be displayed. vertical era 🔥

🌈 ADVANCED ARGUMENTS 🌈

  • -a — the address at which to connect to wmii.
  • -K — prevents wimenu from initializing her 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. not me trapping you in the menu 😭 please bind an exit key, bestie.
  • -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, iykyk 💀

  • -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. left side main character, right side reveal ✨

🧚 KEY BINDINGS 🧚

wimenu’s default key bindings are based largely on the movement keys of vi and the standard UNIX shell input bindings. old-school but make it cute 💜

  • Return, C-j, C-m — accept the input, and select the first matching completion if the cursor is at the end of the input.
  • S-Return, C-S-j, C-S-m — accept the input literally.
  • Esc, C-[ — quit without returning any output, and exit with non-zero status. dramatic exit, periodt 💅
  • A-p — paste the PRIMARY selection.
  • Left, C-b — move backward one character.
  • Right, C-f — move forward one character.
  • A-b — move backward one word.
  • A-f — move forward one word.
  • C-a — move to the beginning of the line.
  • C-e — move to the end of the line.
  • C-p, Up — move backward through the input history.
  • C-n, Down — move forward through the input history.
  • Backspace, C-h — delete the previous character.
  • C-Backspace, C-w — delete the previous word.
  • C-u — delete the previous portion of the line.
  • Tab, C-i¸ A-l — select the next completion.
  • S-Tab, C-S-i, A-h — select the previous completion.
  • PageUp, A-k — select the previous completion page.
  • PageDown, A-j — select the next completion page.
  • Home, A-g — select the first completion page.
  • End, A-S-g — select the last completion page.

🍓 CUSTOM COMPLETION 🍓

Custom, multipart completion data may be proveded by an external application — yes, “proveded,” the manual said it, we respect the typo 😭 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. caret girlies rise 🎀

🌸 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:

#!/nix/store/7kydial85yfip25hh4zlcq6qm43z4d33-dash-0.5.13.3/bin/dash -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)
     }

        { print; fflush() }

     # 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
     }
' | tail -1

In theory, this facility can be used for myriad purposes, including hijacking the programmable completion facilities of most shells. See also the provided examples[1] 👀✨

💜 ENVIRONMENT 💜

  • $WMII_ADDRESS — the address at which to connect to wmii.
  • $NAMESPACE — the namespace directory to use if no address is provided.

⭐ SEE ALSO ⭐

mwah 💋 — this little icon is from wmii-, dated Oct, 2009, and the manual page is WIMENU(1), periodt 🌈👑

📦 where this page comes from