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.

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.

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