vis

a vi-like editor based on Plan 9's structural regular expressions
vis-menu.1

(6021B)
      1 .Dd November 29, 2016
      2 .Dt VIS-MENU 1
      3 .Os Vis VERSION
      4 .Sh NAME
      5 .Nm vis-menu
      6 .Nd Interactively select an item from a list
      7 .
      8 .Sh SYNOPSIS
      9 .Nm vis-menu
     10 .Op Fl i
     11 .Op Fl t | Fl b
     12 .Op Fl p Ar prompt
     13 .Op Fl l Ar lines
     14 .Op Ar initial
     15 .Nm vis-menu
     16 .Op Fl v
     17 .
     18 .Sh DESCRIPTION
     19 .Nm vis-menu
     20 allows a user to interactively select one item from a list of options.
     21 A newline-separated list of items is read from standard input,
     22 then the list of items is drawn directly onto the terminal
     23 so the user may select one.
     24 Finally,
     25 the selected item is printed to standard output.
     26 .Pp
     27 For information on actually navigating the menu,
     28 see
     29 .Sx USAGE
     30 below.
     31 .Bl -tag -width flag
     32 .It Fl i
     33 Use case-insensitive comparison when filtering items.
     34 .It Fl t | Fl b
     35 Normally,
     36 the menu is displayed on the current line of the terminal.
     37 When
     38 .Fl t
     39 is provided, the menu will always be drawn on the top line of the terminal.
     40 When
     41 .Fl b
     42 is provided, the menu will always be drawn on the bottom line.
     43 .It Fl p Ar prompt
     44 Display
     45 .Ar prompt
     46 before the list of items.
     47 .It Fl l Ar lines
     48 Normally,
     49 the list is displayed with all the items side-by-side on a single line,
     50 which is space-efficient
     51 but does not show many items at a time,
     52 especially if some of them are long.
     53 When
     54 .Fl l
     55 is provided,
     56 the list is displayed with each item on its own line,
     57 .Ar lines
     58 lines high.
     59 If there are more than
     60 .Ar lines
     61 items in the list,
     62 the user can scroll through them with the arrow keys,
     63 just like in the regular horizontal mode.
     64 .It Ar initial
     65 The user can type into a text field
     66 to filter the list of items
     67 as well as scrolling through them.
     68 If supplied,
     69 .Ar initial
     70 is used as the initial content of the text field.
     71 .It Fl v
     72 Instead of displaying an interactive menu,
     73 .Nm vis-menu
     74 prints its version number to standard output and exits.
     75 .El
     76 .
     77 .Sh USAGE
     78 .Nm vis-menu
     79 displays the prompt (if any),
     80 a text field,
     81 and a list of items.
     82 Normally these are presented side-by-side in a single line,
     83 but if the
     84 .Fl l
     85 flag is given,
     86 the prompt and typing area will be on the first line,
     87 and list items on the following lines.
     88 .Pp
     89 The following commands are available:
     90 .Bl -tag -width ".Sy Control-A"
     91 .It Sy Enter
     92 selects the currently-highlighted list item and exits.
     93 .It Xo Sy Control-\e
     94 or
     95 .Sy Control-\&]
     96 .Xc
     97 selects the current contents of the text field
     98 (even if it does not appear in the list)
     99 and exits.
    100 .It Xo Sy "ESC ESC"
    101 or
    102 .Sy Control-C
    103 .Xc
    104 exit without selecting any item.
    105 .It Xo Sy Down
    106 or
    107 .Sy Control-N
    108 .Xc
    109 scroll forward through the available list items.
    110 .It Xo Sy Up
    111 or
    112 .Sy Control-P
    113 .Xc
    114 scroll backward through the available list items.
    115 .It Xo Sy Right
    116 or
    117 .Sy Control-F
    118 .Xc
    119 move the cursor forward through the typed text,
    120 and scroll through the available list items.
    121 .It Xo Sy Left
    122 or
    123 .Sy Control-B
    124 .Xc
    125 move the cursor backward through the typed text,
    126 and scroll through the available list items.
    127 .It Xo Sy PageUp
    128 or
    129 .Sy Control-V
    130 .Xc
    131 scrolls to show the previous page of list items.
    132 .It Xo Sy PageDown
    133 or
    134 .Sy Meta-v
    135 .Xc
    136 scrolls to show the next page of list items.
    137 .It Xo Sy Home
    138 or
    139 .Sy Control-A
    140 .Xc
    141 move the cursor to the beginning of the text field
    142 or scroll to the first item in the list.
    143 .It Xo Sy End
    144 or
    145 .Sy Control-E
    146 .Xc
    147 move the cursor to the end of the text field
    148 or scroll to the last item in the list.
    149 .It Sy Meta-b
    150 moves the cursor to the beginning of the current word in the text field.
    151 .It Sy Meta-f
    152 moves the cursor past the end of the current word in the text field.
    153 .It Sy Tab
    154 copies the content of the selected list item into the text field.
    155 This is almost, but not quite, like tab completion.
    156 .It Xo Sy Delete
    157 or
    158 .Sy Control-D
    159 .Xc
    160 delete the character in the text field under the cursor.
    161 .It Sy Backspace
    162 deletes the character in the text field to the left of the cursor.
    163 .It Sy Meta-d
    164 deletes the characters in the text field
    165 from the character under the cursor
    166 to the next space.
    167 .It Sy Control-K
    168 deletes the characters in the text field
    169 from the character under the cursor to the end.
    170 .It Sy Control-U
    171 deletes the characters in the text field
    172 from the beginning up to
    173 (but not including)
    174 the character under the cursor.
    175 .It Sy Control-W
    176 deletes the characters in the text field
    177 from the previous space up to
    178 (but not including)
    179 the character under the cursor.
    180 .El
    181 .Pp
    182 All other non-control characters will be inserted into the text field
    183 at the current cursor position.
    184 .Pp
    185 When there is text in the text field,
    186 only list items that include the given text will be shown.
    187 If the text contains one or more spaces,
    188 each space-delimited string is a separate filter
    189 and only items matching every filter will be shown.
    190 .Pp
    191 If the user filters out all the items from the list,
    192 then hits Enter to select the
    193 .Dq currently highlighted
    194 item,
    195 the text they typed will be returned instead.
    196 .
    197 .Sh EXAMPLES
    198 Here's a shell-script that allows the user to choose a number from one to 10:
    199 .Bd -literal -offset indent
    200 NUMBER=$(seq 1 10 | vis-menu -p "Choose a number")
    201 if [ $? -eq 0 ]; then
    202 	echo "You chose: $NUMBER"
    203 else
    204 	echo "You refused to choose a number, or an error occurred."
    205 fi
    206 .Ed
    207 .
    208 .Sh DIAGNOSTICS
    209 The
    210 .Nm vis-menu
    211 utility exits 0 if the user successfully selected an item from the list,
    212 and 1 if the user cancelled.
    213 .Pp
    214 If an internal error occurs,
    215 the
    216 .Nm vis-menu
    217 utility prints a message to standard error and terminates with an exit
    218 status greater than 1.
    219 Potential error conditions include
    220 being unable to allocate memory,
    221 being unable to read from standard input,
    222 or being run without a controlling terminal.
    223 .
    224 .Sh SEE ALSO
    225 .Xr dmenu 1 ,
    226 .Xr slmenu 1 ,
    227 .Xr vis 1
    228 .
    229 .Sh HISTORY
    230 The original model for a single line menu reading items from standard input was
    231 .Xr dmenu 1
    232 which implements the idea for X11.
    233 .Nm dmenu
    234 is available from
    235 .Li http://tools.suckless.org/dmenu/
    236 .Pp
    237 The code was subsequently re-worked for ANSI terminal output as
    238 .Xr slmenu 1
    239 which is available from
    240 .Li https://bitbucket.org/rafaelgg/slmenu/
    241 .Pp
    242 Since
    243 .Nm slmenu
    244 did not appear to be maintained,
    245 it was forked to become
    246 .Nm vis-menu
    247 to be distributed with
    248 .Xr vis 1 .