smenu [-h|-?] [-f configuration_file] \
[-n lines] [-t [cols]] [-k] \
[-s pattern] [-m message] [-w] \
[-d] [-M] [-c] [-l] [-r] [-b] \
[-a (i|e|c|b|s|t|ct|sf|st|mf|mt|sfe|ste|mfe|mte|da):ATTR]... \
[-i regex] [-e regex] \
[-C [i|e]<col selectors>] \
[-R [i|e]<row selectors>] \
[-S /regex/string/[g][v][s][i]] \
[-I /regex/string/[g][v][s][i]] \
[-E /regex/string/[g][v][s][i]] \
[-A regex] [-Z regex] \
[-N [regex]] [-U [regex]] [-F] [-D sub-option...] \
[-1 regex [ATTR]] [-2 regex [ATTR]] ... [-5 regex [ATTR]] \
[-g [string]] [-q] [-W bytes] [-L bytes] \
[-T [separator]] [-P [separator]] [-p] \
[-V] [-x|-X type [word] delay] [-/ prefix|substring|fuzzy] \
[input_file]
<col selectors> ::= col1[-col2],...|<RE>,...
<row selectors> ::= col1[-col2],...|<RE>,...
<sub-option> ::= [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>
<col/row selectors> and <RE> can be freely mixed.
The parameters of -a and -D must be delimited by blanks.
All read words are presented in a scrolling window on the terminal at the current cursor position without clearing the screen before.
The selection cursor is initially positioned on the first selectable word by default.
Options exists to explicitly or implicitly include or exclude some words by using extended regular expressions.
Notice that when some words are explicitly excluded they can no more be re-included after.
Excluded words are skipped when the selection cursor is moved and cannot be searched for.
The -W 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 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.
UTF-8 sequences introduced by \u are also understood. \u can be followed by 2,4,6 or 8 hexadecimal characters. An invalid UTF-8 sequence will be replaced by a dot (.), see also below.
Example: \uc3a9 means latin small letter e with acute.
Note that with most shells, the \ before the 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. A single dot (.) is also used as a placeholder otherwise.
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.
Warning, UTF-8 encoded codepoints are quietly converted into dots (.) when the user locale is not UTF-8 aware like POSIX or C by example.
| ←, h | Previous word |
| ↑, k | Previous line |
| PgUp, K | Previous pages |
| Home | First word of the window |
| CTRL+Home, SHIFT+Home, CTRL+k | First word |
| →, l | Next Word |
| ↓, j | Next line |
| PgDn, J | Next pages |
| End | Last word of the window |
| CTRL+End, SHIFT+End, CTRL+j | Last word |
If the -N, -U or -F are used then it is 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, -I or -E.
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 by example.
-E gives another way to do that, see below or more.
The case is also ignored.
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 approximatively 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.
By 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.
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.
The / key can also be used instead of any of these keys. By default is is programmed to do a fuzzy search but this can be altered by using the command line option (-/) 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.
Typically, 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.
ESC can be used anytime to abort the current search session. ENTER and all cursor moves also terminate the search session but do not clear the list of the matchng words.
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 behaviour is persistent until the user hit the ESC or ENTER key.
By 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.
In summary, here is the meaning of the special keys in search mode:
| Keys which clear the list of matching words. | ||
| Key | Meaning | Closes |
| the | ||
| search | ||
| session | ||
| Esc | Cancel search | Yes |
| Keys which keep or update the list of matching words. | ||
| Key | Meaning | Closes |
| the | ||
| search | ||
| session | ||
| ← | Previous word | Yes |
| ↑ | Previous line | Yes |
| PgUp | Previous page | Yes |
| CTRL+Home, SHIFT+Home, CTRL+k | First word | Yes |
| → | Next word | Yes |
| ↓ | Next line | Yes |
| PgDn | Next pages | Yes |
| CTRL+End, SHIFT+End, CTRL+j | Last word | Yes |
| Home,CTRL-A | Only keep the words starting with the search pattern | No |
| End,CTRL-Z | Only keep the words ending with the search pattern | No |
| Ins | Tag word | No |
| Del | Untag word | No |
Note that the search buffer is persistent as long as the same search algorithm is used and ESC has not been pressed.
By default, ENTER 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 option to change this behavior.
| \@\@^ | ^ | \ | Do not remove this trailing space! | |
| | | | | | | | | / |
| / | 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.
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
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
[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 = 60 ; search timers 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
[misc]
default_search_method = substring
--8<------------------------------------------------------------------
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 and i standing for bold, dim, reverse, standout, underline and italic.
| words | 32767 |
| word_length | 512 |
| columns | 256 |
The .smenu
The special value
In this mode each column has the same width.
pattern can be:
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 set on the latest selectable position.
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 sequences can be used in the pattern.
\u sequences can be used in the message.
Note that the message will be truncated if it does not fit on a terminal line.
When in column mode, -w can be used to force all the columns to have the same size (the largest one). See option -c below.
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.
At least one attribute prefixed attribute must be given.
PREFIX can take the following values:
If more than one attribute is given, then they must be separated by spaces.
See the -1 option for the ATTR syntax.
-i can be used more than once with cumulative effect.
\u sequences can also be used in the regexp.
-e 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 and/or -e are done before the possible words alterations made by -I or -E (see below).
\u sequences can also be used in the regexp.
These letters are case independent so I can be used in place of i per example.
In column mode, this option allows one to restrict the previous selections or de-selections to some columns. If no selection is given via -i and -e this option gives the possibility to select entire columns by giving their numbers (1 based) of extended regular expressions.
i or nothing select the specified ranges of columns. e select all but the specified ranges of columns.
The words in the selected columns will be considered as included And the others excluded.
A selection by regular expressions means that a column containing a word matching one of these expression will be included or excluded according to the letter given after the option.
Regular expressions and column numbers can be freely mixed.
Regular expression in -C and -R can contain UTF-8 characters either directly or by using the \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.
The column mode is forced when this option is selected.
One difference though: this is the line mode which is forced by this option NOT the column mode.
-C and -R 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.
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.
Small example: R=$(echo a b c | smenu -S /b/B/) will display "a B c" and R will contain B if 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 if B is selected. In both cases, only the word B will be searchable and not b.
In the three previous options, regex is a POSIX Extended Regular Expression. For details, please refer to the regex manual page.
Additionally \u sequences can also be used in the regexp.
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 option described below can change the way -N sets and formats the numbers.
This option can be used more than once with cumulative effects.
-N, -U and -F can be mixed.
This mechanism is similar to to the inclusion/exclusion of words by -i and -e.
This option can be used more than once with cumulative effects.
-U, -N and -F can be mixed.
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 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, -N and -U can be mixed.
Its optional parameters are called sub-options and must respect the format x:y where x can be:
The allowed directives are: 'trim' which discads them if they form an empty word (only made of spaces and tabulations), 'cut' which unconditionnaly discards them and 'keep' which places them at the beginning of the resulting word.
The default value for this directive is 'keep'.
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.
Example: r:\> l:\< a:l d:_
To number all words with the default parameters, use the syntax: "-N ." which is a shortcut for: "-N . 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 is set and the value of the n sub-option is given then this value is used.
By default, the 5 special levels have their foreground color set to red, green, brown/yellow, purple and cyan. 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}] | [{b|d|r|s|u|i}]
Examples of possible attributes are:
2/0,bu green on black bold underline /2 green background 5 text in purple rb reverse bold
\u sequences can be used in the pattern.
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 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.
Multibyte sequences (UTF-8) can be natives of using the same ASCII representation used in words (a leading \u following by up to 8 hexadecimal characters).
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'.
Multibyte sequences (UTF-8) can be natives of using the same ASCII representation used in words (a leading \u following by up to 8 hexadecimal characters).
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 or -l option is also set.
The characters (or multibyte sequences) passed to -L are automatically added to the list of word delimiters as if -W was also used.
\u sequences can also be used here.
The current word can be automatically tagged when the ENTER key is pressed to complete the selection process if the -p option is also set or if no word has been tagged.
All the tagged words (and possibly the world under the cursor) will be sent to stdout separated by the optional argument given after the option -T.
Note than this separator can have more than one character, contain UTF-8 characters (in native or \u form) and can even contain control character as in $'\n'.
A space 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 option.
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 above 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.
Each key press except ENTER, q, Q and ^C resets the timer to its initial value.
The -X version works like -x but no periodic remaining messages is displayed above the selection window.
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
R=$(grep Vm /proc/$$/status | expand | smenu -b -W$'\n' -t3 -g -d)
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 /
--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 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.
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.