Provided by: smenu_0.9.14-1_amd64 bug

NAME

       smenu  -  filter that allows one to interactively select a word from stdin and outputs the
       selection to stdout.

SYNOPSIS

       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.

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

   Moving among words
       The  cursor  can be moved in every direction by using the keyboard arrow keys (,,,) or
       the vi direction keys (h, j, k and l).  HOME, END, PgDn and PgUp  can  also  be  used,  if
       available, and have the following meanings:

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

   Searching for a word
       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  character in the entered sequence must appear in the same order in a word
              must not necessarily be consecutive.

              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     No
                                       starting with the search
                                       pattern
       End,CTRL-Z                      Only  keep   the   words     No
                                       ending  with  the search
                                       pattern

       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.

   Selection and Exit
       Pressing q gives the possibility to exit without selecting anything.

       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.

   Tagging (multi-selections)
       When  the tagging is activated by using the command line -T or -P option, then the keys t,
       T, INS and DEL can be used to tag/untag some words.   These  tagged  words  will  then  be
       output on the standard output when ENTER is pressed.

       t      Tag/untag or Pin/unpin the word under the cursor (toggle).

       T      Tag or pin the matching words if any.

       U      Untag or unpin the matching words if any.

       INS    Tag or pin the word under the cursor.

       DEL    Untag or unpin the word under the cursor.

   Help
       A  small  help message can be displayed when hitting ?.  This display will last for 10s or
       until a valid 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 artefacts 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).

   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
         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 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 and i  standing for bold, dim, reverse, standout, underline and
         italic.

       * 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

       -h or -?
              Displays a long (-h) or short (-?) help message and exits.

       -f configuration_file
              This  option gives the possibility to select an alternative configuration file.  If
              the given file doesn't exist or is not readable then the  default  values  will  be
              used.

              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
              Gives the maximum number of lines in the scrolling selection  window.   By  default
              five lines at most are displayed and the other ones, if any, need you to scroll the
              window.

              The special value 0 sets this number to match the number of lines in  the  terminal
              (minus  the  lines  taken  by  the  message if any).  This remains true even if the
              terminal is resized.

       -t [columns]
              This option sets the tabulation mode and, if a number is specified, attents to  set
              the  number  of  displayed  columns  to  that  number.  In this mode, embedded line
              separators are ignored.  The options -A and -Z 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.

       -k     By default, the spaces surrounding the output string will be deleted.  This  option
              forces them to be retained.

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

       -s pattern
              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 set on the
                latest selectable position.

              * A single # or the string #last to set the initial cursor position to  the  latest
                selectable word position.

              * A  string  starting  with a / indicating that we want the cursor to be set to the
                first word matching the given regular expression.

              * A prefix string indicating that we want the cursor to be set on  the  first  word
                matching the string given (a 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 sequences can be used in the pattern.

       -m message
              Displays  a message above the window.  If the current locale is not UTF-8, then all
              UTF-8 characters in it will be converted into a dot.

              \u sequences can be used in the message.

              Note that the message will be truncated if it does not fit on a terminal line.

       -w     When -t 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 can be used to force all the columns to have the same  size
              (the largest one).  See option -c 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.

       -d     Tells the program to clean up the display before quitting by removing the selection
              window after use as if it was never displayed.

       -M     Centers the display if possible.

       -c     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     Sets the line mode.  This mode is the same as column mode but  without  any  column
              alignment.

       -r     Enables ENTER to validate the selection even in search mode.

       -b     Replaces all non-printable characters by a blank.  If this results in a blank word,
              it will be potentially deleted.

       -a PREFIX:ATTR [PREFIX:ATTR...]
              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.

              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, then they must be separated by spaces.

       See the -1 option for the ATTR syntax.

       -i regex
              Sets the include filter to match the selectable words.  All the  other  words  will
              become implicitly non-selectable (excluded)

              -i can be used more than once with cumulative effect.

              \u sequences can also be used in the regexp.

       -e regex
              Sets  the  exclude  filter  to  match  the  non-selectable  words.   All  the other
              selectable words will become implicitly selectable (included)

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

       -C [i|e] <col selectors>

              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.

       -R [i|e] <row selectors>
              Similar to -C but for the rows.

              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.

       -S /regex/replacement string/[g][v][s]
              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.

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

              * The optional trailing i (for ignore case) means that the string search  operation
                should ignore the case for this pattern.

                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.

       -I /regex/replacement string/[g][v][s]
              Post-processes  the  selectable  words  by  applying  a  regular  expression  based
              substitution (see -S for details).

       -E /regex/replacement string/[g][v][s]
              Post-processes  the  excluded  (or  non-selectable)  words  by  applying  a regular
              expression based substitution (see -S for details).

              The / separator that -I and -E 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 manual page.

              Additionally \u sequences can also be used in the regexp.

       If a post-processing action (-S/-I/-E) 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.

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

              \u sequences can also be used in the regexp after -A.

       -Z regex
              Similar  to  -A  but  forces the word to be the latest of its line.  The same trick
              with -L can also be used.

              \u sequences can also be used in the regexp after -Z.

       -N [regex]
              This option allows one to number the selectable words matching a  specific  regular
              expression.   These  numbers  are  numbered  starting  from 1 and provides a 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 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.

       -U [regex]
              This  option  allows one to un-number words.  If placed after a previous -N, 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 and -e.

              This option can be used more than once with cumulative effects.

              -U, -N and -F can be mixed.

       -F     This option is similar to -N 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 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.

       -D [parameters]
              This  option  allows  one  to  change  the  default  behaviour of the -N, -U and -F
              options.

              Its optional parameters are called sub-options and  must  respect  the  format  x:y
              where x can be:

              l (-F, -N and -U options)
                     Here  y  is  the  UTF-8 character (in native or \u form) to print before the
                     number. The default is a single space.

              r (-F, -N and -U options)
                     Here y is the UTF-8 character (in native or \u  form)  to  print  after  the
                     number. The default is ).

              a (-F, -N and -U 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, -N and -U options)
                     Here  y  is  'included'  (or  one  of  its prefixes) or 'all' (or one of its
                     prefixes) for the initial padding of  the  non  numbered  words.  'included'
                     means  that  only  included  word  will  be padded while 'all' means pad all
                     words. The default is all.

              w (-F, -N and -U options)
                     Here y is the width of the number between 1 and 5 included.

              f (-F, -N and -U options)
                     Here y controls if the numbering  must  follow  the  last  extracted  number
                     (defaults to yes) or if it must remain independent.

              h (-F option)
                     Tells  what  to do with the characters present before the embedded number if
                     any.

                     The allowed directives are: 'trim' which discads 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'.

              o (-F option)
                     Here  y  is  the  offset  of  the first multibyte character of the number to
                     extract from the word (defaults to 0).

              n (-F option)
                     Here y is the number of  multibyte  characters  to  extract  from  the  word
                     starting at the offset given by the o sub-option.

              i (-F option)
                     Here  y  is  number  of  multibyte  characters to ignore after the extracted
                     number

              d (-F, -N and -U 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, -N and -U 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: 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.

       -1 ... -5 regex [ATTR]
              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 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.

       -g [string]
              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 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.

       -q     Prevents the display of the scroll bar.

       -W bytes
              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 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'.

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

       -T [separator]
              Enables the multi-selections or tag mode.  In this mode, several  selectable  words
              can be selected without leaving the program.

              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.

       -P [separator]
              Works like -T but, unlike -T, 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 stands for "Pin".

       -p     This option modifies the default behavior of the -T and -P  options.   An  untagged
              word under the cursor will be automatically tagged when ENTER is pressed.

       -V     Displays the current version and quits.

       -x type [word] delay
       -X type [word] delay
              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 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.

       -/ search_method
              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'.

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 R=$(./smenu -q -d -s/Exit -M -n 30 -c      \
                             -e "@+" -E '/@+/ /'            \
                             -F -D n:1 i:1                  \
                             -m "Test menu"$'0 < 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.

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 Pierre Gentile (p.gen.progs@gmail.com)