path: root/smenu.1

.TH smenu 1 "2015" "beta"
.SH NAME
smenu - filter that allows one to interactively select a word from stdin
and outputs the selection to stdout.
.SH SYNOPSIS
.nf
\f(CRsmenu [\fB-h\fP|\fB-?\fP] [\fB-f\fP \fIconfiguration_file\fP] \\
      [\fB-n\fP \fIlines\fP] [\fB-t\fP [\fIcols\fP]] [\fB-k\fP] \\
      [\fB-s\fP \fIpattern\fP] [\fB-m\fP \fImessage\fP] [\fB-w\fP] \\
      [\fB-d\fP] [\fB-M\fP] [\fB-c\fP] [\fB-l\fP] [\fB-r\fP] [\fB-b\fP] \\
      [\fB-a\fP (i|e|c|b|s|t|ct|sf|st|da):\fIATTR\fP]... \\
      [\fB-i\fP \fIregex\fP] [\fB-e\fP \fIregex\fP] \\
      [\fB-C\fP \
[\fIi\fP|\fIe\fP]<col selectors>] \\
      [\fB-R\fP \
[\fIi\fP|\fIe\fP]<row selectors>] \\
      [\fB-S\fP \fI/regex/string/\fP[\fIg\fP][\fIv\fP][\fIs\fP][\fIi\fP]] \\
      [\fB-I\fP \fI/regex/string/\fP[\fIg\fP][\fIv\fP][\fIs\fP][\fIi\fP]] \\
      [\fB-E\fP \fI/regex/string/\fP[\fIg\fP][\fIv\fP][\fIs\fP][\fIi\fP]] \\
      [\fB-A\fP \fIregex\fP] [\fB-Z\fP \fIregex\fP] \\
      [\fB-N\fP [\fIregex\fP]] [\fB-U\fP [\fIregex\fP]] [\fB-F\fP] \
[\fB-D\fP \fIsub-option\fP...] \\
      [\fB-1\fP \fIregex\fP [\fIATTR\fP]] \
[\fB-2\fP \fIregex\fP [\fIATTR\fP]] ... \
[\fB-5\fP \fIregex\fP [\fIATTR\fP]] \\
      [\fB-g\fP [\fIstring\fP]] [\fB-q\fP] \
[\fB-W\fP \fIbytes\fP] [\fB-L\fP \fIbytes\fP] \\
      [\fB-T\fP [\fIseparator\fP]] [\fB-P\fP [\fIseparator\fP]] [\fB-p\fP] \\
      [\fB-V\fP] [\fB-x\fP|\fB-X\fP \fItype\fP [\fIword\fP] \fIdelay\fP] \\
      [input_file]

      <col selectors> ::= \fIcol1\fP[-\fIcol2\fP],...|\fI<RE>\fP,...
      <row selectors> ::= \fIcol1\fP[-\fIcol2\fP],...|\fI<RE>\fP,...
      <sub-option>    ::= [l|r:<char>]|[a:left|right]|[p:included|all|
                          [w:<num>]|[f:yes|no]|[o:<num>]|[n:<num>]|
                          [i:<num>][d:<char>]
      <ATTR>          ::= [fg][/bg][,style]
      <RE>            ::= \fB<char>\fIregex\fB<char>\fR

      <col/row selectors> and <RE> can be freely mixed.
      The parameters of -a and -D must be delimited by blanks.
.fi
.SH 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
\fBat\fP the current cursor position without clearing the screen before.
.PP
The selection cursor is initially positioned on the first selectable word
by default.
.PP
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.
.PP
Excluded words are skipped when the selection cursor is moved and cannot
be searched for.
.PP
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.
.PP
The \fB-L\fP has a similar meaning for lines.

Special character sequences formed by a \fI\\\fP followed by one of the
characters \fIa\fP \fIb\fP \fIt\fP \fIn\fP \fIv\fP \fIf\fP \fIr\fP and
\fI\\\fP are understood and have their traditional meanings.

UTF-8 sequences introduced by \fI\\u\fP are also understood.
\fI\\u\fP can be followed by 2,4,6 or 8 hexadecimal characters.
An invalid UTF-8 sequence will be replaced by a dot  (\fI.\fP), see
also below.

Example: \fI\\uc3a9\fP means latin small letter e with acute.
.PP
Note that with most shells, the \fI\\\fP before the \fIu\fP need to be
protected or escaped.
.PP
Quotations (single and double) in the input stream can be used to ignore
the word separators so that a group of words are taken as a single entity.
.PP
Non printable characters in words that are not delimiters 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.
.PP
Words containing only spaces, entered directly or resulting from a
substitution, are also rejected unless they are not selectable.
This allows special effects like creating blank lines for example.
These words are also kept in column mode, selectable or not.
.PP
\fBWarning\fP, \fBUTF-8\fP encoded codepoints are quietly converted
into dots (\fI.\fP) when the user locale is not \fBUTF-8\fP aware like
\fBPOSIX\fP or \fBC\fP by example.
.PP
.SS "Moving among words"
The cursor can be moved in every direction by using the
keyboard arrow keys (\fB\(<-\fP,\fB\(da\fP,\fB\(ua\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 the following meanings:
.TS
tab(@);
l l.
\(<-, h@Previous word
\(ua, k@Previous line
PgUp, K@Previous pages
Home@First word of the window
CTRL+Home, SHIFT+Home, CTRL+k@First word
.sp
\(->, l@Next Word
\(da, j@Next line
PgDn, J@Next pages
End@Last word of the window
CTRL+End, SHIFT+End, CTRL+j@Last word
.TE

If the \fB-N\fP, \fB-U\fP or \fB-F\fP are used then it is possible to
directly access a word by entering its number.
The numbering created using these option is done \fBbefore\fP any words
substitution done using \fB-S\fP, \fB-I\fP or \fB-E\fP.

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 \fB-I\fP by example.

\fB-E\fP gives another way to do that, see below or more.
.SS "Searching for a word"
The key \fB/\fP or the key combination \fB^F\fP (\fBCTRL+f\fP) can be
used to initiate a search by prefix among the words (possibly altered
by \fB-S\fP/\fB-I\fP/\fB-E\fP) located after the cursor.
.PP
After that, the cursor attributes are modified and all the characters
entered up to a default of 6s after this change are put in a search buffer
and the cursor moves immediately to the next word matching this prefix.
.PP
Any character entered before a default of 6s timeout after this action
completes this buffer and resets the the 6s timer and advances the cursor
again if another word matches the new buffer.
.PP
As soon as the timer expires, the search mode is ended and the cursor
regains its initial appearance.
.PP
The search buffer is persistent as long as the cursor is on a matching
word when a new search is initialized.
.PP
If the cursor is moved in this mode, the timer will expire immediately
As if \fBENTER\fP or \fBESC\fP was pressed and the move is attempted.
.PP
Pressing \fBENTER\fP or \fBESC\fP immediately exits this mode.
.PP
Pressing \fBSPACE\fP or \fBn\fP repeats the last search if the search
buffer is not empty.
Nothing will happen if there is no matching word after the cursor.
.PP
Note that the \fBSPACE\fP and \fBn\fP keys cannot be used when the search
mode is active because they must be available if you want to search a
word containing these characters.
.SS "Selection and Exit"
Pressing \fBq\fP gives the possibility to exit without selecting anything.
.PP
By default, \fBENTER\fP 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 \fIeven\fP when 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 when the \fB-q\fP
option is set.
This option completely disables 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
tab(@);
l l l l l
l l l l l
l l l l .
\\@\\@^@^@\\ @Do not remove this trailing space!
|@|@|@|@/
/@v@/@v
.TE
.PP
A \fB+\fP can also appear in the scroll bar in lieu of the vertical bar,
giving the relative position of the cursor line in the bunch of input
words.
.SS "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.
.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
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
\fIini\fP file.
The values read from the file in the home directory will be overridden by
the ones read from the local directory (if it is present).

Missing and bad keywords are silently skipped.

The values read, if valid, override the default hard-coded ones.

If a value is invalid an error message is shown and the program terminates.

The values of the timers must be given in units of \fB1/10\fP of a second.

Here is an example giving the syntax and the names of the keywords
allowed:
.PP
.nf
\f(CR--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
  bar = 7/4,b             ; scroll bar attributes
  search_field = 0/6      ; search field attributes
  search_text = 7,bu      ; search text attributes
  ; include = b           ; selectable color attributes
  exclude = 4/0,u         ; non-selectable color attributes
  tag = 0/5               ; tagged (selected) attributes
  dacess = 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
--8<------------------------------------------------------------------
\fP
.fi
.IP * 2
The \fBmethod\fP keyword can take the two poss