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

FreeBSD Manual Pages


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

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

       smenu [-h|-?] [-n lines]	[-t [cols]] \
	     [-k] [-s pattern] [-m message] [-w] \
	     [-d] [-M] [-c] [-l] [-r] [-b] \
	     [-i regex]	[-e regex] \
	     [-C [a|A|s|S|r|R|d|D][col1[-col2],[col1[-col2]... \
	     [-R [a|A|s|S|r|R|d|D][row1[-row2],[row1[-row2]... \
	     [-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 \
	     [-1 regex [ATTR] [-2 regex	[ATTR] ... [-5 regex [ATTR] \
	     [-g] [-q] [-W bytes] [-L bytes] \
	     [-T [seperator]]] [-V]

       This small utility acts as a filter (reads from	stdin  and  writes  to
       stdout).	 All  the  words taken from stdin are presented	in a scrolling
       window on the terminal at the current cursor position.

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

       It  is  possible	 to filter the selectable words	in the input stream by
       using an	include	regular	expression to match the	selectable  words  and
       an exclude regular expression to	match the non-selectable words.

       Notice  that  when  some	 words are excluded they can no	more be	re-in-
       cluded after.

       Non-selectable words are	skipped	when moving the	selection  cursor  and
       cannot 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

       Quotations (single and double) in the input stream enable to ignore the
       word separators so that a group of words	are taken as a single entity.

       Non printable characters	in words that are not  a  delimiter  are  con-
       verted  to  their  traditional form (\n for end-of-line,	\t for tabula-
       tion...)	by default.  A single dot (.) is also used  as	a  placeholder

       Warning,	 UTF-8 encoded codepoints are quietly converted	into a dot (.)
       when the	user locale is not UTF-8 aware like POSIX or C by example.

   Moving among	words
       The cursor can then 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 their	tradi-
       tional meanings.

   Searching for a word
       The  key	/ or the key combination ^F (Ctrl-f) can be used to initiate a
       search by prefix	among the words	after the cursor.

       After that, the cursor attribute	is modified and	all characters entered
       7s after	this change go into a search buffer with the cursor moving im-
       mediately to the	next word matching this	prefix.

       Any character entered in	the 5s after this action completes  this  buf-
       fer,  resets the	5s timer and advances the cursor again if another word
       matches the new buffer.

       As soon as the timer ends, the search mode is ended and the cursor  re-
       gains its initial appearance.

       The  search buffer is persistent	as long	as the cursor is on a matching
       word when a new search is initialized.

       If the cursor is	moved in this mode, the	timer will expire  immediately
       As if ENTER or ESC was pressed.

       Pressing	ENTER or ESC immediately exits this mode.

       Pressing	SPACE or n repeats the last search if the search buffer	is not
       empty.  Nothing will happen if there is no matching word	after the cur-

       Note  that  the SPACE and n keys	cannot be used when the	search mode is
       active because they must	be available if	you want to search a word con-
       taining these characters.

   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.

       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	a |, giving the	 rela-
       tive position of	the cursor line	in the bunch of	input words.

   Terminal resizing
       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 on 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).

       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-

       Here  is	an example giving the syntax and the names of the keywords al-

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

	 method=ansi		 ; classic | ansi (default)

	 cursor=0/2		 ; cursor attributes
	 cursor_on_tag=0/2,u	 ; cursor on tag attributes
	 shift=6,b		 ; shift symbol	attributes
	 bar = 7/4,b		 ; scroll bar attributes
	 search_field =	0/6	 ; search field	attributes
	 search_text = 7,bu	 ; search text attributes
	 exclude = 4/0,u	 ; non-selectable color	attributes
	 tag = 0/5		 ; tagged (selected) 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

	 lines = 7		 ; default number of lines of the window

	 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)

       * 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   256
	 columns       256

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

       -n lines
	      Gives  the  maximum  number  of lines in the scrolling selection
	      window.  By default five lines at	most  are  displayed  and  the
	      other ones, if any, need you to scroll the window.

       -t [columns]
	      This  option sets	the tabulation mode and, if a number is	speci-
	      fied, limits the number of displayed columns to that number.  In
	      this mode, embedded line separators are ignored.	The options -A
	      and -Z can nevertheless be used to force words to	appear in  the
	      first (respectively last)	position of the	displayed line.

	      Note that	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.   Note  that
	      these spaces must	have been protected to be selected.

       -s pattern
	      Pre-Position the cursor to the first word	matching the specified

	      pattern can be:

	      *	A # immediately	followed by a number giving the	initial	 posi-
		tion  of  the  cursor  (counting  from	0).  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-

	      *	A prefix string	indicating that	we want	the cursor to  be  set
		on  the	 first	word  matching the string given	(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

       -m message
	      Displays	a message above	the window.  Beware, it	will 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-

       -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     Replace all non-printable	characters by a	blank.

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

       -e regex
	      Sets the exclude filter to match the non-selectable words.

	      This filter has a	higher priority	than the include filter.

       The regex selections above are done before  the	possible  word	alter-
       ations realized with -I or -E (see below).

       -C [a|A|s|S|r|R|d|D][col1[-col2]],[col1[-col2]]...
	      In  column  mode,	restricts the previous selections or de-selec-
	      tions 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).

	      a/A, s/S or nothing select the specified ranges of columns.  r/R
	      or d/D select all	but the	specified columns.

	      The words	in the selected	columns	will be	considered as included
	      and the others excluded.

	      Example of columns selection: -a2,3,5-7  forces  the  cursor  to
	      only  navigate in	columns	2,3,5,6	and 7.	If d was used in place
	      of a, all	the columns would have been selected except  the  col-
	      umns 2,3,5,6 and 7.

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

	      The column mode is forced	when this option is selected.

       -R [a|A|s|S|r|R|d|D][col1[-col2]],[col1[-col2]]...
	      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.

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

	      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.


	      *	The  optional  trailing	 g (for	global)	means that all matched
		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

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

		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.
       Notice that a substitution resulting in an empty	string	is  equivalent
       to removing the word.

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

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

       In the four previous options, regex is a	POSIX Extended Regular Expres-
       sion.  For details, please refer	to the regex manual page.

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

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

       -1 ... -5 regex [ATTR]
	      Allows to	give up	to 5 classes of	words specified	by regular ex-
	      pressions	a special display color.  They are called special lev-
	      els.  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

       -g     Replaces the blank after each words in column or tabular mode by
	      a	vertical bar |.	Some users may find the	output	more  readable
	      with it.

       -q     Prevents	the  scroll  bar  display.   Useful when all the input
	      words can	be displayed without the need of  scrolling.   By  de-
	      fault the	scroll bar is always displayed when there is more than
	      one line.	 An absence of cursor in it gives a visual  indication
	      that all the input words are there.

       -W bytes
	      This  option can be used to specify the characters (or multibyte
	      sequences) which will be used to delimit the input  words.   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.  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

       -T [separator]
	      Enables the multi-selections or tagged mode.  In this mode, each
	      selectable word can be selected without ending the program.  The
	      last  selection  is  then	done as	usual by hitting the ENTER key
	      which also ends the program.

	      All the tagged words (and	the world under	the cursor)  are  then
	      sent  to	stdout separated by the	optional argument given	to the
	      -T option.  Note than this separator  can	 have  more  than  one
	      character	and can	even contain control character as in $'\n'.

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

       -V     Displays the current version and quits.

       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.

       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)

	 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

       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)

       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:

       [1] "First Entry" [3] "Third entry"
       [2] "Second entry" [4] "Fourth entry"
       @@@ @@@ [5] "Fifth entry"
       [Quit] "Exit menu"

       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	|
       |				|
       |Quit Exit menu			|

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

       R=$(smenu -q -d -s/Q -M -n 30 -c		      \
		 -e "@+" -E '/@+//'		      \
		 -i '\[	*[^ ]+ *\]' -I '/[][ ]//g'    \
		 -m "Test menu"	< sample.mnu)

       The selected number or string will be available in R

       Try to understand it as an exercise.

       None that I am aware of.	 If you	found one, please tell me.

       (C) 2015	Pierre Gentile (

beta				     2015			      smenu(1)


Want to link to this manual page? Use this URL:

home | help