vis-menu.1 (6018B)
- .Dd November 29, 2016
- .Dt VIS-MENU 1
- .Os Vis v0.9
- .Sh NAME
- .Nm vis-menu
- .Nd Interactively select an item from a list
- .
- .Sh SYNOPSIS
- .Nm vis-menu
- .Op Fl i
- .Op Fl t | Fl b
- .Op Fl p Ar prompt
- .Op Fl l Ar lines
- .Op Ar initial
- .Nm vis-menu
- .Op Fl v
- .
- .Sh DESCRIPTION
- .Nm vis-menu
- allows a user to interactively select one item from a list of options.
- A newline-separated list of items is read from standard input,
- then the list of items is drawn directly onto the terminal
- so the user may select one.
- Finally,
- the selected item is printed to standard output.
- .Pp
- For information on actually navigating the menu,
- see
- .Sx USAGE
- below.
- .Bl -tag -width flag
- .It Fl i
- Use case-insensitive comparison when filtering items.
- .It Fl t | Fl b
- Normally,
- the menu is displayed on the current line of the terminal.
- When
- .Fl t
- is provided, the menu will always be drawn on the top line of the terminal.
- When
- .Fl b
- is provided, the menu will always be drawn on the bottom line.
- .It Fl p Ar prompt
- Display
- .Ar prompt
- before the list of items.
- .It Fl l Ar lines
- 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.
- When
- .Fl l
- is provided,
- the list is displayed with each item on its own line,
- .Ar lines
- lines high.
- If there are more than
- .Ar lines
- items in the list,
- the user can scroll through them with the arrow keys,
- just like in the regular horizontal mode.
- .It Ar initial
- The user can type into a text field
- to filter the list of items
- as well as scrolling through them.
- If supplied,
- .Ar initial
- is used as the initial content of the text field.
- .It Fl v
- Instead of displaying an interactive menu,
- .Nm vis-menu
- prints its version number to standard output and exits.
- .El
- .
- .Sh USAGE
- .Nm 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
- .Fl l
- flag is given,
- the prompt and typing area will be on the first line,
- and list items on the following lines.
- .Pp
- The following commands are available:
- .Bl -tag -width ".Sy Control-A"
- .It Sy Enter
- selects the currently-highlighted list item and exits.
- .It Xo Sy Control-\e
- or
- .Sy Control-\&]
- .Xc
- selects the current contents of the text field
- (even if it does not appear in the list)
- and exits.
- .It Xo Sy "ESC ESC"
- or
- .Sy Control-C
- .Xc
- exit without selecting any item.
- .It Xo Sy Down
- or
- .Sy Control-N
- .Xc
- scroll forward through the available list items.
- .It Xo Sy Up
- or
- .Sy Control-P
- .Xc
- scroll backward through the available list items.
- .It Xo Sy Right
- or
- .Sy Control-F
- .Xc
- move the cursor forward through the typed text,
- and scroll through the available list items.
- .It Xo Sy Left
- or
- .Sy Control-B
- .Xc
- move the cursor backward through the typed text,
- and scroll through the available list items.
- .It Xo Sy PageUp
- or
- .Sy Control-V
- .Xc
- scrolls to show the previous page of list items.
- .It Xo Sy PageDown
- or
- .Sy Meta-v
- .Xc
- scrolls to show the next page of list items.
- .It Xo Sy Home
- or
- .Sy Control-A
- .Xc
- move the cursor to the beginning of the text field
- or scroll to the first item in the list.
- .It Xo Sy End
- or
- .Sy Control-E
- .Xc
- move the cursor to the end of the text field
- or scroll to the last item in the list.
- .It Sy Meta-b
- moves the cursor to the beginning of the current word in the text field.
- .It Sy Meta-f
- moves the cursor past the end of the current word in the text field.
- .It Sy Tab
- copies the content of the selected list item into the text field.
- This is almost, but not quite, like tab completion.
- .It Xo Sy Delete
- or
- .Sy Control-D
- .Xc
- delete the character in the text field under the cursor.
- .It Sy Backspace
- deletes the character in the text field to the left of the cursor.
- .It Sy Meta-d
- deletes the characters in the text field
- from the character under the cursor
- to the next space.
- .It Sy Control-K
- deletes the characters in the text field
- from the character under the cursor to the end.
- .It Sy Control-U
- deletes the characters in the text field
- from the beginning up to
- (but not including)
- the character under the cursor.
- .It Sy Control-W
- deletes the characters in the text field
- from the previous space up to
- (but not including)
- the character under the cursor.
- .El
- .Pp
- All other non-control characters will be inserted into the text field
- at the current cursor position.
- .Pp
- When there is text in the text field,
- only list items that include the given text will be shown.
- 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.
- .Pp
- If the user filters out all the items from the list,
- then hits Enter to select the
- .Dq currently highlighted
- item,
- the text they typed will be returned instead.
- .
- .Sh EXAMPLES
- Here's a shell-script that allows the user to choose a number from one to 10:
- .Bd -literal -offset indent
- 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
- .Ed
- .
- .Sh DIAGNOSTICS
- The
- .Nm vis-menu
- utility exits 0 if the user successfully selected an item from the list,
- and 1 if the user cancelled.
- .Pp
- If an internal error occurs,
- the
- .Nm 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.
- .
- .Sh SEE ALSO
- .Xr dmenu 1 ,
- .Xr slmenu 1 ,
- .Xr vis 1
- .
- .Sh HISTORY
- The original model for a single line menu reading items from standard input was
- .Xr dmenu 1
- which implements the idea for X11.
- .Nm dmenu
- is available from
- .Li http://tools.suckless.org/dmenu/
- .Pp
- The code was subsequently re-worked for ANSI terminal output as
- .Xr slmenu 1
- which is available from
- .Li https://bitbucket.org/rafaelgg/slmenu/
- .Pp
- Since
- .Nm slmenu
- did not appear to be maintained,
- it was forked to become
- .Nm vis-menu
- to be distributed with
- .Xr vis 1 .