Ubuntu Manpage: iSelect — Interactive Selection Tool

NAME

       iSelect — Interactive Selection Tool

SYNOPSIS

       iselect  [-d beg,end] [-cfae] [-p linenum] [-k key[:okey]] [-m] [-n name] [-t title] [-SKP] [-Q fallback]
               line…
       iselect [-d beg,end] [-cfae] [-p linenum] [-k key[:okey]] [-m] [-n name] [-t title] [-SKP] [-Q  fallback]
               < lines
       iselect -V|-h

DESCRIPTION

   Intent
       iSelect is an interactive line selection tool, operating via a full-screen Curses-based terminal session.
       It  can  be  used  either  as a user interface frontend controlled by the shell, Perl, or another type of
       script backend as its wrapper, or in batch as a pipe filter (usually between grep and the final executing
       command).  In other words: iSelect was designed to  be  used  for  any  type  of  interactive  line-based
       selection.

   Input Data
       If  no  arguments  are  given,  lines are read from the standard input stream.  Otherwise, lines are used
       directly.

       Each selectable line is fully bold; parts of other  lines  may  be  set  in  bold  by  wrapping  them  in
       ‘<b>...</b>’.

   Selections
       By  default, a single line may be chosen; with -m multiple lines can be selected.  By default, only lines
       containing the tag ‘<s>’ (or with different delimiters set with -d) may be selected.  -a allows selecting
       all lines, but the tag is always removed.  Selected lines are written to the standard output stream

       The tag has a variant that looks like ‘<s:result text>’, which,  instead  of  writing  the  line  itself,
       writes result text.  Every format specifier in the form ‘%[prompt string]s’ or ‘%[prompt string]S’ in the
       output  is  replaced by a line entered in an interactive prompt.  The s variant allows empty responses; S
       doesn't.

OPTIONS

Input Options
-d beg,end, --delimiter=beg,end
Sets the delimiters for the selection tags. The default is < and > — the selection tags have to read
‘<s>’ and ‘<s:result text>’.

-c, --strip-comments
Discard input lines starting with ‘#’.

-f, --force-browse
Open the full-screen browser even if input contains less than <2 lines. This may happen anyway if a
‘%[prompt]s’ needs to be substituted.

-a, --all-select
Force all lines to be selectable. ‘<s>’ tags are still removed.

-e, --exit-no-select
Exit immediately if no lines are selectable.

Display Options
-p, --position=linenum
Sets the cursor position to 1-based linenumber.

-k, --key=key:okey
Maps key to okey. Both may be either a printable character or one of SPACE, RETURN, KEY_UP (↑),
KEY_DOWN (↓), KEY_LEFT (←), KEY_RIGHT (→), KEY_PPAGE (PgUp), KEY_NPAGE (PgDn). This can be given any
number of times, and is applied in order.

-k, --key=key
Same as -k key:RETURN. For example, -k f allows using ‘f’ to confirm the selection.

-m, --multi-line
Allow selecting more than one line with Space.

-n, --name=name
Changes the string displayed flush left at the bottom of the browser window from "iSelect".

-t, --title=title
Sets the file ..., displayed centered at the bottom of the browser window.

Output Options
-S, --strip-result
Strip all leading and trailing whitespace from the result string.

-K, --key-result
Prefix each result with the key used to confirm the selection. This is usually "RETURN" or
"KEY_RIGHT", but in the presence of -k, this is the (unmapped) key; thus, with -k f, selecting line
Foo Bar by pressing ‘f’ yields ‘f:Foo Bar’. A Space is rendered as a literal space, not as "SPACE".

-P, --position-result
Prefix each result with its 1-based line number in the buffer.

-Q, --quit-result=fallback
Write fallback to the standard output stream when quitting.

Giving Feedback
-V, --version
Write the version and licence information to the standard output stream, exit 0.

-h, --help
Write the usage string information to the standard error stream, exit 0.

KEYSTROKES

   Cursor Movement
       Use these to browse through the selection list:
         CURSOR-UP ..... Move cursor one line up
         CURSOR-DOWN ... Move cursor one line down
         PAGE-UP ....... Move cursor one page up
         PAGE-DOWN ..... Move cursor one page down
         g ............. Goto first line
         G ............. Goto last line

   Line Selection
       Use these to select one line and exit in standard mode, or one or more lines in multi-line mode:
         RETURN ........ Select line and exit
         CURSOR-RIGHT .. Select line and exit
         SPACE ......... Select line and stay (multi-line mode only)
         C ............. Clear current marks  (multi-line mode only)

   Others
       Use these to quit iSelect or to show the help or version pages:
         q ............. Quit (exit without selection)
         CURSOR-LEFT ... Quit (exit without selection)
         h ............. Help Page
         v ............. Version Page

FILES

       The Curses session is always opened on /dev/tty, because the standard I/O streams  are  usually  tied  to
       pipes.

EXIT STATUS

       0  if a selection was made, a selection wasn't made, or succumbed to SIGINT or SIGTERM.
       1  if an unknown [o]key was given or an I/O error occurred.

EXAMPLES

       As  an  example  we  present  a real-life situation where iSelect can enhance existing functionality.  We
       define two shell functions (for your $HOME/.bashrc file) which enhance the shell's cd built-in.
         #   database scan
         cds () {
             find "$HOME" -type d | sort > ~/.dirs &
         }

         #   enhanced cd command
         cd () {
             if [ -d "$1" ]; then
                 builtin cd "$1"
             else
                 builtin cd "$(grep -E "/$1[^/]*$" ~/.dirs   |
                               iselect -a -Q "$1" -n "chdir" \
                               -t "Change Directory to...")"
             fi
         }

       This cd() is compatible with the built-in in the case where  the  specified  directory  actually  exists.
       When  it  doesn't,  the  original  cd would immediately give an error (assuming CDPATH is not set).  This
       version tries harder by searching for such a directory in a previously-built  (via  cds())  ($HOME/.dirs)
       file.   When  no  match  is  found, iSelect just returns the given directory as the default result and cd
       fails as usual.  When only one directory was found, iSelect gives it to cd silently.  Only when more then
       one directory was found, iSelect shows  a  menu  to  pick  between  matches  interactively.   The  chosen
       directory is then given to cd.

       For more useful examples on how to use iSelect, see /usr/share/doc/iselect/examples.

AUTHORS

       Ralf S. Engelschall <rse@engelschall.com> (http://www.engelschall.com)