path: root/smenu.1

.TH smenu 1 "2015" "beta"
.SH NAME
smenu - filter that allows to interactively select a word from stdin
and outputs the selection to stdout.
.SH SYNOPSIS
smenu [\fB-h\fP] [\fB-n\fP \fIlines\fP] [\fB-t\fP [\fIcols\fP]]
[\fB-s\fP \fIpattern\fP] [\fB-m\fP \fImessage\fP] [\fB-w\fP] [\fB-d\fP]
[\fB-c\fP] [\fB-r\fP] [\fB-b\fP] [\fB-i\fP regex] [\fB-e\fP regex]
[\fB-g\fP] [\fB-q\fP] [\fB-W\fP bytes] [\fB-L\fP bytes] [\fB-V\fP]
.SH DESCRIPTION
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 with a selection cursor initially positioned on
the first word by default.
.P
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.
.P
Non-selectable words will be skipped when moving the selection cursor
and will not be able to be searched.
.P
The \fB-W\fP option can be used to set the characters (or multibyte
sequences) which will be used to delimit the input words. The default
delimiters are: \fISPACE\fP, \fI\\t\fP and \fI\\n\fP.
.P
The \fB-L\fP has a similar meaning for lines.
.P
Non printable characters in words that are not a delimiter are
converted to their traditional form (\fI\\n\fP for end-of-line,
\fI\\t\fP for tabulation...) by default. A single dot (\fI.\fP) is also
used as a placeholder otherwise.
.P
\fBWarning\fP, \fBUTF-8\fP encoded codepoints are quietly converted
into a dot (\fI.\fP) when the user locale is not \fBUTF-8\fP aware like
\fBPOSIX\fP or \fBC\fP by example.
.P
If a word is only containing spaces, then all of them are 
converted into underscores (\fI_\fP) so that we can see them.
.P
.SS "Moving among words"
The cursor can then be moved in every directions by using the
keyboard arrow keys (\fB\(<-\fP, \fB\(ua\fP,\fB\(da\fP,\fB\(->\fP)
or the \fIvi\fP direction keys (\fBh\fP, \fBj\fP, \fBk\fP and \fBl\fP).
\fBHOME\fP, \fBEND\fP, \fBPgDn\fP and \fBPGUp\fP can also be used if
available and have their traditional meanings.
.SS "Searching for a word"
The \fB/\fP or \fB^F\fP (\fBCtrl-f\fP) can be used to initiate a
research by prefix among the words after the cursor.
.P
After that the cursor attribute is modified and all the characters
entered 7s after this change goes in a search buffer with the cursor
moving immediately to the next word matching this prefix. Any character
entered within 5s after that completes that buffer and resets the 5s
timer and possibly moves the cursor again.
.P
As soon as the timer ends, the search mode is ended and the cursor
regains its initial appearance.
.P
The search buffer if persistent as long as the cursor is on a matching
word when a new research is initialized.
.br
If the beginning of the word under the cursor does not match the
previous search buffer, then the search buffer if erased.
.P
At any time in this mode you can move the cursor with the keys
described above. \fBESC\fP ends this mode immediately.
.P
The \fBSPACE\fP or \fBn\fP key repeats the last research if the search
buffer is not empty. As in search mode, nothing happens if there is no
matching word after the cursor.
.P
Note that only the \fBSPACE\fP key can be used when the search mode is
active because the \fBn\fP character must be available if you want to
search a word containing this character.
.SS "Selection and Exit"
Hitting \fBq\fP exits without outputting anything, nothing is selected.
.P
By default, hitting \fBENTER\fP writes the selected word to stdout when
not in search mode. In search mode \fBENTER\fP ends this mode and do
nothing more. If you want to be able to select a word \fIeven\fP in
search mode, use the \fB-r\fP option to change this behavior.
.SS Help
A small help message can be displayed when hitting \fB?\fP. This display
will last for 10s or until a valid key or \fBESC\fP is pressed.
.SS 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:
.IP * 2
The scroll bar is not displayed if all the input words fit on only one
line.
.IP * 2
Otherwise, the scroll bar is always displayed except if the \fB-q\fP
option is set. This option completely disable the scroll bar display.
.IP * 2
When the scrolling window has only one line, the scroll bar has only 3
states:
.RS 2
.IP - 2
"\fBv\fP" when on all but the last line, indicating that you can go down
to see more.
.IP - 2
"\fB^\fP" when on the last line.
.IP - 2
"\fB|\fP" otherwise.
.RE
.IP * 2
When there is more than one line to display, "\fB/\fP" means that the window
displays the first line, "\fB\\\fP" the last line. "\fB|\fP" is used to fill
the gap, see below the different possible configurations.
.TS
l l l l l
l l l l l
l l l l.
\\	\\	^	^	\\ 
|	|	|	|	/
/	v	/	v
.TE
.P
A "\fB+\fP" can also appear in the scroll bar in lieu of a "\fB|\fP",
giving the relative position of the cursor line in the bunch of input
words.
.SS "Terminal resizing"
The windows is redrawn is 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.
.SS 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 \fBUTF-8\fP (\fBUTF-8\fP in the output of the \fIlocale\fP
command).
.SS Configuration
If a file with adequate permissions and the same name as the
executable prefixed with a dot is present in the user home
directory, then it will be parsed as a \fIini\fP file.
.P
For now, only color informations are considered.
.P
Here is an example giving the syntax and color names to use:
.P
.nf
[colors]
  ; The terminal must have at least 8 colors for this to be useful
  ; if not the following settings will be ignored.

  method=ansi          ; classic | ansi

  bar_foreground = 2   ; scroll bar foreground
  bar_background=0     ; scroll bar background

  search_foreground=11 ; search color foreground
  search_background=1  ; search color background

  exclude_foreground=4 : non-selectable color foreground
  exclude_background=0 : non-selectable color background

[window]
  lines = 7            ; default number of lines of the window
.fi
.IP * 2
The \fBmethod\fP 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 \fBansi\fP method (ISO 8613-6) if your terminal supports
more than 8 colors. The default value corresponds to \fBansi\fP.
.IP * 2
Spaces are allowed anywhere in the lines and between them, even around
the \fB=\fP.
.IP * 2
Everything following a \fB;\fP is ignored.
.SH OPTIONS
.IP \fB-h\fP
Displays a short help message and exists.
.IP "\fB-n\fP \fIlines\fB"
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.
.IP "\fB-t\fP [\fIcolumns\fP]"
This option sets the tabulation mode and, if a number is specified,
limits the number of displayed columns to that number.
.P
.RS
Note that if this mode each column has the same width.
.RE
.IP "\fB-s\fP \fIpattern\fP"
Pre-Position the cursor to the first word matching the specified pattern.

\fIpattern\fP" can be:
.RS
.IP * 2
A \fBnumber\fP giving the initial position of the cursor (counting from
0). If this number if greater than the number of words, the cursor will
be set on la last position.
.IP * 2
The string \fBlast\fP meaning that we want the initial position to be
on the last word.
.IP * 2
A string starting with a "\fB/\fP" indicating that we want the cursor
to be set on the first word matching the \fBprefix\fP string following
the "\fB/\fP" (\fB/Ca\fP will match \fBCancel\fP by example).
.PP
Every failure will do nothing, resulting with the cursor set on the
first word.
.RE
.IP "\fB-m\fP \fImessage\fP"
Displays a message above the window. Beware, it will truncated if it
does not fit on a terminal line.
.IP "\fB-w\fP"
When \fB-t\fP 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.
.P
.RS
Note that the column's size is only calculated once when the words are
displayed for the first time. A terminal resize will not alter this
value.  This choice enables a faster display.
.RE
.P
.IP \fB-d\fP
Tells the program to clean up the display before quitting by removing
the selection window after use as if it was never displayed.
.IP \fB-c\fP
Sets the column mode. In this mode the lines of words do not wrap when
the right border of the terminal is reached but only when a special
character is read. Some words will not be displayed without an
horizontal scrolling.
.RS
.P
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.
.P
In this mode, the width of each column is minimal to keep the maximum
information visible on the terminal.
.P
.RE
.IP \fB-r\fP
Enables \fBENTER\fP to validate the selection even in search mode.
.IP \fB-b\fP
Replace all non-printable characters by a blank.
.IP \fB-i regex\fP
Sets the \fBi\fPnclude filter to match the selectable words.
.IP \fB-e regex\fP
Sets the \fBe\fPxclude filter to match the non-selectable words.

This filter has a higher priority the include filter.
.IP \fB-g\fP
Replaces the blank after each words in normal tabular mode by a vertical
bar "\fB|\fP". Some users may find the output more readable like that.
.IP \fB-q\fP
Prevents the scroll bar display. Useful when all the input words can be
displayed without the need of scrolling. by default 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.
.IP \fB-W\fP
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: \fISPACE\fP, \fI\\t\fP and \fI\\n\fP.
.IP \fB-L\fP
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: \fI\\n\fP.

This option is only useful when the \fB-c\fP option is also used.

The characters (or multibyte sequences) passed to \fB-L\fP are
automatically added to the list of word delimiters as if \fB-W\fP was
also used.
.IP \fB-V\fP
Displays the current version and quits.
.SH NOTES
If tabulations (\fI\\t\fP) are embedded in the input, there is no way
to replace them with the original number of spaces. In this case use
an other filter (like \fIexpand\fR) to pre-process the data.
.SH EXAMPLES
.SS 1
Simple Yes/No/Cancel request with "No" as default choice:
.P
.nf
In \fBbash\fP: \fBread R <<< $(echo "Yes No Cancel" \\
                      | smenu  -d -m "Please choose:" -s /N)\fP

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

In \fBksh\fP:  \fBprint "Yes No Cancel"                \\
         | smenu -d -m "Please choose:" -s /N \\
         | read R\fP
.fi
.SS 2
Get a 3 columns report about VM statistics for the current process in
\fBbash\fP/\fBksh\fP on Linux:
.P
.nf
\fBR=$(grep Vm /proc/$$/status | expand | smenu -b -W$'\\n' -t3 -g -d)\fB
.P
.fi
.SS 3
Create a one column selection window containing the list of the first
20 LVM physical volumes. At end, the selection window will be erased.
This example is written in \fBksh\fP).
.P
.nf
\fBpvs -a -o pv_name --noheadings                 \\
| smenu -m "PV list" -n20 -t1 -d -s //dev/root \\
| read R\fP
.fi
.P
The display will have a look similar to the following with the cursor
set on the word \fI/dev/root\fP:
.P
.nf
PV list
/dev/md126           \\
/dev/md127           |
/dev/root            | <- cursor here.
/dev/sda2            |
/dev/sdb2            |
/dev/sdc1            |
/dev/sdc2            |
/dev/system/homevol  /
.fi
.SH BUGS
None that I am aware of. If you found one, please tell me.
.SH AUTHOR
\(co 2015 Pierre Gentile (p.gen.progs@gmail.com)
.SH SEE ALSO