NAME¶
iSelect -- Interactive Selection Tool
SYNOPSIS¶
iselect [
-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, operating 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 is read either from the command line (
line1 line2 ...)
where each argument corresponds to one buffer line or from
stdin (when
no arguments 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 corresponding 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"'' constructs. 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¶
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 parsing.
- -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/
directory 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/