Provided by: smenu_0.9.15-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|si|m|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
       CTRL , H                       Start of line
       , k                            Previous line
       PgUp, K                         Previous page
       HOME                            First word of the window
       CTRL HOME, SHIFT HOME, CTRL K   First word

       , l                            Next word
       CTRL , L                       End of line
       , j                            Next line
       PgDn, J                         Next page
       END                             Last word of the window
       CTRL END, SHIFT END, CTRL J     Last word

       CTRL /H  (resp.  CTRL /L)  places  the cursor so that a maximum number of words (selectable or not) are
       visible to the left (reps. right) side of the window.

       If -N, -U or -F are used, then it becomes possible to directly access a word by entering its number.  The
       numbering created using these option is done before any words substitution done using -S, -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 words
       A word can be searched using different algorithms: prefix, substring of fuzzy.

       prefix (keys ^ or =):
              The sequence of characters entered must match the beginning of a word.

       substring (keys " or '):
              The sequence of characters entered must match a substring in a word.

       fuzzy (keys ~ or *):
              All  the  characters in the entered sequence must appear in the same order in a word, but need not
              be consecutive.

              The case is also ignored.

              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.

              For example: if the word abcdef is present in the  standard  input,  then  entering  abxcdye  puts
              abcdef in the search buffer and the word is added to the list of matching words and displayed with
              an error attribute (in red by default).

              This special state will persist until all the  symbols  following  the  first  erroneous  one  are
              deleted (using backspace) or if ESC is pressed.

       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 slash key (fB/) can also be used instead of any of these keys.  By default it is is programmed to  do
       a fuzzy search but this can be changed by using the command line option (-/) or by tuning a configuration
       file, see below.

       All the words matching the current search buffer are enhanced: The  characters  present  in  the  current
       search  buffer  are  highlighted  in  one  way  and  the  other characters in another way.  Both of these
       highlighting methods are configurable.

       If the user has entered the search sequence: o, s, then the matching word "words" will  be  displayed  as
       words when the fuzzy algorithm is in use depending of the display attributes configured.

       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.

       For  example,  if  the  search pattern in substring mode is sh and the user hits END, then only the words
       ending with sh will be added in the searched word list and enhanced.

       Note that when a matching word is selected, its  enhanced  characters  only  show  one  of  the  multiple
       matching possibilities.

       When  not  in  a search session ESC can be also used to clear the list of matching words and to reset the
       search buffer.

       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
       CTRL                           Start of line                Yes
       PgUp                            Previous page                Yes
       CTRL HOME, SHIFT HOME, CTRL K   First word                   Yes

                                      Next word                    Yes
                                      Next line                    Yes
       CTRL                           END of 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 (multiple 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
         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

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

              If -n is not present the number of lines will be set to 5.

              If -n 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  is  present  with a numerical argument, this value will be used to determine the number of
              lines.

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

              m      message (title).

              t      tagged words.

              ct     cursor on tagged words.

              sf     search field.

              st     search text.

              sfe    approximate search field with error.

              ste    approximate search text with error.

              mf     matching words field.

              mt     matching words text.

              mfe    matching words field with error.

              mte    matching words text with error.

              da     direct access tag.

       If more than one attribute is given, 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).

                     If this offset if immediately followed by the character '+', then the parser will look  for
                     the  first  number  (if  any) after the given offset instead of using its absolute value to
                     extract the number.

                     Note that when the '+' is used, it is necessary that the  length  of  all  the  numbers  to
                     extract  have the same size as the algorithm looks for a digit to identify the beginning of
                     the number to extract.  Hence, for example, 1 should appear as 01 in the input is n is  set
                     to 2.

              n (-F 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 multiple 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)