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
       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 can-
       not be searched for.

       The -W option can be used to  set  the  characters  (or	multibyte  se-
       quences)	 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	 char-
       acters  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  fol-
       lowed  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 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.	 A single dot (.) is also used as a placeholder	otherwise.

       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.

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

       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.

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

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

       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  op-
       tion,  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  op-
	 tion 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, 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

       [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 num-
	 bers 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 con-
	      figuration 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	termi-
	      nal 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	speci-
	      fied,  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  dis-
	      played 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	speci-
	      fied pattern.

	      pattern can be:

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

	      *	A single # or the string #last to set the initial cursor posi-
		tion 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 expres-
		sion.

	      *	A prefix string	indicating that	we want	the cursor to  be  set
		on the first word matching the string given (a will match Can-
		cel 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 re-
	      moving  the  selection  window after use as if it	was never dis-
	      played.

       -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  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     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 re-
	      sults 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 fil-
	      ter 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  contain-
	      ing  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 ei-
	      ther 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  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.

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

	      *	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 modifica-
		tions will not be reflected in the returned word.

	      *	The optional trailing s	(for stop) means that no more  substi-
		tution	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 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 /regex/replacement string/[g][v][s]
	      Post-processes the selectable words by applying  a  regular  ex-
	      pression based substitution (see -S for details).

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

	      The  /  separator	 that -I and -E	are using above	can be substi-
	      tuted 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 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.

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

	      \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	start-
	      ing 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 regu-
	      lar 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.  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 in-
		     cluded.

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

	      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  tabula-
		     tions),  'cut'  which  unconditionnaly  discards them and
		     'keep' which places them at the beginning of the  result-
		     ing 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	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 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  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, -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  re-
	      maining 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 char-
	      acter 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	 auto-
	      matically	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, sev-
	      eral  selectable	words can be selected without leaving the pro-
	      gram.

	      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,  con-
	      tain  UTF-8  characters (in native or \u form) and can even con-
	      tain 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  op-
	      tions.   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 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.

	      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 af-
	      fected to	'fuzzy'	but the	argument can be	any  prefix  of	 'pre-
	      fix', 'substring'	or 'fuzzy'.

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

beta				     2015			      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+12.2-RELEASE+and+Ports>

home | help