NAME

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]
  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.
  <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

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.

--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
--8<------------------------------------------------------------------

OPTIONS

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 behaviour 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:

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|l}] | [{b|d|r|s|u|i|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 behaviour 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:

-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.

-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.

-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 '')

-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.

-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.

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.

-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).

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:

-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:

-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:

-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:

[-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.

NOTES

EXAMPLES

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

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<---------------------------------

+----------------------------------+
|            Test menu             |
|                                  |
| 1) First Entry   3) Third entry  |
| 2) Second entry  4) Fourth entry |
|                  5) Fifth entry  |
|                                  |
| 0) Exit menu                     |
+----------------------------------+

ENVIRONMENT

BUGS/LIMITATIONS

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