ISELECT(1) Ralf S. Engelschall ISELECT(1)NAME
iSelect -- Interactive Selection Tool
SYNOPSISiselect [-d STR,STR] [-c] [-f] [-a] [-e] [-p NUM] [-k KEY[:OKEY]] [-m]
[-n STR] [-t STR] [-S] [-K] [-P] [-Q STR] [line1 line2 ...]
iselect [-V]
VERSION
1.4.0 (08-Jul-2007)
DESCRIPTION
Intend
iSelect is an interactive line selection tool for ASCII files, operat‐
ing via a full-screen Curses-based terminal session. It can be used
either as an user interface frontend controlled by a Bourne-Shell, Perl
or other 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 types of interactice
line-based selections.
Input Data
Input is read either from the command line (line1 line2 ...) where each
argument corresponds to one buffer line or from stdin (when no argu‐
ments are given) where the buffer lines are determined according to the
newline characters.
You can additionally let substrings displayed in Bold mode for non-
selectable lines (because the selectable lines are always displayed
bold) by using the construct ``"<b>"..."</b>"'' as in HTML.
Selections
The selection is either just a single line (default) or multiple lines
(option -m). Per default no lines are selectable. If a line contains
the string ``"<s>"'' (or a string with different delimiters configured
via option -d) at any position this string is stripped and the line is
selectable. Its result (printed to stdout) is the line contents itself
(but without the ``"<s>"'' string of course). If option -a is used all
lines are selectable and their result is again the line itself, i.e.
using option -a is the same as adding ``"<s>"'' to every line of the
input data. When you want a specific result (i.e. not just the line
contents itself), you have to use the special variant ``"<s:result
text>"'' which results in the output ``"result text"'' when the corre‐
sponding line is selected.
When you use a specific result via ``"<s:result text>"'' the result
text can contain ``"%[query text]s"'' and ``"%[query text]S"'' con‐
structs. For every such construct an interactive query is done and the
result replaces the construct. The ``"%[query text]S"'' construct is
like ``"%[query text]s"'' except that the empty string as the query
result is not accepted on input.
The Curses-based full-screen selection is always done via /dev/tty,
because the stdin and stdout filehandles are usually tied to the input
and output data streams.
Output Data
The output is the line itself or the string given with ``"<s:result
text>"''. When multiple line selection mode (option -m) is used the
output is all selected lines theirself or their configured result
strings. Output always is written to stdout.
OPTIONS
Input Options
These options control how iSelect parses its input.
-d STR, --delimiter=STR
Sets the delimiters for the selection tags. The default is `"<,>"',
i.e. the selection tags have to read ``"<s>"'' and ``"<s:result
text>"''
-c, --strip-comments
Strips all sharp comment lines from the input buffer before pars‐
ing.
-f, --force-browse
Browse always, i.e. even when the input buffer contains no or only
one line.
-a, --all-select
Force all lines to be selectable.
-e, --exit-no-select
Exit immediately if no lines are selectable. In this case not even
the Curses screen is initialized.
Display Options
-p NUM, --position=NUM
Sets the cursor position to line NUM.
-k KEY[:OKEY], --key=KEY[:OKEY]
Defines an additional input key. Per default OKEY is "RETURN", i.e.
for instance -kf defines another selection key `"f"'.
-m, --multi-line
Enable multi-line selection where you can select more then one line
via SPACE key.
-n STR, --name=STR
Sets the name string, displayed flush left at the bottom of the
browser window.
-t STR, --title=STR
Sets the title bar string, displayed centered at the bottom of the
browser window.
Output Options
-S, --strip-result
Strip all leading and trailing whitespaces from the result string.
-K, --key-result
Prefix the result string (given on stdout) with the corresponding
selection key which was used. This usually is "RETURN" or
"KEY_RIGHT" but can be any of the additional keys defined by option
-k. When you use -kf and select a line "Foo Bar" with key `"f"'
the result string is ``"f:Foo Bar"''.
-P, --position-result
Prefix the result string (given on stdout) with the corresponding
cursor position followed by a colon. When you selected line N and
this line has the result "Foo Bar" configured the result string is
``"N:Foo Bar"''.
-Q STR, --quit-result=STR
Sets the result string on quit. Default is the empty string.
Giving Feedback
-V, --version
Displays version identification string.
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)
Others
Use these to quit iSelect or to show its help and version page.
q ............. Quit (exit without selection)
CURSOR-LEFT ... Quit (exit without selection)
h ............. Help Page
v ............. Version Page
EXAMPLE
As an example we present a real-life situation where iSelect can
enhance an existing functionality. We define two Bash functions (for
your $HOME/.bashrc file) which enhance the built-in `cd' command of the
shell.
# database scan for enhanced cd command
cds () {
(cd $HOME;
find . -type d -print ⎪\
sed -e "s;^\.;$HOME;" ⎪\
sort -u >$HOME/.cdpaths ) &
}
# definition of the enhanced cd command
cd () {
if [ -d $1 ]; then
builtin cd $1
else
builtin cd `egrep "/$1[^/]*$" $HOME/.cdpaths ⎪\
iselect-a -Q $1 -n "chdir" \
-t "Change Directory to..."`
fi
PS1="\u@\h:$PWD\n:> "
}
This new `cd' command is compatible with Bashs built-in variant for the
case where the specified directory actually exists. When it doesn't,
the original `cd' would immediately give an error (assuming we have no
CDPATH variable defined). Here this enhanced version tries harder.
First it searches for such a directory in a previously built (via cds)
$HOME/.cdpaths files. When no line was found, iSelect just returns the
given directory as the default result and `cd' then fails as usual with
an error message. When only one directory was found, iSelect directly
results this particular line to `cd'. And only when more then one
directory was found, iSelect opens its Curses-based selection screen
and lets the user choose interactively between those directories. The
chosen directory is then finally given to `cd'.
For more useful examples on how to use iSelect, see the contrib/ direc‐
tory of the iSelect distribution tarball.
AUTHOR
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
SEE ALSO
iSelect Home: http://www.ossp.org/pkg/tool/iselect/
EN 2007-07-08 ISELECT(1)
