Man page - iselect(1)

Packages contains this manual

Manual

ISELECT (1) Ralf S. Engelschall ISELECT (1)

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, line s 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 linenum ber.

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

SEE ALSO

New iSelect Home : https://sr.ht/~nabijaczleweli/ossp ossp-iselect 1.4.2 November 17, 2024 ISELECT (1)