Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
smenu(1)		    General Commands Manual		      smenu(1)

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

SYNOPSIS
	 [*-h|-help]
	 [*-H|-long_help]
	 [*-?|-u|-usage]
	 [*-V|-version]
	 [-n|-lines|-height [height]]
	 [-i|-in|-inc|-incl|-include...	regex]
	 [-e|-ex|-exc|-excl|-exclude...	regex]
	 [-m|-msg|-message|-title message]
	 [-!|-int|-int_string [string]]
	 [-a|-attr|-attributes prefix:attr...]
	 [-1|-l1|-level1 regex [attr]]
	 [-2|-l2|-level2 regex [attr]]
	 [-3|-l3|-level3 regex [attr]]
	 [-4|-l4|-level4 regex [attr]]
	 [-5|-l5|-level5 regex [attr]]
	 [-6|-l6|-level6 regex [attr]]
	 [-7|-l7|-level7 regex [attr]]
	 [-8|-l8|-level8 regex [attr]]
	 [-9|-l9|-level9 regex [attr]]
	 [-T|-tm|-tag|-tag_mode	[delim]]
	 [-z|-zap|-zap_glyphs bytes]
	 [-P|-pm|-pin|-pin_mode	[delim]]
	 [-0|-noat|-no_auto_tag]
	 [-p|-at|-auto_tag]
	 [-N|-number...	[regex...]]
	 [-U|-unnumber... [regex...]]
	 [-F|-en|-embedded_number]
	 [-D|-data|-options [parameter...]
	 [-b|-blank]
	 [-M|-middle|-center]
	 [-d|-restore|-delete|-clean|-delete_window|-clean_window]
	 [-c|-col|-col_mode|-column]
	 [-l|-line|-line_mode]
	 [-t|-tab|-tab_mode|-tabulate_mode [cols]]
	 [-w|-wide|-wide_mode]
	 [-C|-cs|-cols|-cols_select... selector...]
	 [-R|-rs|-rows|-rows_select... selector...]
	 [-A|-fc|-first_column regex]
	 [-Z|-lc|-last_column regex]
	 [-g|-gutter [string]]
	 [-k|-ks|-keep_spaces]
	 [-W|-ws|-wd|-word_delimiters|-word_separators bytes]
	 [-L|-ls|-ld|-line-delimiters|-line_separators bytes]
	 [-q|-no_bar|-no-scroll_bar]
	 [-S|-subst... /regex/repl/opts]
	 [-I|-si|-subst_included... /regex/repl/opts]
	 [-E|-se|-subst_excluded... /regex/repl/opts]
	 [-ES|-early_subst... /regex/repl/opts]
	 [-/|-search_method prefix|substring|fuzzy]
	 [-s|-sp|-start|-start_pattern pattern]
	 [-x|-tmout|-timeout type [word] delay]
	 [-X|-htmout|-hidden_timeout type [word] delay]
	 [-r|-auto_validate]
	 [-is|-incremental_search]
	 [-v|-vb|-visual_bell]
	 [-Q|-ignore_quotes]
	 [-lim|-limits limit:value...]

	 selectors ::= col1[-col2],...|row1[-row2],...|RE,...
	 parameter ::= [l|r:<char>]|[a:left|right]|[p:included|all|[w:<num>]|
		       [f:yes|no]|[o:<num>[+]]|[n:<num>]|[i:<num>]|[d:<char>]|
		       [s:<num>]|[h:trim|cut|keep]
	 attr	   ::= [fg][/bg][,style]
	 RE	   ::= <char>regex<char>

	 selectors and RE can be freely	mixed.
	 <char>	in RE is any non-blank ASCII character except ','.

       Note that some parameters require that others have been previously  en-
       tered in	the command line to be accepted.

DESCRIPTION
       This  small utility acts	as a filter when no input file is given	(reads
       from stdin and writes to	stdout)	or takes its inputs from that file.

       All the words read are presented	in a scrolling window on the  terminal
       at  the	current	 cursor	position without having	previously cleared the
       screen.

       The selection cursor is initially positioned on	the  first  selectable
       word by default.

       There  are options to explicitly	or implicitly include or exclude words
       using extended regular expressions.  Note that when some	words are  ex-
       plicitly	excluded they can no longer be re-included after.

       Excluded	 words are skipped when	the selection cursor is	moved and can-
       not be searched for.

       The -W|-ws|-wd|-word_delimiters|-word_separators	option can be used  to
       set  the	 characters (or	multibyte sequences) which will	be used	to de-
       limit the input words.  The default delimiters are: SPACE, \t and \n.

       The -L|-ls|-ld|-line-delimiters|-line_separators	has a similar  meaning
       for lines.

       Special	character sequences formed by a	\ followed by one of the char-
       acters a	b t n v	f r and	\ are understood and  have  their  traditional
       meanings.

       UTF-8 sequences introduced by \u	and \U are also	understood.

       Warning,	when used together, it is important to know that all sequences
       beginning with \U will be interpreted before the	beginning of  the  in-
       terpretation of sequences beginning with	\u.

       \u  can	be  followed by	2,4,6 or 8 hexadecimal characters composing an
       UTF-8 bytestring.  Here is an example of	using \u to  compose  a	 Latin
       Small Letter E with Acute: \uc3a9.

       \U  must	be followed by exactly 6 hexadecimal digits, including leading
       zeros, that represent a Unicode codepoint according to ISO 10646	UCS-4.
       The  Latin Small	Letter E with Acute of the previous example (codepoint
       U+00E9) can then	be represented as \U0000e9.

       Note that with most shells, the \ before	u and U	need to	 be  protected
       or escaped.

       Quotations  (single  and	double)	in the input stream can	be used	to ig-
       nore the	word separators	so that	a group	of words are taken as a	single
       entity.

       Non printable characters	in words that are not delimiters are converted
       to their	traditional form (\n for end-of-line, \t for tabulation...) by
       default.

       An  invalid UTF-8 sequence or other non-printable character will	be re-
       placed by a dot (.) by default.

       There is	nevertheless a possibility to change this substitution charac-
       ter  with another ASCII printable one with the help of the command line
       option -.|-dot|-invalid.

       Warning,	UTF-8 encoded codepoints are quietly converted into  the  sub-
       stitution  character when the user locale is not	UTF-8 aware like POSIX
       or C by example.

       Words containing	only spaces, entered directly or resulting from	a sub-
       stitution,  are also rejected unless they are not selectable.  This al-
       lows special effects like creating  blank  lines	 for  example.	 These
       words are also kept in column mode, selectable or not.

       smenu  has  an  option to define	a set of characters or UTF-8 sequences
       which should be ignored when reading words.  This can  be  very	useful
       when  dealing  with inputs where	the EOL	sequence consists in more than
       one character.

       A typical example is DOS	or Windows files with lines ending with	 CRLF.
       In  such	 a  case one might decide to ignore all	CR characters from the
       input.

   Moving among	words
       The cursor can be moved in every	direction by using the keyboard	 arrow
       keys  (<-,|v,|^,->) 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
       |v, 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|-number,	-U|-unnumber or	-F|-en|-embedded_number	are used, then
       it becomes possible to directly access a	word by	entering  its  number.
       The  numbering created using these option is done before	any words sub-
       stitution done using -S|-subst /regex/repl/opts,	-I|-si|-subst_included
       or -E|-se|-subst_excluded.

       Using a combination of these options, it	is easy	to control which words
       will be numbered	by adding a special symbol in it  before  using	 smenu
       and    removing	 it   (substituted   by	  nothing)   afterward	 using
       -I|-si|-subst_included by example.

       -E|-se|-subst_excluded gives another way	to do that, see	below or more.

   Changing input words
       smenu offers the	possibility to modify the input	words  in  a  sed-like
       way.   Words  can  be modified at two points: just after	they have been
       read and	after other operations have been applied,  such	 as  enabling,
       disabling or coloring.

       The  related  options are -ES|-subst, -S|-subst,	-I|-si|-subst_included
       and -E|-se|-subst_excluded their	descriptions can be found in  the  OP-
       TIONS section.

   Searching for words
       A word can be searched using different algorithms: prefix, substring of
       fuzzy.

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

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

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

	      The case is also ignored.

	      Note  that spaces	and tabs at the	beginning and end of words are
	      ignored when searching for substrings or fuzzy strings.

	      The cursor is placed, if possible, on the	 first	matching  word
	      having  the  minimum  number  of gaps between the	first and last
	      matching character, see the difference between  the  actions  of
	      the s/S and n/N keys below.

	      This method also tolerates intermediate symbols not appearing in
	      the words	which will be ignored.	If this	is the case,  the  at-
	      tributes	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  in-
	      put,  then entering abxcdye puts abcdef in the search buffer and
	      the word is added	to the list of matching	 words	and  displayed
	      with an error attribute (in red by default).

	      This  special state will persist until all the symbols following
	      the first	erroneous one are deleted (using backspace) or if  ESC
	      is  pressed  to  cancel  the search session and clear the	search
	      buffer.

       During a	search session,	the cursor changes and each character  entered
       is  added  in  (or removed from)	the search buffer.  The	display	is re-
       freshed after each change in this buffer.

       A 10 seconds timeout (by	default) automatically ends the	current	search
       session	as  if	the Enter key had been pressed.	 This timeout is reset
       each time a new key is hit in search mode.  This	delay can  be  config-
       ured  using the search entry in the timers section of the configuration
       file as shown in	the example in the configuration subsection.

       The slash key (/) can also be used instead of any of  these  keys.   By
       default	it  is	is  programmed	to  do	a fuzzy	search but this	can be
       changed by using	the command line option	(-/|-search_method) or by tun-
       ing 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 highlight-
       ing methods are configurable.

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

       ENTER and all cursor moves terminate the	 search	 session  but  do  not
       clear the list of the matching words and	the search buffer.

       The  user  can  then  use the n/s/SPACE keys (forward) and the N/S keys
       (backward) to navigate in the list of matching words,

       In fuzzy	search mode, the s/S keys attempt to move the  cursor  to  the
       next/previous  word whose matching part forms a substring of this word.
       If no such matches exist, s/S and n/N do	the same things.  To move  the
       cursor  to  the	next/previous  fuzzy match, use	the n/N/SPACE keys.  s
       means next substring match in this context  while  n  just  means  next
       match.

       If  the	user hits the HOME or END key during a search session then the
       list of matching	words is reduced to the	words starting	(respectively)
       ending  with  the  current  search pattern and the window is refreshed.
       For those who consider HOME and END as non-intuitive,  the  CTRL	A  and
       CTRL Z  keys are	also available in search mode as an alternative.  This
       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

       |v			       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 end-	    No
				       ing with	the search pat-
				       tern

       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.

       CTRL C  (Abort)	also allows you	to exit	the program immediately	with a
       return code equal to 128+SINGINT	(by default)  without  selecting  any-
       thing.	See  the -!|-int|-int_string option for	more information about
       the customization of the	CTRL C behaviour.

       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|-auto_validate option	to change this behavior.

   Tagging (multiple selections)
       When   the   tagging   is   activated   by   using   the	 command  line
       -T|-tm|-tag|-tag_mode or	-P|-pm|-pin|-pin_mode option, then the keys t,
       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:

       o The scroll bar	is not displayed if all	the input words	 fit  on  only
	 one line.

       o Otherwise,  the scroll	bar is always displayed	except when the	-q op-
	 tion is set.  This option completely disables the scroll bar display.

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

       o 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, giv-
       ing  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 val-
       ues 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	termi-
       nates.

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

       --8<------------------------------------------------------------------
       [colors]
	 ; The terminal	must have at least 8 colors and/or have	attributes like	bold
	 ; and reverse for this	to be useful
	 ; if not the following	settings will be ignored.

	 method=ansi		 ; classic | ansi (default)

	 cursor=0/2		 ; cursor attributes
	 cursor_on_tag=0/2,u	 ; cursor on tag attributes
	 shift=6,b		 ; shift symbol	attributes
	 message=0/3		 ; message (title) attributes
	 bar = 7/4,b		 ; scroll bar attributes
	 search_field =	0/6	 ; search field	attributes
	 search_text = 7,bu	 ; search text attributes
	 match_field = 1,b	 ; matching words field	attributes
	 match_text = 7,bu	 ; matching words text attributes
	 search_err_field = 1	 ; approximate search field attributes
	 search_err_text = 1,r	 ; approximate search text attributes
	 ; match_err_field = 3	 ; approximate matching	words field attributes
	 match_err_text	= 1	 ; approximate matching	words text attributes
	 ; include = b		 ; selectable color attributes
	 exclude = 4/0,u	 ; non-selectable color	attributes
	 tag = 0/5		 ; tagged (selected) attributes
	 daccess = 3,b		 ; direct access tag attributes

	 special1 = 7/4,b	 ; attributes for the special level 1
	 special2 = bu		 ; attributes for the special level 2
	 special3 = /3,b	 ; attributes for the special level 3
	 special4 = 7/4		 ; attributes for the special level 4
	 special5 = 7/2,b	 ; attributes for the special level 5
	 special9 = 2,rb	 ; attributes for the special level 9

       [window]
	 lines = 7		 ; default number of lines of the window

       [limits]
	 word_length = 1024	 ; arbitrary max length	of input words (int)
	 words = 32767		 ; arbitrary max number	of allowed input
				 ; words (int)
	 columns = 128		 ; arbitrary max number	of columns (int)

       [timers]
	 search	= 100		 ; search timeout in 1/10 s
	 help =	150		 ; duration of the help	message	in 1/10	s
	 window	= 7		 ; delay before	redrawing if the size of the
				 ; terminal's window change in 1/10 s
	 direct_access = 6	 ; duration allowed to add a new digit to
				 ; the direct word access number in 1/10 s

       [misc]
	 default_search_method = substring
       --8<------------------------------------------------------------------

       o 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 num-
	 bers  representing the	foreground and background color	and toggles is
	 a strings which can contain the characters b, d, r, s,	 u,  i	and  l
	 standing  for	bold,  dim,  reverse,  standout, underline, italic and
	 blink.

       o Spaces	are allowed anywhere in	 the  lines  and  between  them,  even
	 around	the =.

       o Everything following a	; is ignored.

       o When undefined, the default limits are:

	 words	       32767
	 word_length   512
	 columns       256

OPTIONS
       Not all options may be available, depending on the current context.

       When smenu is called and	before the first option	is evaluated, it is in
       the Main	context.  Each option can switch to another context  in	 which
       only a subset of	the options is usable.

       For  each  parameter described below, the contexts in which the associ-
       ated option is defined as well as the context to	 which	it  leads,  if
       any, are	given.

       An  option  not	defined	in a context will force	the end	of the current
       context and will	be recursively evaluated in the	previous contexts  un-
       til  found  (or	not).  If not found, an	error message is displayed and
       smenu is	terminated.

       The contexts defined in smenu are:

       Main
	 The default context

       Columns
	 After the -c|-col|-col_mode|-column parameter.

       Lines
	 After the -l|-line|-line_mode parameter.

       Tabulations
	 After the -t|-tab|-tab_mode|-tabulate_mode parameter.

       Tagging
	 After the -T|-tm|-tag|-tag_mode or -P|-pm|-pin|-pin_mode parameter.

       WARNING
	 Here is a situation that may seem confusing at	first glance.

	 Imagine the only parameter command line parameter is -cols_select.

	 Since this is a parameter of an option	which is not valid when	not in
	 the  Columns  context,	 it  should  have raised an error but it still
	 seems to be accepted.

	 The trick is: when not	in column mode -cols_select is indeed not  ac-
	 cepted	 but  its prefix (-col)	is valid.  The options are thus	under-
	 stood as: -col	-s_select.  The	same mechanism occurs again as	-s  is
	 also  valid  in column	mode so	the final understanding	of the command
	 line is: -col -s _select.

	 Another example that illustrates the fact that	long  parameters  have
	 priority  over	short parameter	combinations: -is will not select only
	 words containing a "s", but will act in the same way as its  alterna-
	 tive name (-incremental_search).

	 If  you really	want to	select only words containing a "s", simply add
	 a space after the i as	in -i s	or use one of the other	-i names  such
	 as -inc for example.

	 In such cases,	the user may set the CTXOPT_DEBUG environment variable
	 which any non-empty content.

	 If we reconsider the -cols_select example with	CTXOPT_DEBUG  set  the
	 output	is now:

	 CTXOPT_DEBUG: Parameter: -cols_select.	Evaluation context: Main.
	 CTXOPT_DEBUG: Found a valid parameter as a prefix of -cols_select: -col.
	 CTXOPT_DEBUG: Parameter: -col.	Evaluation context: Main.
	 CTXOPT_DEBUG: Switch to context Columns.
	 CTXOPT_DEBUG: Parameter: -s_select. Evaluation	context: Columns.
	 CTXOPT_DEBUG: Found a valid parameter as a prefix of -s_select: -s.
	 CTXOPT_DEBUG: Parameter: -s. Evaluation context: Columns.
	 CTXOPT_DEBUG: Argument: _select.

	 In this case, adding a	space in the command line: -col	-cols_select 1
	 also solves the issue and indicates that only the first column	should
	 be selectable.

	 Note, however,	that at	least one argument for -cols_select is now re-
	 quired:

	 CTXOPT_DEBUG: Parameter: -col.	Evaluation context: Main.
	 CTXOPT_DEBUG: Switch to context Columns.
	 CTXOPT_DEBUG: Parameter: -cols_select.	Evaluation context: Columns.
	 CTXOPT_DEBUG: Argument: 1.

       The -h|-help and	-?|-u|-usage options now display the help and synopsis
       of the available	options	in the current context.

       Example:
	 smenu -col -u will only show the usage	in the Columns context

       The  contexts contain all the non-context-changing options so, in prac-
       tice, the usage should be intuitive.  You may nevertheless have to  ad-
       just some scripts using the old smenu releases as I did in the lvm_menu
       example.

       Some of the advantages of this new system of options are:

       o Long parameter	names are allowed One dash is enough, but two are also
	 allowed for compatibility reasons.

       o An option can be referenced by	any number of parameters with short or
	 long names.

       o Auto checking of missing mandatory options, duplicated	option,...

       o Only options usable in	the current context are	allowed.

       This  option  management	 system	 is  explained	in  more   detail   at
       https://github.com/p-gen/ctxopt.

       The description of each command line parameter is as follows:

       -h|-help
	      (Allowed in all contexts.)

	      Display a	context	specific help messages and exits.

       -H|-long_help
	      (Allowed in the "Main" context.)

	      Display a	long (non context specific) help messages and exits.

       -?|-u|-usage
	      (Allowed in all contexts.)

	      Displays a short help message and	exits.

       -V|-version
	      (Allowed in the "Main" context.)

	      The .smenu files in the user's home directory and	in the current
	      directory, if present, will be ignored when this option is used.

       -n|-lines|-height [height]
	      (Allowed in all contexts.)

	      Gives the	maximum	number of lines	 in  the  scrolling  selection
	      window.

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

	      If -n|-lines|-height  is	present	 without  argument,  then  the
	      height  of  the terminal will be used to determine the number of
	      lines.  This remains true	even if	the terminal is	resized.

	      If -n|-lines|-height is present with a numerical argument,  this
	      value will be used to determine the number of lines.

       -i|-in|-inc|-incl|-include... regex
	      (Allowed in all contexts.)

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

	      -i|-in|-inc|-incl|-include can be	used more than once with cumu-
	      lative effect.

	      \u and \U	sequences can also be used in the regexp.

       -e|-ex|-exc|-excl|-exclude... regex
	      (Allowed in all contexts.)

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

	      -e|-ex|-exc|-excl|-exclude can be	used more than once with cumu-
	      lative effect.  This filter has a	higher priority	than  the  in-
	      clude filter.

	      The   regex  selections  made  using  -i|-in|-inc|-incl|-include
	      and/or -e|-ex|-exc|-excl|-exclude	are done before	 the  possible
	      words    alterations    made    by   -I|-si|-subst_included   or
	      -E|-se|-subst_excluded (see below).

	      \u and \U	sequences can also be used in the regexp.

       -m|-msg|-message|-title message
	      (Allowed in all contexts.)

	      Displays a message (title) above the window.  If the current lo-
	      cale is not UTF-8, then all UTF-8	characters will	be replaced by
	      the substitution character.

	      \u and \U	sequences can be used in the message.

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

       -!|-int|-int_string [string]
	      (Allowed in all contexts.)

	      The  optional  string argument, when present, defines the	string
	      to be used as the	selection string when the CTRL C  sequence  is
	      entered.

	      If string	is missing then	nothing	will be	selected.

	      In all cases, when -!|-int|-int_string is	present	in the command
	      line, the	return code of the program will	be 0.

	      This gives the user the choice to	make the behaviour  of	CTRL C
	      similar  to that of q and	Q or to	that of	the Unix shell leaving
	      the shell	with a return code greater than	128.

       -a|-attr|-attributes prefix:attr...
	      (Allowed in all contexts.)

	      Sets the display attributes of the elements  displayed  and  the
	      cursor.

	      At least one attribute prefixed attribute	must be	given.

	      prefix can take the following values:

	      i	     included words.

	      e	     excluded words.

	      c	     cursor.

	      b	     scroll bar.

	      s	     shift indicator.

	      m	     message (title).

	      t	     tagged words.

	      ct     cursor on tagged words.

	      sf     search field.

	      st     search text.

	      sfe    approximate search	field with error.

	      ste    approximate search	text with error.

	      mf     matching words field.

	      mt     matching words text.

	      mfe    matching words field with error.

	      mte    matching words text with error.

	      da     direct access tag.

	      If  more	than one attribute is given, they must be separated by
	      spaces.

	      Example: -attr i:/5 e:4,br b:7/3,rb c:7/2,b

	      See the the -1|-l1|-level1 option	below for the  description  of
	      the attributes syntax after the colon and	an example.

       -1|-l1|-level1 regex [attr]

       -2|-l2|-level2 regex [attr]

       -3|-l3|-level3 regex [attr]

       -4|-l4|-level4 regex [attr]

       -5|-l5|-level5 regex [attr]

       -6|-l6|-level6 regex [attr]

       -7|-l7|-level7 regex [attr]

       -8|-l8|-level8 regex [attr]

       -9|-l9|-level9 regex [attr]
	      (Allowed in all contexts.)

	      Allows one to give a special display color to up to 5 classes of
	      words specified by regular expressions.  They are	called special
	      levels.  Only selectable words will be considered.

	      By  default,  the	 first	5 special levels have their foreground
	      color set	to red,	green, brown/yellow, purple and	cyan  and  the
	      remaining	 4 levels are set to white.  All these colors also can
	      be set or	modified permanently in	the configuration files.   See
	      the example file above for an example.

	      The  optional second argument (attr) can be used to override the
	      default or configured attributes of each class.  Its  syntax  is
	      the same as the one used in the configuration file:
	      [fg][/bg][,{b|d|r|s|u|i|l}] | [{b|d|r|s|u|i|l}]

	      Examples of possible attributes are:
		2/0,bu green on	black bold underline
		/2     green background
		5      text in purple
		rb     reverse bold

	      \u and \U	sequences can be used in the pattern.

       -z|-zap|-zap_glyphs bytes
	      (Allowed in all contexts.)

	      Initializes a set	of UTF-8 characters to be ignored when reading
	      words from stdin or a file.

	      Example: The argument '\u0d\ue282ac,' means: ignore all  commas,
	      Euro  signs  and	carriage  return  characters when reading from
	      stdin or a file.

	      As shown above \u	and \U sequences can be	used in	the bytes set.

       -T|-tm|-tag|-tag_mode [delim]
	      (Allowed in the following	contexts: "Main", "Columns",  "Lines",
	      and "Tabulations", switches to the "Tagging" context.)

	      Allows  multiple	selections  and	switches to tag	mode.  In this
	      mode, several selectable words can be selected  without  leaving
	      the program.

	      Tagged words are highlighted (underlined by default).

	      The  current word	can be automatically tagged when the ENTER key
	      is  pressed  to  complete	  the	selection   process   if   the
	      -p|-at|-auto_tag	option	is  also  set  or  if no word has been
	      tagged.

	      Note that	nothing	is selected when no word is  tagged  and  when
	      the -0|-noat|-no_auto_tag	option is also set.

	      All  tagged words	(and possibly the world	under the cursor) will
	      be sent to the standard output separated by the  optional	 argu-
	      ment given after the option -T|-tm|-tag|-tag_mode.

	      Note  that  this separator can have more than one	character, can
	      contain UTF-8 characters (in native or \u	or \U  form)  and  can
	      even contain control character as	in $'\n'.

	      A	 single	 space	character  is used as the default separator if
	      none is given.

	      Caution: To get exactly the same behavior	as in  version	0.9.11
	      and earlier, you must also use the -p|-at|-auto_tag option.

       -P|-pm|-pin|-pin_mode [delim]
	      (Allowed	in the following contexts: "Main", "Columns", "Lines",
	      and "Tabulations", switches to the "Tagging" context.)

	      Works	 like	   -T|-tm|-tag|-tag_mode      but,	unlike
	      -T|-tm|-tag|-tag_mode,  the output depends on the	order in which
	      the words	were tagged.  In other words, the  first  tagged  word
	      comes  first  in	the output, the	second tagged word comes next,
	      and so on.

       -p|-at|-auto_tag
	      (Allowed in the "Tagging"	context.)

	      This   option   modifies	 the   default	 behavior    of	   the
	      -T|-tm|-tag|-tag_mode and	-P|-pm|-pin|-pin_mode options.

	      An  untagged  word under the cursor will be automatically	tagged
	      when ENTER is pressed.

       -0|-noat|-no-auto_tag
	      (Allowed in the "Tagging"	context.)

	      This   option   modifies	 the   default	 behavior    of	   the
	      -T|-tm|-tag|-tag_mode and	-P|-pm|-pin|-pin_mode options.

	      An  untagged  word  under	 the  cursor will not be automatically
	      tagged when ENTER	is pressed and	no  other  words  are  tagged.
	      This is true even	when the option	-p|-at|-auto_tag is also set.

	      It is ignored if at least	one other word is tagged at that time.

       -N|-number>da_ctx... [regex]
	      (Allowed	in  the	following contexts: "Main", "Columns", "Lines"
	      and "Tabulation".)

	      This option allows you to	number selectable words	that  match  a
	      specific	regular	expression.  These numbers are numbered	from 1
	      and allow	direct access to the words.

	      To use this functionality, the user must enter the number	 which
	      corresponds to the desired entry digit per digit.

	      Each new digit must be added in a	time frame of 1/2 seconds (per
	      default) otherwise the number is considered complete and a newly
	      entered  digit  will start a new number.	If the number does not
	      exists, then the cursor is restored to it's initial position.

	      The sub-options of the -D|-data|-options option described	 below
	      can change the way -N|-number sets and formats the numbers.

	      This  option accepts more	than one argument and can be used mul-
	      tiple times with cumulative effects.

	      -N|-number,  -U|-unnumber	 and  -F|-en|-embedded_number  can  be
	      mixed.

       -U|-unnumber>da_ctx... [regex]
	      (Allowed	in  the	following contexts: "Main", "Columns", "Lines"
	      and "Tabulation".)

	      This option allows one to	unnumber words.	  If  placed  after  a
	      previous	-N|-number,  it	can be used to remove the numbering of
	      selected words.  If placed before, the word which	doesn't	 match
	      its regular expression will be numbered by default.

	      This mechanism is	similar	to to the inclusion/exclusion of words
	      by -i|-in|-inc|-incl|-include and	-e|-ex|-exc|-excl|-exclude.

	      This option accepts more than one	argument and can be used  mul-
	      tiple times with cumulative effects.

	      -U|-unnumber,  -N|-number	 and  -F|-en|-embedded_number  can  be
	      mixed.

       -F|-en|-embedded_number
	      (Allowed in the following	contexts: "Main",  "Columns",  "Lines"
	      and "Tabulation".)

	      This  option  is	similar	 to -N|-number but does	not generate a
	      continuous flow of numbers but extracts them from	the  word  it-
	      self.

	      With  this  option you can take full control of the numbering of
	      the displayed word.  Note	that the numbering does	not need to be
	      ordered.

	      The  resulting  word  after the extraction of the	number must be
	      non empty.

	      Some sub-option are required, see	the  -D|-data|-options	option
	      described	below.

	      Notice  that for this option to work correctly, all the embedded
	      numbers must have	the same number	of digits.   To	 get  that,  a
	      preprocessing  may  be  necessary	on the words before using this
	      program.

	      -F|-en|-embedded_number,	-N|-number  and	 -U|-unnumber  can  be
	      mixed.

       -D|-data|-options [parameter...]
	      (Allowed	in  the	Following contexts: "Main", "Columns", "Lines"
	      and "Tabulations".)

	      This option allows one to	change the default  behaviour  of  the
	      -N|-number, -U|-unnumber and -F|-en|-embedded_number options.

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

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

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

	      a	(-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
		     Here  y  is 'left'	(or one	of its prefixes) if the	number
		     must be left aligned, or 'right' (or one of its prefixes)
		     if	it must	be right aligned.  The default is right.

	      p	(-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
		     Here  y is	'included' or 'all' for	the initial padding of
		     the non numbered words.   The  keyword  'included'	 means
		     that  only	included word will be padded while 'all' means
		     pad all words.

		     The default is all. These keywords	can be abbreviated.

	      w	(-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
		     Here y is the width of the	number between	1  and	5  in-
		     cluded.

	      f	(-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
		     Here y controls if	the numbering must follow the last ex-
		     tracted number (defaults to yes) or if it must remain in-
		     dependent.

		     The  possible  values  are	yes and	no but can be abbrevi-
		     ated.

	      m	(-F|-en|-embedded_number option)
		     Here y controls if	the numbering of word with missing em-
		     bedded numbers must be done or not	(defaults to yes).

		     When  this	 sub-option  is	set to no, the s and f sub-op-
		     tions are ignored.

		     The possible values are yes and no	but  can  be  abbrevi-
		     ated.

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

		     The allowed directives are: 'trim'	which discads them  if
		     they  form	an empty word (only made of spaces and tabula-
		     tions), 'cut' which  unconditionally  discards  them  and
		     'keep'  which places them at the beginning	of the result-
		     ing word.

		     The default value for this	 directive  is	'keep',	 these
		     keywords can be abbeviated.

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

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

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

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

		     Example:  n:2  will extract and use the first 2 digits of
		     each words	from the input stream to number	them.

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

	      d	(-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
		     Here  y is	a multibyte separator.	When present, this di-
		     rective instructs smenu to	output the  selected  numbered
		     word(s)  prefixed	by  its(their) direct access number(s)
		     and the given separator.

		     Only the numbered word(s) will be prefixed.

		     d stands for decorate.

		     This directive can	be  useful  when  you  want  to	 post-
		     process the output	according to its direct	access number.

	      s	(-F|-en|-embedded_number, -N|-number and -U|-unnumber options)
		     Here  y  is the direct access number that will be set for
		     the first numbered	word.  Its value is 1  by  default,  a
		     value of 0	is possible.

	      Example: -data r:\> l:\< a:l d:_

	      To number	all words with the default parameters, use the syntax:
	      "-N ." which is a	shortcut for: "-N . -D l:' ' r:')' a:r p:a"

	      The padding sub-option specifies whether	spaces	must  also  be
	      added in front of	excluded words or not to improve compactness.

	      When  the	 w sub-option is not given the width of	the numbers is
	      determined automatically but if -F|-en|-embedded_number  is  set
	      and  the	value  of the n	sub-option is given then this value is
	      used.

       -b|-blank
	      (Allowed in all contexts.)

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

       -.|-dot|-invalid
	      (Allowed in all contexts.)

	      Sets  the	 substitution  character for non-printable characters.
	      When this	parameter is not used, the default substitution	 char-
	      acter is a single	dot.

       -M|-middle|-center
	      (Allowed in all contexts.)

	      Centers the display if possible.

       -d|-restore|-delete|-clean|-delete_window|-clean_window
	      (Allowed in all contexts.)

	      Tells the	program	to clean up the	display	before quitting	by re-
	      moving the selection window after	use as if it  was  never  dis-
	      played.

       -c|-col|-col_mode|-column
	      (Allowed	in  the	"Main" and "Tagging" contexts, switches	to the
	      "Columns"	context.)

	      Sets the column mode.  In	this mode the lines of	words  do  not
	      wrap  when  the right border of the terminal is reached but only
	      when a special character is read.	 Some words will not  be  dis-
	      played without an	horizontal scrolling.

	      If  such	a  scrolling is	needed,	some indications may appear on
	      the left and right edge of the window to help the	user to	 reach
	      the unseen words.

	      In  this	mode,  the width of each column	is minimal to keep the
	      maximum information visible on the terminal.

       -l|-line|-line_mode
	      (Allowed in the "Main" and "Tagging" contexts, switches  to  the
	      "Lines" context.)

	      Sets  the	 line  mode.  This mode	is the same as column mode but
	      without any column alignment.

       -t|-tab|-tab_mode|-tabulate_mode	[cols]
	      (Allowed in the "Main" and "Tagging" contexts, switches  to  the
	      "Tabulations" context.)

	      This  option sets	the tabulation mode and, if a number is	speci-
	      fied, attempts to	set the	number of displayed  columns  to  that
	      number.

	      In  this	mode,  embedded	line separators	are ignored if not ex-
	      plicitly set with	 -L|-ls|-ld|-line-delimiters|-line_separators.
	      The  options  -A|-fc|-first_column  and  -Z|-lc|-last_column can
	      nevertheless be used to force words to appear in the first  (re-
	      spectively last) position	of the displayed line.

	      Note  that the number of requested columns will be automatically
	      reduced if a word	does not fit in	the calculated column size.

	      In this mode each	column has the same width.

       -w|-wide|-wide_mode
	      (Allowed in the "Columns"	and "Tabulations" contexts.)

	      When -t|-tab|-tab_mode|-tabulate_mode is followed	by a number of
	      columns,	the default is to compact the columns so that they use
	      the less terminal	width as possible.  This option	 enlarges  the
	      columns in order to use the whole	terminal width.

	      When  in	column	mode, -w|-wide|-wide_mode can be used to force
	      all the columns to have the same size (the  largest  one).   See
	      option -c|-col|-col_mode|-column below.

	      Note  that  the  column's	 size is only calculated once when the
	      words are	displayed for the first	time.  A terminal resize  will
	      not update this value.  This choice enables a faster display.

       -C|-cs|-cols|-cols_select... [i|e]selectors...
	      (Allowed in the "Columns"	context.)

	      I	and E have the same meaning as i and e.

	      In column	mode, this option is useful to restrict	the selections
	      to a subset of all columns.  Either by including (nothing	or  i)
	      or by excluding (e) them.

	      Columns can be designated	by their number	(1 based) or by	a reg-
	      ular expression enclosed in delimiter made  from	any  non-blank
	      ASCII character excluding	the comma.

	      Range  of	 columns (number or RE)	can be given by	separated then
	      with a dash.

	      Multiple selectors can be	regrouped in one argument using	commas
	      to  separate them.  This option also accepts multiple arguments,
	      each of them being a selector.

	      A	selection by regular expressions means that a column  contain-
	      ing a word matching any of these expressions will	be included or
	      excluded depending on the	letter given after the option  or  be-
	      fore the selector	if there is more than one argument.

	      Regular expressions and column numbers can be freely mixed.

	      Regular	  expression	in    -C|-cs|-cols|-cols_select	   and
	      -R|-rs|-rows|-rows_select	can contain  UTF-8  characters	either
	      directly or by using the \u or \U	notation.

	      Example  of columns selection: -Ci2,3,/X./,5-7 forces the	cursor
	      to only navigate in columns 2,3,5,6 and 7	and those containing a
	      two  characters  word starting with 'X'.	If e was used in place
	      of i, all	the columns would have been selected except  the  col-
	      umns  2,3,5,6,7  and those matching the extended regular expres-
	      sion 'X.'.

	      Spaces are allowed in the	selection  string  if  they  are  pro-
	      tected.

	      Other  example where multiple selectors are used as multiple ar-
	      guments: ps | smenu -col -cols e/TTY/ e/CMD/ e3

       -R|-rs|-rows|-rows_select... selectors...
	      (Allowed in the "Columns"	and "Lines" contexts.)

	      Similar to -C|-cs|-cols|-cols_select but for the rows.

	      -C|-cs|-cols|-cols_select	and -R|-rs|-rows|-rows_select  can  be
	      used more	than once in a cumulative manner:

	      The  selection  mode (selection or de-selection) is given	by the
	      first occurrence of the options, the other occurrences will only
	      update the selected or de-selected ranges.

	      Once  a  column  or a row	has been excluded, it cannot be	re-in-
	      cluded.

       -A|-fc|-first_column regex
	      (Allowed in the following	contexts: "Columns", "Lines" and "Tab-
	      ulations".)

	      In  column mode, forces all words	matching the given regular ex-
	      pression to be the first one in the displayed line.  If you want
	      to  only rely on this method to build the	lines, just specify an
	      empty   regex   to   set	 the   end-of-line   separator	  with
	      -L|-ls|-ld|-line-delimiters|-line_separators '')

	      \u  and  \U  sequences  can  also	 be  used  in the regexp after
	      -A|-fc|-first_column.

       -Z|-lc|-last_column regex
	      (Allowed in the following	contexts: "Columns", "Lines" and "Tab-
	      ulations".)

	      Similar  to  -A|-fc|-first_column	 but forces the	word to	be the
	      latest of	its line.  The same trick with -L|-ls|-ld|-line-delim-
	      iters|-line_separators can also be used.

	      \u  and  \U  sequences  can  also	 be  used  in the regexp after
	      -Z|-lc|-last_column.

       -g|-gutter [string]
	      (Allowed in the "Columns"	and "Tabulations" contexts.)

	      Replaces the blank after each words in column or tabular mode by
	      a	column separator.

	      This separator is	extracted from the string argument and each of
	      its (multibyte) character	is used	one after the  other  to  fill
	      the gutter.

	      If  there	 are more columns that gutter characters then the last
	      character	is used	for the	remaining columns.

	      When not given, the separator defaults to	a vertical bar | (or a
	      full height vertical bar if the locale is	set to UTF-8).

	      Each  character  can  be given in	normal or \u or	\U form	in the
	      string argument.

	      Example: "|- " will allow	one to separate	the first two  columns
	      with  '|',  then	'-' will be used and ' ' will separate the re-
	      maining columns if any.

       -k|-ks|-keep_spaces
	      (Allowed in all contexts.)

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

       -W|-ws|-wd|-word_delimiters|-word_separators bytes
	      (Allowed in all contexts.)

	      This  option can be used to specify the characters (or multibyte
	      sequences) which will be used to delimit the input words.

	      Multibyte	sequences (UTF-8) can be natives  of  using  the  same
	      ASCII representation used	in words (a leading \u or \U following
	      by up to 8 hexadecimal characters	for the	former and 6 hexadeci-
	      mal characters for the latter).

	      Non-printable  characters	in arguments should be given using the
	      standard $'' representation.  $'\t' stands  for  the  tabulation
	      character	for example.

	      The default delimiters are: SPACE, $'\t' and $'\n'.

       -L|-ls|-ld|-line-delimiters|-line_separators bytes
	      (Allowed in all contexts.)

	      This  option can be used to specify the characters (or multibyte
	      sequences) which will be used to delimit the lines in the	 input
	      stream.

	      Multibyte	 sequences  (UTF-8)  can  be natives of	using the same
	      ASCII representation used	in words (a leading \u or \U following
	      by up to 8 hexadecimal characters	for the	former and 6 hexadeci-
	      mal characters for the latter).

	      Non-printable characters in arguments should be given using  the
	      standard $'' representation.  $'\n' stands for the newline char-
	      acter for	example.

	      The default delimiter is:	$'\n'.

	      This option is only useful when the -c|-col|-col_mode|-column or
	      -l option	is also	set.

	      The    characters	   (or	  multibyte   sequences)   passed   to
	      -L|-ls|-ld|-line-delimiters|-line_separators  are	 automatically
	      added  to	the list of word delimiters as if -W|-ws|-wd|-word_de-
	      limiters|-word_separators	was also used.

	      \u and \U	sequences can also be used here.

       -q|-no_bar|-no-scroll_bar
	      (Allowed in all contexts.)

	      Prevents the display of the scroll bar.

       -S|-subst... /regex/repl/[g][v][s]
	      (Allowed in all contexts.)

	      Post-processes the words by applying a regular expression	 based
	      substitution.  The argument must be formatted as in the sed edi-
	      tor.

	      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:

	      o	The optional trailing g	(for global) means that	 all  matching
		occurrences shall be replaced and not only the first one.

	      o	The  optional  trailing	 v (for	visual)	means that the altered
		words will only	be used	for display and	search.	 The modifica-
		tions will not be reflected in the returned word.

	      o	The  optional trailing s (for stop) means that no more substi-
		tution will be allowed on this word even if another  -S|-subst
		is used.

	      o	The  optional  trailing	 i  (for  ignore  case)	means that the
		string search operation	should ignore the case for  this  pat-
		tern.

		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|-si|-subst_included... /regex/repl/[g][v][s]
	      (Allowed in all contexts.)

	      Post-processes  the  selectable  words by	applying a regular ex-
	      pression based substitution (see -S|-subst for details).

       -E|-se|-subst_excluded... /regex/repl/[g][v][s]
	      (Allowed in all contexts.)

	      Post-processes the excluded (or non-selectable) words by	apply-
	      ing  a  regular expression based substitution (see -S|-subst for
	      details).

	      The    /	  separator    that	-I|-si|-subst_included	   and
	      -E|-se|-subst_excluded are using above can be substituted	by any
	      other character except SPACE, \t,	\f, \n,	\r and \v.

	      In the three previous options, regex is a	POSIX Extended Regular
	      Expression.  For details,	please refer to	the regex manual page.

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

       If   a	post-processing	  action  (-S|-subst,  -I|-si|-subst_included,
       -E|-se|-subst_excluded) results in an empty (length 0)  word,  then  we
       have two	cases:

	      in column	mode:
		     Substitutions involving empty words can lead to misalign-
		     ments, so it is necessary to prohibit them	and  terminate
		     the  program.   These  substitutions have to be made with
		     other tools before	using this utility.

	      otherwise:
		     The word is simply	removed.

       -ES|-subst... /regex/repl/[g][v][s]
	      (Allowed in all contexts.)

	      Pre-processes words by applying a	substitution based on a	 regu-
	      lar  expression.	 The  argument must be formatted as in the sed
	      editor.

	      The substitutions	are made, as the name of the option indicates,
	      before any other selection or coloring actions are made.

	      This  option can be used more than once.	Each substitution will
	      be applied in sequence on	 each  word.   This  sequence  can  be
	      stopped if a stop	flag is	encountered.

	      In  summary, this	option is similar to the -S|-subst option pre-
	      viously described, except	that the substitutions are  made  ear-
	      lier and certain flags like visual are ignored.

	      Note  that this option can be used in conjunction	with the other
	      substitution options mentioned above.

       -/|-search_method search_method
	      (Allowed in all contexts.)

	      Affects the '/' key to a search method.  By default '/'  is  af-
	      fected  to  'fuzzy'  but the argument can	be any prefix of 'pre-
	      fix', 'substring'	or 'fuzzy'.

       -s|-sp|-start|-start_pattern pattern
	      (Allowed in all contexts.)

	      Place the	cursor on the first word corresponding to  the	speci-
	      fied pattern.

	      pattern can be:

	      o	A  # immediately followed by a number giving the initial posi-
		tion of	the cursor (counting from 0).

		If the word at this position is	excluded, then the first  pre-
		vious  non  excluded  word is selected if it exists, otherwise
		the first non excluded word is selected.

		If this	number if greater than the number of words, the	cursor
		will be	placed on the latest selectable	position.

	      o	A single # or the string #last to set the initial cursor posi-
		tion on	the latest selectable word position.

	      o	A string starting with a / indicating that we want the	cursor
		to  be placed on the first word	matching the given regular ex-
		pression.

	      o	A string starting with a = indicating than we want the	cursor
		to be placed on	that exact word.

	      o	A normal string. In this case the cursor will be placed	on the
		first word starting with that string (Ca will match Cancel  by
		example).

	      Warning,	when  searching	 for a prefix or a regular expression,
	      smenu only looks for them	after an eventual modification,	so for
	      example,	the  command:  smenu  -I/c/x/ -s/c <<< "a b c d" won't
	      find c and put the cursor	on a but smenu -I/c/x/v	-s/c <<< "a  b
	      c	d" will	find it	and put	the cursor on the x substituting the c
	      on screen	only

	      \u and \U	sequences can be used in the pattern.

       -x|-tmout|-timeout type [word] delay

       -X|-htmout|-hidden_timeout type [word] delay
	      (Allowed in all contexts.)

	      Sets a timeout.  Three types of timeout are possible:

	      current:	At the timeout,	the word under the cursor  and/or  the
			tagged	words  are  sent to the	standard output	if the
			ENTER key has been pressed

	      quit:	At the timeout,	nothing	is selected as if  the	q  key
			has been pressed

	      word:	At  the	 timeout, the word given after the type	is se-
			lected.	 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  sec-
	      onds.

	      The  remaining time (in seconds) is added	at the end of the mes-
	      sage displayed above the selection window	and is updated in real
	      time each	second.

	      Any  key	except	ENTER, q, Q and	CTRL C resets the timer	to its
	      initial value.

	      The    -X|-htmout|-hidden_timeout	    version	works	  like
	      -x|-tmout|-timeout  but  no  periodic remaining messages is dis-
	      played above the selection window.

       -r|-auto_validate
	      (Allowed in all contexts.)

	      Enables ENTER to validate	the selection even in search mode.

       -is|-incremental_search
	      (Allowed in all contexts.)

	      By default, when a new search session is initiated, the  current
	      search  buffer  is  reset.  When this parameter is set, the next
	      search will start	where the last search ended, except if ESC was
	      hit before.

	      This  option  instructs  not to clean the	previous search	buffer
	      each time	a new search session is	started.

       -v|-vb|-visual_bell
	      (Allowed in all contexts.)

	      By default, when searching, an alarm is produced by the terminal
	      when  the	 user enters a character or makes a move which lead to
	      no result	or to an error condition.   This  argument  make  this
	      beep visual by briefly showing the cursor.

       -Q|-ignore_quotes
	      (Allowed in all contexts.)

	      Using  this  option  will	 remove	the word grouping feature from
	      single and double	quotes which will be considered	normal charac-
	      ters.   For  example:  "a	 b" will be considered by smenu	as two
	      words "a and b" and no more as a single word: a b.

       -lim|-limits limit:value...
	      (Allowed in all contexts.)

	      This option gives	the possibility	to modify the default  maximum
	      number  of  words	 or  columns  and  the	maximum	permitted word
	      length.

	      The specified values overload the	default	 settings  and/or  the
	      settings given in	the configuration files.

	      In order to do that, three sub-options can be used:

	      l:value
		     to	set the	maximum	word length allowed.

	      w:value
		     to	set the	maximum	number of words	allowed.

	      c:value
		     to	set the	maximum	number of columns allowed.

NOTES
       If  tabulators  (\t)  are embedded in the input,	there is no way	to re-
       place them with the original number of spaces.  In this	case  use  an-
       other filter (like expand) to pre-process the data.

EXAMPLES
   1
       Simple Yes/No/Cancel request with "No" as default choice:

       In bash:
	 read R	<<< $(echo "Yes	No Cancel" \
		      |	smenu  -d -m "Please choose:" -s /N)

       or
	 R=$(echo "Yes No Cancel" \
	     | smenu -d	-m "Please choose:" -s /N)

       In ksh:
	 print "Yes No Cancel"		      \
	 | smenu -d -m "Please choose:"	-s /N \
	 | read	R

   2
       Get  a  3 columns report	about VM statistics for	the current process in
       bash/ksh	on Linux:

       R=$(grep	Vm /proc/$$/status | expand | smenu -b -W$'\n' -t3 -g -d)

   3
       Create a	one column selection window containing the list	of  the	 first
       20  LVM	physical  volumes.   At	 the end, the selection	window will be
       erased.	This example is	written	in ksh).

       pvs -a -o pv_name --noheadings		      \
       | smenu -m "PV list" -n20 -t1 -d	-s //dev/root \
       | read R

       The display will	have a look similar to the following with  the	cursor
       set on the word /dev/root:

       PV list
       /dev/md126	    \
       /dev/md127	    |
       /dev/root	    | <- cursor	here.
       /dev/sda2	    |
       /dev/sdb2	    |
       /dev/sdc1	    |
       /dev/sdc2	    |
       /dev/system/homevol  /

   4 (advanced)
       Imagine a file named sample.mnu with the	following content:

       --8<---------------------------------
       "1 First	Entry" "3 Third	entry"
       "2 Second entry"	"4 Fourth entry"
       @@@ "5 Fifth entry"
       @@@
       "0 Exit menu"
       --8<---------------------------------

       Then  this  quite  esoteric  command  will  render  it (centered	on the
       screen) as:

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

       with the	cursor on Quit and only	the numbers and	"Quit" selectable.

       R=$(smenu -q -d -s/Exit -M -n 30	-c	  \
		 -e "@+" -E '/@+/ /'		  \
		 -F -D n:1 i:1			  \
		 -m "Test menu"	< sample.mnu)

       The selected entry will be available in R

       Try to understand it as an exercise.

ENVIRONMENT
       NO_COLOR	      force a monochrome terminal when set.
       CTXOPT_DEBUG   put the option parser in debug mode.

BUGS/LIMITATIONS
       Some terminal emulators,	those notably based on VTE version later  than
       0.35  (see https://github.com/GNOME/vte/commit/01380d), have a new fea-
       ture 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
       (C) 2015-present, Pierre	Gentile	(p.gen.progs@gmail.com)

								      smenu(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | EXAMPLES | ENVIRONMENT | BUGS/LIMITATIONS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=smenu&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help