VIS-MENU(1)

📦
version 0.9.r531.gd89b6c27 · 5 versions
, in arch rolling

👑 VIS-MENU(1) — the select-something-from-a-list era 💅

ok so bestie, this is vis-menu, from the General Commands Manual section, and it's genuinely one of the most useful little icons in your toolbox. Let me walk you through it. 🫶

✨ NAME ✨

vis-menu — interactively select an item from a list. that's it. that's the whole vibe.

🌸 SYNOPSIS 🌸

vis-menu [-i] [-t | -b] [-p prompt] [-l lines] [initial]
vis-menu [-v]

literally two whole modes. pick things, or check the version. she contains multitudes. 💖

🦋 DESCRIPTION 🦋

okay so here's the whole thing: vis-menu lets a user interactively select one item from a list of options. It reads a newline-separated list of items from standard input, then draws that list directly onto the terminal so the user can pick one. Finally — the moment we've all been waiting for — the selected item gets printed to standard output. slay. ✨

for the deets on actually navigating the menu, scroll down to USAGE, i gotchu.

  • -i — use case-insensitive comparison when filtering items. so APPLE and apple are the same girl. 🍎
  • -t | -b — normally the menu is displayed on the current line of the terminal. when -t is provided, the menu is always drawn on the top line of the terminal. when -b is provided, the menu is always drawn on the bottom line. top or bottom, no in-between, main character placement only. 👑
  • -p prompt — display prompt before the list of items. a little intro, a little "hey girl, pick one". 🎀
  • -l lines — okay so normally the list is displayed with all the items side-by-side on a single line, which is space-efficient but does not show many items at a time, especially if some of them are long (😭 the struggle). when -l is provided, the list is displayed with each item on its own line, lines lines high. if there are more than lines items in the list, the user can scroll through them with the arrow keys — just like in the regular horizontal mode. same energy, different layout. ✨
  • initial — the user can type into a text field to filter the list of items as well as scrolling through them. if supplied, initial is used as the initial content of the text field. pre-filled and pre-cute. 💜
  • -v — instead of displaying an interactive menu, vis-menu prints its version number to standard output and exits. no vibes, just facts. 😌

💅 USAGE 💅

so vis-menu displays the prompt (if any), a text field, and a list of items. normally these are presented side-by-side in a single line, but if the -l flag is given, the prompt and typing area will be on the first line, and list items on the following lines. very organized of her. 🎀

the following commands are available — memorize them, they're your whole personality now:

  • Enter — selects the currently-highlighted list item and exits. the classic. the moment. 🔥
  • Control+\ or Control+] — selects the current contents of the text field (even if it does not appear in the list) and exits. yes, you can just make stuff up. icon behavior. 👑
  • ESC ESC or Control+C — exit without selecting any item. the irish goodbye. 🙈
  • Down or Control+N — scroll forward through the available list items.
  • Up or Control+P — scroll backward through the available list items.
  • Right or Control+F — move the cursor forward through the typed text, and scroll through the available list items.
  • Left or Control+B — move the cursor backward through the typed text, and scroll through the available list items.
  • PageUp or Control+V — scrolls to show the previous page of list items.
  • PageDown or Meta+v — scrolls to show the next page of list items.
  • Home or Control+A — move the cursor to the beginning of the text field or scroll to the first item in the list. double duty, she's versatile. 💅
  • End or Control+E — move the cursor to the end of the text field or scroll to the last item in the list.
  • Meta+b — moves the cursor to the beginning of the current word in the text field.
  • Meta+f — moves the cursor past the end of the current word in the text field.
  • Tab — copies the content of the selected list item into the text field. this is almost, but not quite, like tab completion. close enough to fool your friends. 🧚
  • Delete or Control+D — delete the character in the text field under the cursor.
  • Backspace — deletes the character in the text field to the left of the cursor.
  • Meta+d — deletes the characters in the text field from the character under the cursor to the next space.
  • Control+K — deletes the characters in the text field from the character under the cursor to the end.
  • Control+U — deletes the characters in the text field from the beginning up to (but not including) the character under the cursor.
  • Control+W — deletes the characters in the text field from the previous space up to (but not including) the character under the cursor.

all other non-control characters will be inserted into the text field at the current cursor position. type away bestie. ⌨️✨

when there is text in the text field, only list items that include the given text will be shown. and if the text contains one or more spaces, each space-delimited string is a separate filter — and only items matching every filter will be shown. so foo bar means "matches foo AND matches bar". no cap. 🫶

and here's a fun one: if the user filters out all the items from the list, then hits Enter to select the "currently highlighted" item, the text they typed will be returned instead. the void answers back. 💀

🔥 EXAMPLES 🔥

here's a shell-script that allows the user to choose a number from one to 10 — copy it, run it, live your truth:

NUMBER=$(seq 1 10 | vis-menu -p "Choose a number")
if [ $? -eq 0 ]; then
        echo "You chose: $NUMBER"
else
        echo "You refused to choose a number, or an error occurred."
fi

look at that exit-status handling. we love a script that checks $?. 🌈

💀 DIAGNOSTICS 💀

the vis-menu utility exits 0 if the user successfully selected an item from the list, and 1 if the user cancelled. simple. clean. ✨

if an internal error occurs, the vis-menu utility prints a message to standard error and terminates with an exit status greater than 1. potential error conditions include being unable to allocate memory, being unable to read from standard input, or being run without a controlling terminal. so like… give her a terminal, she needs one. 😭

🦋 SEE ALSO 🦋

dmenu(1), slmenu(1), vis(1)

the whole friend group. 🫶

🌈 HISTORY 🌈

the original model for a single line menu reading items from standard input was dmenu(1), which implements the idea for X11. dmenu is available from http://tools.suckless.org/dmenu/

the code was subsequently re-worked for ANSI terminal output as slmenu(1), which is available from https://bitbucket.org/rafaelgg/slmenu/

since slmenu did not appear to be maintained, it was forked to become vis-menu, to be distributed with vis(1). and that's how our girl got here. glow-up complete. 👑

ok that's the whole page bestie, go pick something from a list, you're gonna eat 💅

signed off with love — this is from Vis v0.9-531-gd89b6c27-dirty, dated November 29, 2016, so she's vintage but she still slays. 🎀

📦 where this page comes from