Provided by: smenu_1.2.0-1_amd64 
NAME
smenu - filter that allows one to interactively select a word from stdin and outputs the
selection to stdout.
SYNOPSIS
[*-h|-help]
[*-H|-long_help]
[*-?|-u|-usage]
[*-V|-version]
[-n|-lines|-height [height]]
[-i|-in|-inc|-incl|-include... regex]
[-e|-ex|-exc|-excl|-exclude... regex]
[-m|-msg|-message|-title message]
[-!|-int|-int_string [string]]
[-a|-attr|-attributes prefix:attr...]
[-1|-l1|-level1 regex [attr]]
[-2|-l2|-level2 regex [attr]]
[-3|-l3|-level3 regex [attr]]
[-4|-l4|-level4 regex [attr]]
[-5|-l5|-level5 regex [attr]]
[-6|-l6|-level6 regex [attr]]
[-7|-l7|-level7 regex [attr]]
[-8|-l8|-level8 regex [attr]]
[-9|-l9|-level9 regex [attr]]
[-T|-tm|-tag|-tag_mode [delim]]
[-z|-zap|-zap_glyphs bytes]
[-P|-pm|-pin|-pin_mode [delim]]
[-0|-noat|-no_auto_tag]
[-p|-at|-auto_tag]
[-N|-number... [regex...]]
[-U|-unnumber... [regex...]]
[-F|-en|-embedded_number]
[-D|-data|-options [parameter...]
[-b|-blank]
[-M|-middle|-center]
[-d|-restore|-delete|-clean|-delete_window|-clean_window]
[-c|-col|-col_mode|-column]
[-l|-line|-line_mode]
[-t|-tab|-tab_mode|-tabulate_mode [cols]]
[-w|-wide|-wide_mode]
[-C|-cs|-cols|-cols_select... selector...]
[-R|-rs|-rows|-rows_select... selector...]
[-A|-fc|-first_column regex]
[-Z|-lc|-last_column regex]
[-g|-gutter [string]]
[-k|-ks|-keep_spaces]
[-W|-ws|-wd|-word_delimiters|-word_separators bytes]
[-L|-ls|-ld|-line-delimiters|-line_separators bytes]
[-q|-no_bar|-no-scroll_bar]
[-S|-subst... /regex/repl/opts]
[-I|-si|-subst_included... /regex/repl/opts]
[-E|-se|-subst_excluded... /regex/repl/opts]
[-ES|-early_subst... /regex/repl/opts]
[-/|-search_method prefix|substring|fuzzy]
[-s|-sp|-start|-start_pattern pattern]
[-x|-tmout|-timeout type [word] delay]
[-X|-htmout|-hidden_timeout type [word] delay]
[-r|-auto_validate]
[-is|-incremental_search]
[-v|-vb|-visual_bell]
[-Q|-ignore_quotes]
[-lim|-limits limit:value...]
[-f|-forgotten_timeout|-global_timeout timeout]
[-nm|-no_mouse]
[-br|-buttons|-button_remapping new_button_1 new_button_3]
[-dc|-dcd|-double_click|-double_click_delay delay_in_ms]
selectors ::= col1[-col2],...|row1[-row2],...|RE,...
parameter ::= [l|r:<char>]|[a:left|right]|[p:included|all|[w:<num>]|
[f:yes|no]|[o:<num>[+]]|[n:<num>]|[i:<num>]|[d:<char>]|
[s:<num>]|[h:trim|cut|keep]
attr ::= [fg][/bg][,style]
RE ::= <char>regex<char>
selectors and RE can be freely mixed.
style can only contain a maximum of 6 characters.
<char> in RE is any non-blank ASCII character except ','.
Note that some parameters require that others have been previously entered in the command
line to be accepted.
DESCRIPTION
This small utility acts as a filter when no input file is given (reads from stdin and
writes to stdout) or takes its inputs from that file.
All words read are presented in a scrolling window on the terminal at the current cursor
position, without clearing the screen first.
The selection cursor is initially positioned on the first selectable word by default.
There are options to explicitly or implicitly include or exclude words using extended
regular expressions. Note that once certain words are explicitly excluded, they cannot be
re-included later.
Excluded words are skipped when the selection cursor is moved and cannot be searched for.
The -W|-ws|-wd|-word_delimiters|-word_separators option can be used to set the characters
(or multibyte sequences) which will be used to delimit the input words. The default
delimiters are: SPACE, \t and \n.
The -L|-ls|-ld|-line-delimiters|-line_separators has a similar meaning for lines.
Special character sequences formed by a \ followed by one of the characters a b t n v f r
and \ are understood and have their traditional meanings.
smenu strives to support UTF-8 encoding, both as input and output. UTF-8 sequences
introduced by \u and \U are also understood.
Warning, when used together, it is important to know that all sequences beginning with \U
will be interpreted before the beginning of the interpretation of sequences beginning with
\u.
\u can be followed by 2,4,6 or 8 hexadecimal characters composing an UTF-8 bytestring.
Here is an example of using \u to compose a Latin Small Letter E with Acute: \uc3a9.
\U must be followed by exactly 6 hexadecimal digits, including leading zeros, that
represent a Unicode codepoint according to ISO 10646 UCS-4. The Latin Small Letter E with
Acute of the previous example (codepoint U+00E9) can then be represented as \U0000e9.
Note that with most shells, the \ before u and U need to be protected or escaped.
Quotations (single and double) in the input stream can be used to ignore the word
separators so that a group of words are taken as a single entity.
Non printable characters in words that are not delimiters are converted to their
traditional form (\n for end-of-line, \t for tabulation...) by default.
An invalid UTF-8 sequence or other non-printable character will be replaced by a dot (.)
by default.
There is nevertheless a possibility to change this substitution character with another
ASCII printable one with the help of the command line option -.|-dot|-invalid.
Warning, UTF-8 encoded codepoints are quietly converted into the substitution character
when the user locale is not UTF-8 aware like POSIX or C by example.
Words containing only spaces, entered directly or resulting from a substitution, are also
rejected unless they are not selectable. This allows special effects like creating blank
lines for example. These words are also kept in column mode, selectable or not.
smenu has an option to define a set of characters or UTF-8 sequences which should be
ignored when reading words. This can be very useful when dealing with inputs where the
EOL sequence consists in more than one character.
A typical example is DOS or Windows files with lines ending with CRLF. In such a case one
might decide to ignore all CR characters from the input.
Moving among words using the keyboard and maybe the mouse
keyboard:
The cursor can be moved in any direction using the arrow keys of the keyboard: ←, ↓, ↑,
→ or the vi direction keys: h, j, k and l. The HOME, END, PgDn and PgUp keys can also
be used when available.
The meaning of the movement keys is as follows:
←, h Previous word
CTRL ←, H Start of line
↑, k Previous line
PgUp, K Previous page
HOME First word of the window
CTRL HOME, SHIFT HOME, CTRL K First word
< The window's content is shifted to the
left while keeping the cursor visible
→, l Next word
CTRL →, L End of line
↓, j Next line
PgDn, J Next page
END Last word of the window
CTRL END, SHIFT END, CTRL J Last word
> The window's content is shifted to the
right while keeping the cursor visible
CTRL ←/H (resp. CTRL →/L) places the cursor so that a maximum number of words
(selectable or not) are visible to the left (reps. right) side of the window.
When the content of the window is shifted to the left or right using < or > or the
mouse, the cursor always highlights the same word and remains visible. This can block
sole shifting operations.
Mouse:
With many terminal emulators, it is possible to use the mouse to interact with the
screen content.
When the mouse is supported, the cursor can turn into an arrow (but not always) and the
mouse can then be used as a point and click device as follows:
First (usually left) mouse button (note that buttons can be remapped):
• A click on a word selects it if it is selectable.
• A click on a word while holding the CTRL key pressed marks/unmarks it if it is
selectable.
• A click at the ends of the scroll bar is equivalent to pressing the up and down
arrow on the keyboard.
A click on another location of the scroll bar moves the cursor to another word
depending on the location clicked. The new current word will be positioned at the
beginning of a line if possible.
• A double-click on a word selects it if it is selectable and acts as if the Enter key
had been pressed, the double-click delay is configurable.
• A click on the left or right horizontal arrow (when visible) shifts the content of
the window to the left or right, one word at a time.
Nothing is done if the cursor is at risk to leave the window.
Note that clicking on a left-facing arrow in an empty line means that not all the
words in that line could be displayed because of previous shifts or moves. In this
case, smenu will try to display the last word of this line but it is not always
possible as the cursor must remain visible.
The keyboard commands < and > can be used in such a case because the cursor is
already on the current line.
Third (usually right) mouse button:
• When tagging or pinning is enabled, a click on a word tags/untags it if it is
selectable.
• When tagging or pinning is enabled, a click on a word while holding the CTRL key
pressed has the following actions:
- If the word clicked is selectable and no word is already marked then marks it.
- If a word is marked and the clicked word is selectable and is not the marked word,
then:
+ In column mode, if the marked word is in the same column/line as the clicked
word, tags all words bounded by those words in that column/line as if Z the
keyboard command were used.
+ In line or column mode, if the marked word is in the same line as the clicked
word, tags all words bounded by those words in that line.
+ Otherwise, tags all words bounded by the marked word and the clicked one.
+ In all cases, the mark is removed.
Mouse wheel:
• Rotating the mouse wheel scrolls the contents of the window one line up or down.
• Rotating the mouse wheel while holding down the CTRL key scrolls the contents of the
window one page up or down.
This feature may not work depending on the terminal and operating system.
Be sure to use the wheel when the mouse pointer is over the smenu window, as some
terminal emulators may otherwise zoom the screen in and out instead.
Remember that mouse support does not disable the keyboard, so use the keys instead if
the mouse is not working properly.
Some terminals may not report clicks after the 223rd line or column due to a limitation
of the old X11 mouse tracking protocol, one example of such a terminal emulator is
screen < 4.7.0. tmux as well as screen >= 4.7.0 are fine.
Keyboard and mouse can be used at the same time.
Remark 1.
Some X-Window terminal emulators may not support the enable/disable bracketed pastes
escape sequence, in such a case if may be necessary to explicitly clear the content of
the paste buffer before running smenu so that the mouse buttons (especially for
pasting) do their job correctly.
This action can easily be performed using the command xsel -c for example.
Remark 2.
Some X-Windows terminal emulators intercept mouse input when some modifiers are used,
a typical example is xterm which displays popup menus in these cases.
For xterm (Patch #361 - 2020/10/14 or later) a working workaround is to use the X
resource XTerm*omitTranslation:popup-menu either by adding it in your .Xresources file
and register it with xrdb or by launching xterm using the -xrm
'XTerm*omitTranslation:popup-menu' command line option.
Remark 3 for BSD systems.
In order for the mouse to work properly under (virtualised?) FreeBSD and perhaps other
BSD variants, it may be necessary add the following two lines to the file ~/.Xmodmap:
! Disable button 8 and 9.
pointer = 1 2 3 4 5 6 7 0 0 10 11 12
And run the command: xmodmap ~/.Xmodmap (ignore any warnings issued by this command).
This can also be done non-permanently by running the command:
xmodmap -e "pointer = 1 2 3 4 5 6 7 0 0 10 11 12"
If this is not enough, try to disable buttons 8 to 12.
Direct acess:
If -N|-number, -U|-unnumber or -F|-en|-embedded_number are used, then it becomes
possible to directly access a word by entering its number. The numbering created using
these option is done before any words substitution done using -S|-subst
/regex/repl/opts, -I|-si|-subst_included or -E|-se|-subst_excluded.
Using a combination of these options, it is easy to control which words will be numbered
by adding a special symbol in it before using smenu and removing it (substituted by
nothing) afterward using -I|-si|-subst_included by example.
-E|-se|-subst_excluded gives another way to do that, see below or more.
Changing input words
smenu offers the possibility to modify the input words in a sed-like way. Words can be
modified at two points: just after they have been read and after other operations have
been applied, such as enabling, disabling or coloring.
The related options are -ES|-subst, -S|-subst, -I|-si|-subst_included and
-E|-se|-subst_excluded their descriptions can be found in the OPTIONS section.
Searching for words
A word can be searched using different algorithms: prefix, substring of fuzzy.
prefix (keys ^ or =):
The sequence of characters entered must match the beginning of a word.
substring (keys " or '):
The sequence of characters entered must match a substring in a word.
fuzzy (keys ~ or *):
All the characters in the entered sequence must appear in the same order in a word,
but need not be consecutive.
The case is also ignored.
Note that spaces and tabs at the beginning and end of words are ignored when
searching for substrings or fuzzy strings.
The cursor is placed, if possible, on the first matching word having the minimum
number of gaps between the first and last matching character, see the difference
between the actions of the s/S and n/N keys below.
This method also tolerates intermediate symbols not appearing in the words which
will be ignored. If this is the case, the attributes of the approximately matching
words are changed into an error versions of them to warn the user to this
situation.
The erroneous symbols will not be inserted in the search buffer.
For example: if the word abcdef is present in the standard input, then entering
abxcdye puts abcdef in the search buffer and the word is added to the list of
matching words and displayed with an error attribute (in red by default).
This special state will persist until all the symbols following the first erroneous
one are deleted (using backspace) or if ESC is pressed to cancel the search session
and clear the search buffer.
During a search session, the cursor changes and each character entered is added in (or
removed from) the search buffer. The display is refreshed after each change in this
buffer.
A 10 seconds timeout (by default) automatically ends the current search session as if the
Enter key had been pressed. This timeout is reset each time a new key is hit in search
mode. This delay can be configured using the search entry in the timers section of the
configuration file as shown in the example in the configuration subsection.
The slash key (/) can also be used instead of any of these keys. By default it is is
programmed to do a fuzzy search but this can be changed by using the command line option
(-/|-search_method) or by tuning a configuration file, see below.
All the words matching the current search buffer are enhanced: The characters present in
the current search buffer are highlighted in one way and the other characters in another
way. Both of these highlighting methods are configurable.
If the user has entered the search sequence: o, s, then the matching word "words" will be
displayed as words when the fuzzy algorithm is in use depending of the display attributes
configured.
ENTER and all cursor moves terminate the search session but do not clear the list of the
matching words and the search buffer.
The user can then use the n/s/SPACE keys (forward) and the N/S keys (backward) to navigate
in the list of matching words,
In fuzzy search mode, the s/S keys attempt to move the cursor to the next/previous word
whose matching part forms a substring of this word. If no such matches exist, s/S and n/N
do the same things. To move the cursor to the next/previous fuzzy match, use the
n/N/SPACE keys. s means next substring match in this context while n just means next
match.
If the user hits the HOME or END key during a search session then the list of matching
words is reduced to the words starting (respectively) ending with the current search
pattern and the window is refreshed. For those who consider HOME and END as non-
intuitive, the CTRL A and CTRL Z keys are also available in search mode as an alternative.
This behavior is persistent until the user hit the ESC or ENTER key.
For example, if the search pattern in substring mode is sh and the user hits END, then
only the words ending with sh will be added in the searched word list and enhanced.
Note that when a matching word is selected, its enhanced characters only show one of the
multiple matching possibilities.
When not in a search session ESC can be also used to clear the list of matching words and
to reset the search buffer.
Note that the search buffer is persistent as long as the same search algorithm is used and
ESC has not been pressed.
Selection and Exit
Pressing q gives the possibility to exit without selecting anything.
CTRL C (Abort) also exits the program immediately with a return code equal to 128+SINGINT
(by default) without selecting anything. See the -!|-int|-int_string option for more
information about the customization of the CTRL C behavior.
By default, ENTER or a double click with the first mouse button if applicable writes the
selected word to stdout when not in search mode otherwise it exits from this mode and does
nothing more. If you want to be able to select a word even when in search mode, use the
-r|-auto_validate option to change this behavior.
Tagging (multiple selections)
When the tagging is activated by using the command line -T|-tm|-tag|-tag_mode or
-P|-pm|-pin|-pin_mode option, then the keys t, u, INS, DEL c, r, m, M, T, C, R and U, can
be used to tag/untag some words. These tagged words will then be sent to the standard
output when ENTER is pressed.
Their meanings is as follows:
t Tags/untags or Pin/unpin the word under the cursor (toggle).
u Untags or unpins the word under the cursor.
INS Tags or pins the word under the cursor.
DEL Untags or unpins the word under the cursor.
c Tags or pins all the selectable words in the current column when no word is marked,
otherwise acts like C.
r Tags or pins all the selectable words in the current row/line when no word is
marked, otherwise acts like R.
m Marks the current word, the cursor aspect will change until the word is unmarked.
M or ESC
Unmarks the current word, other actions will also automatically unmark the word,
see below.
T If no word are marked and the result of a search is still displayed then tags all
words found in this search.
If no word has been searched and no word is marked, then the current word is
marked, just as if m has been used instead. Otherwise all words between the marked
word and the current word are tagged.
The marked word will no longer be marked after tagging is complete.
Z Like T when not in search mode and when the marked words is not on the same column
or line as the cursor in column mode.
When in column mode and if the marked word is in the same column or line as the
cursor, tags only the words in the same column (respectively line) bounded by the
marked word and the cursor.
C As for T, C marks the current word if no word is currently marked, just as if m had
been used instead.
If a word is already marked, C tags/pins the words between the current and the
marked words if they are the same column.
The marked word will no longer be marked after tagging is complete.
R As for T, R marks the current word if no word is currently marked, just as if m has
been used instead.
If a word is already marked, R tags/pins the words between the current and the
marked words if they are the same row/line.
The marked word will no longer be marked after tagging is complete.
Note that when you use T, C or R with pinning enabled, the order of word selection depends
on whether the marked word is before or after the current word.
When a word is marked, the pinning order using c and r increases from the marked word to
the current word.
When no words are marked, the pinning order when using c and r always increases from top
to bottom and from left to right respectively.
U Untags or unpins the last tagging action.
CTRL T Untags all the previously tagged/pinned words.
The marked word, if any, will no longer be marked after this action.
Help
A small help message can be displayed when hitting the ? key. This message will last for
10s or until another key or ESC is pressed.
Scroll bar
A scroll bar is displayed at the right of the scrolling window. Its appearance is meant
to be classical but it has some particularities:
• The scroll bar is not displayed if all the input words fit on only one line.
• Otherwise, the scroll bar is always displayed except when the -q option is set. This
option completely disables the scroll bar display.
• When the scrolling window has only one line, the scroll bar has only 3 states:
- v when on all but the last line, indicating that you can go down to see more.
- ^ when on the last line.
- | otherwise.
• When there is more than one line to display, / means that the window displays the first
line, \ the last line. | is used to fill the gap, see below the different possible
configurations.
\ \ ^ ^ \
| | | | /
/ v / v
A + can also appear in the scroll bar in lieu of the vertical bar, giving the relative
position of the cursor line in the bunch of input words.
Terminal resizing (also see BUGS/LIMITATIONS)
The windows is redrawn if the terminal is resized. The redrawing is actually done only 1s
after the end of the resizing to avoid artifacts on screen. The cursor will remain on the
current selected word but may be displayed at another place in the window.
Unicode support
This utility is Unicode aware and should be able to display correctly any Unicode
character (even double-width ones) as long as the current encoding is UTF-8 (UTF-8 in the
output of the locale command).
Note that smenu will not attempt to normalize words containing UTF-8 glyphs. Thus
\u61\ucc88 (ä) will not be considered equal to \uc3a4 (canonical normalization of ä). It
is nevertheless possible to use an external tool such as uconv from the ICU project
(https://icu.unicode.org) to do this work before using smenu.
For example: uconv can be used as a filter as in:
cat ... | uconv -x any-nfc | smenu
Configuration
If a file with adequate permissions and the same name as the executable but prefixed with
a dot is present in the current directory or in the user's home directory, then it will be
parsed as a .ini file. The values read from the file in the home directory will be
overridden by the ones read from the local directory (if it is present).
Missing and bad keywords are silently skipped.
The values read, if valid, override the default hard-coded ones.
If a value is invalid an error message is shown and the program terminates.
The values of the timers must be given in units of 1/10 of a second.
Here is an example giving the syntax and the names of the keywords allowed:
--8<------------------------------------------------------------------
[colors]
; The terminal must have at least 8 colors and/or have attributes
: like bold and reverse for this to be useful
; if not the following settings will be ignored.
method=ansi ; classic | ansi (default)
cursor=0/2 ; cursor attributes
cursor_on_tag=0/2,u ; cursor on tag attributes
shift=6,b ; shift symbol attributes
message=0/3 ; message (title) attributes
bar = 7/4,b ; scroll bar attributes
search_field = 0/6 ; search field attributes
search_text = 7,bu ; search text attributes
match_field = 1,b ; matching words field attributes
match_text = 7,bu ; matching words text attributes
search_err_field = 1 ; approximate search field attributes
search_err_text = 1,r ; approximate search text attributes
; match_err_field = 3 ; approximate matching words field attributes
match_err_text = 1 ; approximate matching words text attributes
; include = b ; selectable color attributes
exclude = 4/0,u ; non-selectable color attributes
tag = 0/5 ; tagged (selected) attributes
daccess = 3,b ; direct access tag attributes
special1 = 7/4,b ; attributes for the special level 1
special2 = bu ; attributes for the special level 2
special3 = /3,b ; attributes for the special level 3
special4 = 7/4 ; attributes for the special level 4
special5 = 7/2,b ; attributes for the special level 5
special9 = 2,rb ; attributes for the special level 9
[window]
lines = 7 ; default number of lines of the window
[limits]
word_length = 1024 ; arbitrary max length of input words (int)
words = 32767 ; arbitrary max number of allowed input
; words (int)
columns = 128 ; arbitrary max number of columns (int)
[timers]
search = 100 ; search timeout in 1/10 s
help = 150 ; duration of the help message in 1/10 s
window = 7 ; delay before redrawing if the size of the
; terminal's window change in 1/10 s
direct_access = 6 ; duration allowed to add a new digit to
; the direct word access number in 1/10 s
forgotten = 9000 ; An explicit delay (in 1/10 s) before smenu
; is forced to stop as if "q" had been pressed.
; Useful when one forgot to make a selection.
[misc]
default_search_method = substring
[mouse]
double_click_delay= 200 ; delay in milliseconds
--8<------------------------------------------------------------------
• The method keyword can take the two possible values displayed above and determines if
you want to use the native method (limited to 8 colors) of the ansi method (ISO 8613-6)
if your terminal supports more than 8 colors.
The default value corresponds to ansi.
The attributes syntax is [fg][/bg][,toggles] where fg and bg are numbers representing
the foreground and background color and toggles is a strings which can contain the
characters b, d, r, s, u, i, n and l representing respectively bold, dim, reverse,
standout, underline, italic, invisible and blink.
• Spaces are allowed anywhere in the lines and between them, even around the =.
• Everything following a ; is ignored.
• When undefined, the default limits are:
words 32767
word_length 512
columns 256
OPTIONS
Not all options may be available, depending on the current context.
When smenu is called and before the first option is evaluated, it is in the Main context.
Each option can switch to another context in which only a subset of the options is usable.
For each parameter described below, the contexts in which the associated option is defined
as well as the context to which it leads, if any, are given.
An option not defined in a context will force the end of the current context and will be
recursively evaluated in the previous contexts until found (or not). If not found, an
error message is displayed and smenu is terminated.
The contexts defined in smenu are:
Main
The default context
Columns
After the -c|-col|-col_mode|-column parameter.
Lines
After the -l|-line|-line_mode parameter.
Tabulations
After the -t|-tab|-tab_mode|-tabulate_mode parameter.
Tagging
After the -T|-tm|-tag|-tag_mode or -P|-pm|-pin|-pin_mode parameter.
WARNING
Here is a situation that may seem confusing at first glance.
Imagine the only parameter command line parameter is -cols_select.
Since this is a parameter of an option which is not valid when not in the Columns
context, it should have raised an error but it still seems to be accepted.
The trick is: when not in column mode -cols_select is indeed not accepted but its prefix
(-col) is valid. The options are thus understood as: -col -s_select. The same
mechanism occurs again as -s is also valid in column mode so the final understanding of
the command line is: -col -s _select.
Another example that illustrates the fact that long parameters have priority over short
parameter combinations: -is will not select only words containing a "s", but will act in
the same way as its alternative name (-incremental_search).
If you really want to select only words containing a "s", simply add a space after the i
as in -i s or use one of the other -i names such as -inc for example.
In such cases, the user may set the CTXOPT_DEBUG environment variable which any non-
empty content.
If we reconsider the -cols_select example with CTXOPT_DEBUG set the output is now:
CTXOPT_DEBUG: Parameter: -cols_select. Evaluation context: Main.
CTXOPT_DEBUG: Found a valid parameter as a prefix of -cols_select: -col.
CTXOPT_DEBUG: Parameter: -col. Evaluation context: Main.
CTXOPT_DEBUG: Switch to context Columns.
CTXOPT_DEBUG: Parameter: -s_select. Evaluation context: Columns.
CTXOPT_DEBUG: Found a valid parameter as a prefix of -s_select: -s.
CTXOPT_DEBUG: Parameter: -s. Evaluation context: Columns.
CTXOPT_DEBUG: Argument: _select.
In this case, adding a space in the command line: -col -cols_select 1 also solves the
issue and indicates that only the first column should be selectable.
Note, however, that at least one argument for -cols_select is now required:
CTXOPT_DEBUG: Parameter: -col. Evaluation context: Main.
CTXOPT_DEBUG: Switch to context Columns.
CTXOPT_DEBUG: Parameter: -cols_select. Evaluation context: Columns.
CTXOPT_DEBUG: Argument: 1.
The -h|-help and -?|-u|-usage options now display the help and synopsis of the available
options in the current context.
Example:
smenu -col -u will only show the usage in the Columns context
The contexts contain all the non-context-changing options so, in practice, the usage
should be intuitive. You may nevertheless have to adjust some scripts using the old smenu
releases as I did in the lvm_menu example.
Some of the advantages of this new system of options are:
• Long parameter names are allowed One dash is enough, but two are also allowed for
compatibility reasons.
• An option can be referenced by any number of parameters with short or long names.
• Auto checking of missing mandatory options, duplicated option,...
• Only options usable in the current context are allowed.
This option management system is explained in more detail at https://github.com/p-
gen/ctxopt.
The description of each command line parameter is as follows:
-h|-help
(Allowed in all contexts.)
Display a context specific help messages and exits.
-H|-long_help
(Allowed in the "Main" context.)
Display a long (non context specific) help messages and exits.
-?|-u|-usage
(Allowed in all contexts.)
Displays a short help message and exits.
-V|-version
(Allowed in the "Main" context.)
The .smenu files in the user's home directory and in the current directory, if
present, will be ignored when this option is used.
-n|-lines|-height [height]
(Allowed in all contexts.)
Gives the maximum number of lines in the scrolling selection window.
If -n|-lines|-height is not present the number of lines will be set to 5.
If -n|-lines|-height is present without argument, then the height of the terminal
will be used to determine the number of lines. This remains true even if the
terminal is resized.
If -n|-lines|-height is present with a numerical argument, this value will be used
to determine the number of lines.
-i|-in|-inc|-incl|-include... regex
(Allowed in all contexts.)
Sets the include filter to match the selectable words. All the other words will
become implicitly non-selectable (excluded)
-i|-in|-inc|-incl|-include can be used more than once with cumulative effect.
\u and \U sequences can also be used in the regexp.
-e|-ex|-exc|-excl|-exclude... regex
(Allowed in all contexts.)
Sets the exclude filter to match the non-selectable words. All the other
selectable words will become implicitly selectable (included)
-e|-ex|-exc|-excl|-exclude can be used more than once with cumulative effect. This
filter has a higher priority than the include filter.
The regex selections made using -i|-in|-inc|-incl|-include and/or
-e|-ex|-exc|-excl|-exclude are done before the possible words alterations made by
-I|-si|-subst_included or -E|-se|-subst_excluded (see below).
\u and \U sequences can also be used in the regexp.
-m|-msg|-message|-title message
(Allowed in all contexts.)
Displays a message (title) above the window. If the current locale is not UTF-8,
then all UTF-8 characters will be replaced by the substitution character.
\u and \U sequences can be used in the message.
Note that the message will be truncated if it does not fit on a terminal line.
-!|-int|-int_string [string]
(Allowed in all contexts.)
The optional string argument, when present, defines the string to be used as the
selection string when the CTRL C sequence is entered.
If string is missing then nothing will be selected.
In all cases, when -!|-int|-int_string is present in the command line, the return
code of the program will be 0.
This gives the user the choice to make the behavior of CTRL C similar to that of q
and Q or to that of the Unix shell leaving the shell with a return code greater
than 128.
-a|-attr|-attributes prefix:attr...
(Allowed in all contexts.)
Sets the display attributes of the elements displayed and the cursor.
At least one attribute prefixed attribute must be given.
prefix can take the following values:
i included words.
e excluded words.
c cursor.
b scroll bar.
s shift indicator.
m message (title).
t tagged words.
ct cursor on tagged words.
sf search field.
st search text.
sfe approximate search field with error.
ste approximate search text with error.
mf matching words field.
mt matching words text.
mfe matching words field with error.
mte matching words text with error.
da direct access tag.
If more than one attribute is given, they must be separated by spaces.
Example: -attr i:/5 e:4,br b:7/3,rb c:7/2,b
See the the -1|-l1|-level1 option below for the description of the attributes
syntax after the colon and an example.
-1|-l1|-level1 regex [attr]
-2|-l2|-level2 regex [attr]
-3|-l3|-level3 regex [attr]
-4|-l4|-level4 regex [attr]
-5|-l5|-level5 regex [attr]
-6|-l6|-level6 regex [attr]
-7|-l7|-level7 regex [attr]
-8|-l8|-level8 regex [attr]
-9|-l9|-level9 regex [attr]
(Allowed in all contexts.)
Allows one to give a special display color to up to 5 classes of words specified by
regular expressions. They are called special levels. Only selectable words will
be considered.
By default, the first 5 special levels have their foreground color set to red,
green, brown/yellow, purple and cyan and the remaining 4 levels are set to white.
All these colors also can be set or modified permanently in the configuration
files. See the example file above for an example.
The optional second argument (attr) can be used to override the default or
configured attributes of each class. Its syntax is the same as the one used in the
configuration file:
[fg][/bg][,{b|d|r|s|u|i|n|l}] | [{b|d|r|s|u|i|n|l}]
Examples of possible attributes are:
2/0,bu green on black bold underline
/2 green background
5 text in purple
rb reverse bold
\u and \U sequences can be used in the pattern.
-z|-zap|-zap_glyphs bytes
(Allowed in all contexts.)
Initializes a set of UTF-8 characters to be ignored when reading words from stdin
or a file.
Example: The argument '\u0d\ue282ac,' means: ignore all commas, Euro signs and
carriage return characters when reading from stdin or a file.
As shown above \u and \U sequences can be used in the bytes set.
-T|-tm|-tag|-tag_mode [delim]
(Allowed in the following contexts: "Main", "Columns", "Lines", and "Tabulations",
switches to the "Tagging" context.)
Allows multiple selections and switches to tag mode. In this mode, several
selectable words can be selected without leaving the program.
Tagged words are highlighted (underlined by default).
The current word can be automatically tagged when the ENTER key is pressed to
complete the selection process if the -p|-at|-auto_tag option is also set or if no
word has been tagged.
Note that nothing is selected when no word is tagged and when the
-0|-noat|-no_auto_tag option is also set.
All tagged words (and possibly the world under the cursor) will be sent to the
standard output separated by the optional argument given after the option
-T|-tm|-tag|-tag_mode.
Note that the delim argument can contain more than one character, can contain UTF-8
characters (in native or \u or \U form) and can even contain control character as
in $'\n'.
A single space character is used as the default separator if none is given.
Caution: To get exactly the same behavior as in version 0.9.11 and earlier, you
must also use the -p|-at|-auto_tag option.
-P|-pm|-pin|-pin_mode [delim]
(Allowed in the following contexts: "Main", "Columns", "Lines", and "Tabulations",
switches to the "Tagging" context.)
Works like -T|-tm|-tag|-tag_mode but, unlike -T|-tm|-tag|-tag_mode, the output
depends on the order in which the words were tagged. In other words, the first
tagged word comes first in the output, the second tagged word comes next, and so
on.
-p|-at|-auto_tag
(Allowed in the "Tagging" context.)
This option modifies the default behavior of the -T|-tm|-tag|-tag_mode and
-P|-pm|-pin|-pin_mode options.
An untagged word under the cursor will be automatically tagged when ENTER is
pressed.
-0|-noat|-no-auto_tag
(Allowed in the "Tagging" context.)
This option modifies the default behavior of the -T|-tm|-tag|-tag_mode and
-P|-pm|-pin|-pin_mode options.
An untagged word under the cursor will not be automatically tagged when ENTER is
pressed and no other words are tagged. This is true even when the option
-p|-at|-auto_tag is also set.
It is ignored if at least one other word is tagged at that time.
-N|-number>da_ctx... [regex]
(Allowed in the following contexts: "Main", "Columns", "Lines" and "Tabulation".)
This option allows you to number selectable words that match a specific regular
expression. These numbers are numbered from 1 and allow direct access to the
words.
To use this functionality, the user must enter the number which corresponds to the
desired entry digit per digit.
Each new digit must be added in a time frame of 1/2 seconds (per default) otherwise
the number is considered complete and a newly entered digit will start a new
number. If the number does not exists, then the cursor is restored to it's initial
position.
The sub-options of the -D|-data|-options option described below can change the way
-N|-number sets and formats the numbers.
This option accepts more than one argument and can be used multiple times with
cumulative effects.
-N|-number, -U|-unnumber and -F|-en|-embedded_number can be mixed.
-U|-unnumber>da_ctx... [regex]
(Allowed in the following contexts: "Main", "Columns", "Lines" and "Tabulation".)
This option allows one to unnumber words. If placed after a previous -N|-number,
it can be used to remove the numbering of selected words. If placed before, the
word which doesn't match its regular expression will be numbered by default.
This mechanism is similar to to the inclusion/exclusion of words by
-i|-in|-inc|-incl|-include and -e|-ex|-exc|-excl|-exclude.
This option accepts more than one argument and can be used multiple times with
cumulative effects.
-U|-unnumber, -N|-number and -F|-en|-embedded_number can be mixed.
-F|-en|-embedded_number
(Allowed in the following contexts: "Main", "Columns", "Lines" and "Tabulation".)
This option is similar to -N|-number but does not generate a continuous flow of
numbers but extracts them from the word itself.
With this option you can take full control of the numbering of the displayed word.
Note that the numbering does not need to be ordered.
The resulting word after the extraction of the number must be non empty.
Some sub-option are required, see the -D|-data|-options option described below.
Notice that for this option to work correctly, all the embedded numbers must have
the same number of digits. To get that, a preprocessing may be necessary on the
words before using this program.
-F|-en|-embedded_number, -N|-number and -U|-unnumber can be mixed.
-D|-data|-options [parameter...]
(Allowed in the Following contexts: "Main", "Columns", "Lines" and "Tabulations".)
This option allows one to change the default behavior of the -N|-number,
-U|-unnumber and -F|-en|-embedded_number options.
Its optional parameters are called sub-options and must respect the format x:y
where x can be:
l (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y is the UTF-8 character (in native or \u or \U form) to print before
the number. The default is a single space.
r (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y is the UTF-8 character (in native or \u or \U form) to print after
the number. The default is ).
a (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y is 'left' (or one of its prefixes) if the number must be left
aligned, or 'right' (or one of its prefixes) if it must be right aligned.
The default is right.
p (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y is 'included' or 'all' for the initial padding of the non numbered
words. The keyword 'included' means that only included word will be padded
while 'all' means pad all words.
The default is all. These keywords can be abbreviated.
w (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y is the width of the number between 1 and 5 included.
f (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y controls if the numbering must follow the last extracted number
(defaults to yes) or if it must remain independent.
The possible values are yes and no but can be abbreviated.
m (-F|-en|-embedded_number option)
Here y controls if the numbering of word with missing embedded numbers must
be done or not (defaults to yes).
When this sub-option is set to no, the s and f sub-options are ignored.
The possible values are yes and no but can be abbreviated.
h (-F|-en|-embedded_number option)
Tells what to do with the characters present before the embedded number if
any.
The allowed directives are: 'trim' which discards them if they form an empty
word (only made of spaces and tabulations), 'cut' which unconditionally
discards them and 'keep' which places them at the beginning of the resulting
word.
The default value for this directive is 'keep', these keywords can be
abbreviated.
o (-F|-en|-embedded_number option)
Here y is the offset of the first multibyte character of the number to
extract from the word (defaults to 0).
If this offset if immediately followed by the character '+', then the parser
will look for the first number (if any) after the given offset instead of
using its absolute value to extract the number.
Note that when the '+' is used, it is necessary that the length of all the
numbers to extract have the same size as the algorithm looks for a digit to
identify the beginning of the number to extract. Hence, for example, 1
should appear as 01 in the input is n is set to 2.
n (-F|-en|-embedded_number option)
Here y is the number of multibyte characters to extract from the word
starting at the offset given by the o sub-option.
Example: n:2 will extract and use the first 2 digits of each words from the
input stream to number them.
i (-F|-en|-embedded_number option)
Here y is number of multibyte characters to ignore after the extracted
number
d (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y is a multibyte separator. When present, this directive instructs
smenu to output the selected numbered word(s) prefixed by its(their) direct
access number(s) and the given separator.
Only the numbered word(s) will be prefixed.
d stands for decorate.
This directive can be useful when you want to post-process the output
according to its direct access number.
s (-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
Here y is the direct access number that will be set for the first numbered
word. Its value is 1 by default, a value of 0 is possible.
Example: -data r:\> l:\< a:l d:_
To number all words with the default parameters, use the syntax: "-N ." which is a
shortcut for: "-N . -D l:' ' r:')' a:r p:a"
The padding sub-option specifies whether spaces must also be added in front of
excluded words or not to improve compactness.
When the w sub-option is not given the width of the numbers is determined
automatically but if -F|-en|-embedded_number is set and the value of the n sub-
option is given then this value is used.
-b|-blank
(Allowed in all contexts.)
Replaces all non-printable characters by a blank. If this results in a blank word,
it will be potentially deleted.
-.|-dot|-invalid
(Allowed in all contexts.)
Sets the substitution character for non-printable characters. When this parameter
is not used, the default substitution character is a single dot.
-M|-middle|-center
(Allowed in all contexts.)
Centers the display if possible.
-d|-restore|-delete|-clean|-delete_window|-clean_window
(Allowed in all contexts.)
Tells the program to clean up the display before quitting by removing the selection
window after use as if it was never displayed.
-c|-col|-col_mode|-column
(Allowed in the "Main" and "Tagging" contexts, switches to the "Columns" context.)
Sets the column mode. In this mode the lines of words do not wrap when the right
border of the terminal is reached but only when a special character is read. Some
words will not be displayed without an horizontal scrolling.
If such a scrolling is needed, some indications may appear on the left and right
edge of the window to help the user to reach the unseen words.
In this mode, the width of each column is minimal to keep the maximum information
visible on the terminal.
-l|-line|-line_mode
(Allowed in the "Main" and "Tagging" contexts, switches to the "Lines" context.)
Sets the line mode. This mode is the same as column mode but without any column
alignment.
-t|-tab|-tab_mode|-tabulate_mode [cols]
(Allowed in the "Main" and "Tagging" contexts, switches to the "Tabulations"
context.)
This option sets the tabulation mode and, if a number is specified, attempts to set
the number of displayed columns to that number.
In this mode, embedded line separators are ignored if not explicitly set with
-L|-ls|-ld|-line-delimiters|-line_separators. The options -A|-fc|-first_column and
-Z|-lc|-last_column can nevertheless be used to force words to appear in the first
(respectively last) position of the displayed line.
Note that the number of requested columns will be automatically reduced if a word
does not fit in the calculated column size.
In this mode each column has the same width.
-w|-wide|-wide_mode
(Allowed in the "Columns" and "Tabulations" contexts.)
When -t|-tab|-tab_mode|-tabulate_mode is followed by a number of columns, the
default is to compact the columns so that they use the less terminal width as
possible. This option enlarges the columns in order to use the whole terminal
width.
When in column mode, -w|-wide|-wide_mode can be used to force all the columns to
have the same size (the largest one). See option -c|-col|-col_mode|-column below.
Note that the column's size is only calculated once when the words are displayed
for the first time. A terminal resize will not update this value. This choice
enables a faster display.
-C|-cs|-cols|-cols_select... [i|e]selectors...
(Allowed in the "Columns" context.)
I and E have the same meaning as i and e.
In column mode, this option is useful to restrict the selections to a subset of all
columns. Either by including (nothing or i) or by excluding (e) them.
Columns can be designated by their number (1 based) or by a regular expression
enclosed in delimiter made from any non-blank ASCII character excluding the comma.
Range of columns (number or RE) can be given by separated then with a dash.
Multiple selectors can be regrouped in one argument using commas to separate them.
This option also accepts multiple arguments, each of them being a selector.
A selection by regular expressions means that a column containing a word matching
any of these expressions will be included or excluded depending on the letter given
after the option or before the selector if there is more than one argument.
Regular expressions and column numbers can be freely mixed.
Regular expression in -C|-cs|-cols|-cols_select and -R|-rs|-rows|-rows_select can
contain UTF-8 characters either directly or by using the \u or \U notation.
Example of columns selection: -Ci2,3,/X./,5-7 forces the cursor to only navigate in
columns 2,3,5,6 and 7 and those containing a two characters word starting with 'X'.
If e was used in place of i, all the columns would have been selected except the
columns 2,3,5,6,7 and those matching the extended regular expression 'X.'.
Spaces are allowed in the selection string if they are protected.
Other example where multiple selectors are used as multiple arguments: ps | smenu
-col -cols e/TTY/ e/CMD/ e3
-R|-rs|-rows|-rows_select... selectors...
(Allowed in the "Columns" and "Lines" contexts.)
Similar to -C|-cs|-cols|-cols_select but for the rows.
-C|-cs|-cols|-cols_select and -R|-rs|-rows|-rows_select can be used more than once
in a cumulative manner:
The selection mode (selection or de-selection) is given by the first occurrence of
the options, the other occurrences will only update the selected or de-selected
ranges.
Once a column or a row has been excluded, it cannot be re-included.
-A|-fc|-first_column regex
(Allowed in the following contexts: "Columns", "Lines" and "Tabulations".)
In column mode, forces all words matching the given regular expression to be the
first one in the displayed line. If you want to only rely on this method to build
the lines, just specify an empty regex to set the end-of-line separator with
-L|-ls|-ld|-line-delimiters|-line_separators '')
\u and \U sequences can also be used in the regexp after -A|-fc|-first_column.
-Z|-lc|-last_column regex
(Allowed in the following contexts: "Columns", "Lines" and "Tabulations".)
Similar to -A|-fc|-first_column but forces the word to be the latest of its line.
The same trick with -L|-ls|-ld|-line-delimiters|-line_separators can also be used.
\u and \U sequences can also be used in the regexp after -Z|-lc|-last_column.
-g|-gutter [string]
(Allowed in the "Columns" and "Tabulations" contexts.)
Replaces the blank after each words in column or tabular mode by a column
separator.
This separator is extracted from the string argument and each of its (multibyte)
character is used one after the other to fill the gutter.
If there are more columns that gutter characters then the last character is used
for the remaining columns.
When not given, the separator defaults to a vertical bar | (or a full height
vertical bar if the locale is set to UTF-8).
Each character can be given in normal or \u or \U form in the string argument.
Example: "|- " will allow one to separate the first two columns with '|', then '-'
will be used and ' ' will separate the remaining columns if any.
-k|-ks|-keep_spaces
(Allowed in all contexts.)
By default, the spaces surrounding the output string will be deleted. This option
forces them to be retained.
-W|-ws|-wd|-word_delimiters|-word_separators bytes
(Allowed in all contexts.)
This option can be used to specify the characters (or multibyte sequences) which
will be used to delimit the input words.
Multibyte sequences (UTF-8) can be natives of using the same ASCII representation
used in words (a leading \u or \U following by up to 8 hexadecimal characters for
the former and 6 hexadecimal characters for the latter).
Non-printable characters in arguments should be given using the standard $''
representation. $'\t' stands for the tabulation character for example.
The default delimiters are: SPACE, $'\t' and $'\n'.
-L|-ls|-ld|-line-delimiters|-line_separators bytes
(Allowed in all contexts.)
This option can be used to specify the characters (or multibyte sequences) which
will be used to delimit the lines in the input stream.
Multibyte sequences (UTF-8) can be natives of using the same ASCII representation
used in words (a leading \u or \U following by up to 8 hexadecimal characters for
the former and 6 hexadecimal characters for the latter).
Non-printable characters in arguments should be given using the standard $''
representation. $'\n' stands for the newline character for example.
The default delimiter is: $'\n'.
This option is only useful when the -c|-col|-col_mode|-column or -l option is also
set.
The characters (or multibyte sequences) passed to -L|-ls|-ld|-line-
delimiters|-line_separators are automatically added to the list of word delimiters
as if -W|-ws|-wd|-word_delimiters|-word_separators was also used.
\u and \U sequences can also be used here.
-q|-no_bar|-no-scroll_bar
(Allowed in all contexts.)
Prevents the display of the scroll bar.
-S|-subst... /regex/repl/[g][v][s]
(Allowed in all contexts.)
Post-processes the words by applying a regular expression based substitution. The
argument must be formatted as in the sed editor.
As in sed, matching groups and references to these groups (from \0 to \9 in repl)
are supported. These groups must be surrounded by ( and ) in regex. \0 and & are
equivalent in repl as in the GNU version of sed.
Back reference example:
R=$(echo "[A] [B] [C]" | ./smenu -S '/([^][]+)/:\1:/')
will display "[:A:] [:B:] [:C:]"
This option can be used more than once. Each substitution will be applied in
sequence on each word. This sequence can be stopped if a stop flag is encountered.
flags:
• The optional trailing g (for global) means that all matching occurrences shall be
replaced and not only the first one.
• The optional trailing v (for visual) means that the altered words will only be
used for display and search. The modifications will not be reflected in the
returned word.
• The optional trailing s (for stop) means that no more substitution will be
allowed on this word even if another -S|-subst is used.
• The optional trailing i (for ignore case) means that the string search operation
should ignore the case for this pattern.
Small examples to explain the meaning of v:
R=$(echo a b c | smenu -S /b/B/)
will display "a B c" and R will contain B when B is selected meanwhile
R=$(echo a b c | smenu -S /b/B/v)
will display the same as above but R will contain the original word b when B is
selected.
In both cases, only the word B will be searchable and not b.
-I|-si|-subst_included... /regex/repl/[g][v][s]
(Allowed in all contexts.)
Post-processes the selectable words by applying a regular expression based
substitution (see -S|-subst for details).
-E|-se|-subst_excluded... /regex/repl/[g][v][s]
(Allowed in all contexts.)
Post-processes the excluded (or non-selectable) words by applying a regular
expression based substitution (see -S|-subst for details).
The / separator that -I|-si|-subst_included and -E|-se|-subst_excluded are using
above can be substituted by any other character except SPACE, \t, \f, \n, \r and
\v.
In the three previous options, regex is a POSIX Extended Regular Expression. For
details, please refer to the regex(7) manual page.
Additionally \u and \U sequences can also be used in the regexp.
If a post-processing action (-S|-subst, -I|-si|-subst_included, -E|-se|-subst_excluded)
results in an empty (length = 0) word, then we have two cases:
in column mode:
Substitutions involving empty words can lead to misalignments, so it is
necessary to prohibit them and terminate the program. These substitutions
have to be made with other tools before using this utility.
otherwise:
The word is simply removed.
-ES|-subst... /regex/repl/[g][v][s]
(Allowed in all contexts.)
Pre-processes words by applying a substitution based on a regular expression. The
argument must be formatted as in the sed editor.
The substitutions are made, as the name of the option indicates, before any other
selection or coloring actions are made.
This option can be used more than once. Each substitution will be applied in
sequence on each word. This sequence can be stopped if a stop flag is encountered.
In summary, this option is similar to the -S|-subst option previously described,
except that the substitutions are made earlier and certain flags like visual are
ignored.
Note that this option can be used in conjunction with the other substitution
options mentioned above.
-/|-search_method search_method
(Allowed in all contexts.)
Affects the '/' key to a search method. By default '/' is affected to 'fuzzy' but
the argument can be any prefix of 'prefix', 'substring' or 'fuzzy'.
-s|-sp|-start|-start_pattern pattern
(Allowed in all contexts.)
Place the cursor on the first word corresponding to the specified pattern.
pattern can be:
• A # immediately followed by a number giving the initial position of the cursor
(counting from 0).
If the word at this position is excluded, then the first previous non excluded
word is selected if it exists, otherwise the first non excluded word is selected.
If this number if greater than the number of words, the cursor will be placed on
the latest selectable position.
• A single # or the string #last to set the initial cursor position on the latest
selectable word position.
• A string starting with a / indicating that we want the cursor to be placed on the
first word matching the given regular expression.
• A string starting with a = indicating than we want the cursor to be placed on
that exact word.
• A normal string. In this case the cursor will be placed on the first word
starting with that string (Ca will match Cancel by example).
Warning, when searching for a prefix or a regular expression, smenu only looks for
them after an eventual modification, so for example, the command: smenu -I/c/x/
-s/c <<< "a b c d" won't find c and put the cursor on a but smenu -I/c/x/v -s/c <<<
"a b c d" will find it and put the cursor on the x substituting the c on screen
only
\u and \U sequences can be used in the pattern.
-x|-tmout|-timeout type [word] delay
-X|-htmout|-hidden_timeout type [word] delay
(Allowed in all contexts.)
Sets a timeout. Three types of timeout are possible:
current: At the timeout, the word under the cursor and/or the tagged words are
sent to the standard output if the ENTER key has been pressed
quit: At the timeout, nothing is selected as if the q key has been pressed
word: At the timeout, the word given after the type is selected. Note that
this word doesn't need to be part of the words coming from the standard
input.
Each type can be be shortened as a prefix of its full name ("cur" for "current" of
"q" for "quit" per example).
The delay must be set in seconds and cannot be greater than 99999 seconds.
The remaining time (in seconds) is added at the end of the message displayed above
the selection window and is updated in real time each second.
Any key except ENTER, q, Q and CTRL C resets the timer to its initial value.
The -X|-htmout|-hidden_timeout version works like -x|-tmout|-timeout but no
periodic remaining messages is displayed above the selection window.
-r|-auto_validate
(Allowed in all contexts.)
Enables ENTER to validate the selection even in search mode.
-is|-incremental_search
(Allowed in all contexts.)
By default, when a new search session is initiated, the current search buffer is
reset. When this parameter is set, the next search will start where the last
search ended, except if ESC was hit before.
This option instructs not to clean the previous search buffer each time a new
search session is started.
-v|-vb|-visual_bell
(Allowed in all contexts.)
By default, when searching, an alarm is produced by the terminal when the user
enters a character or makes a move which lead to no result or to an error
condition. This argument make this beep visual by briefly showing the cursor.
-Q|-ignore_quotes
(Allowed in all contexts.)
Using this option will remove the word grouping feature from single and double
quotes which will be considered normal characters. For example: "a b" will be
considered by smenu as two words "a and b" and no more as a single word: a b.
-lim|-limits limit:value...
(Allowed in all contexts.)
This option gives the possibility to modify the default maximum number of words or
columns and the maximum permitted word length.
The specified values overload the default settings and/or the settings given in the
configuration files.
In order to do that, three sub-options can be used:
l:value
to set the maximum word length allowed.
w:value
to set the maximum number of words allowed.
c:value
to set the maximum number of columns allowed.
Several sub-options, separated by spaces, can be given after this option.
[-f|-forgotten_timeout|-global_timeout timeout]
(Allowed in all contexts.)
This option defines a global timeout in seconds. The program will end without
error after this period of inactivity.
This timer is reset to its initial value each time a key is pressed.
Its default value is "unlimited", but it can be changed by assigning a number (in
tenths of seconds) to the "forgotten" entry in the [timers] section of the optional
configuration file. See the example in the configuration sub-section.
A value of 0 as an argument disables this timer and replaces the default value.
[-nm|-no_mouse]
(Allowed in all contexts.)
This option allows you to disable the mouse even if smenu can use it.
[-br|-buttons|-button_remapping new_button_1 new_button_3]
(Allowed in all contexts.)
This option allows one to remap the mouse buttons. The buttons are numbered from 1
to 3 but as smenu only uses buttons 1 and 3, only two arguments are required.
By example, the syntax -br 3 1 will reverse the first (left) and third (right?)
buttons.
The default mapping is 1 3.
[-dc|-dcd|-double_click|-double_click_delay delay_in_ms]
(Allowed in all contexts.)
This option allows one to set the double-click delay in the range of 100 ms (1/10
second) to 500 ms (1/2 second). The default delay of 150 ms (1/6.66 second) will
be used if the given value is out of range or invalid.
The double-click capability can also be disabled by setting delay_in_ms to 0.
This setting is also configurable in a configuration file, see the [mouse] section
in the example in the configuration sub-section.
NOTES
If tabulators (\t) are embedded in the input, there is no way to replace them with the
original number of spaces. In this case use another filter (like expand) to pre-process
the data.
EXAMPLES
1
Simple Yes/No/Cancel request with "No" as default choice:
In bash:
read R <<< $(echo "Yes No Cancel" \
| smenu -d -m "Please choose:" -s /N)
or
R=$(echo "Yes No Cancel" \
| smenu -d -m "Please choose:" -s /N)
In ksh:
print "Yes No Cancel" \
| smenu -d -m "Please choose:" -s /N \
| read R
2
Get a 3 columns report about VM statistics for the current process in bash/ksh on Linux:
R=$(grep Vm /proc/$$/status | expand | smenu -b -W$'\n' -t3 -g -d)
3
Create a one column selection window containing the list of the first 20 LVM physical
volumes. At the end, the selection window will be erased. This example is written in
ksh).
pvs -a -o pv_name --noheadings \
| smenu -m "PV list" -n20 -t1 -d -s //dev/root \
| read R
The display will have a look similar to the following with the cursor set on the word
/dev/root:
PV list
/dev/md126 \
/dev/md127 |
/dev/root | <- cursor here.
/dev/sda2 |
/dev/sdb2 |
/dev/sdc1 |
/dev/sdc2 |
/dev/system/homevol /
4 (advanced)
Imagine a file named sample.mnu with the following content:
--8<---------------------------------
"1 First Entry" "3 Third entry"
"2 Second entry" "4 Fourth entry"
@@@ "5 Fifth entry"
@@@
"0 Exit menu"
--8<---------------------------------
Then this quite esoteric command will render it (centered on the screen) as:
+----------------------------------+
| Test menu |
| |
| 1) First Entry 3) Third entry |
| 2) Second entry 4) Fourth entry |
| 5) Fifth entry |
| |
| 0) Exit menu |
+----------------------------------+
with the cursor on Quit and only the numbers and "Quit" selectable.
R=$(smenu -q -d -s/Exit -M -n 30 -c \
-e "@+" -E '/@+/ /' \
-F -D n:1 i:1 \
-m "Test menu" < sample.mnu)
The selected entry will be available in R
Try to understand it as an exercise.
ENVIRONMENT
NO_COLOR force a monochrome terminal when set.
CTXOPT_DEBUG put the option parser in debug mode.
BUGS/LIMITATIONS
Some terminal emulators, those notably based on VTE version later than 0.35 (see
https://github.com/GNOME/vte/commit/01380d), have a new feature that gives them the
possibility to wrap/unwrap already displayed lines when resizing the window.
As far as I known, there is no terminfo entry to disable that.
On these types of terminals, the automatic re-display of the output of smenu will be
disturbed and some artifacts may appear on the screen if the terminal window is resized.
AUTHORS
© 2015-present, Pierre Gentile (p.gen.progs@gmail.com)
smenu(1)