ossp-pkg/iselect/iselect.pod
## _ ____ _ _
## (_) ___| ___| | ___ ___| |_
## / /\___ \ / _ \ |/ _ \/ __| __|
## / / ___) | __/ | __/ (__| |_
## (_( |____/ \___|_|\___|\___|\__|
##
## iSelect -- Interactive Selection Tool
##
## iSelect is a Curses-based tool for interactive line selection
## in an ASCII file via a full-screen terminal session.
##
## ======================================================================
##
## Copyright (c) 1997-2007 Ralf S. Engelschall.
##
## This program is free software; it may be redistributed and/or
## modified only under the terms of the GNU General Public License,
## which may be found in the iSelect source distribution.
## Look at the file COPYING for details.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
## See the the GNU General Public License for more details.
##
## ======================================================================
##
## iselect.pod -- manual page
##
=head1 NAME
iSelect -- Interactive Selection Tool
=head1 SYNOPSIS
B<iselect>
[B<-d> I<STR>,I<STR>]
[B<-c>]
[B<-f>]
[B<-a>]
[B<-e>]
[B<-p> I<NUM>]
[B<-k> I<KEY>[:I<OKEY>]]
[B<-m>]
[B<-n> I<STR>]
[B<-t> I<STR>]
[B<-S>]
[B<-K>]
[B<-P>]
[B<-Q> I<STR>]
[I<line1> I<line2> ...]
B<iselect>
[B<-V>]
=head1 VERSION
@V@
=head1 DESCRIPTION
=head2 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 F<grep>
and the final executing command). In other words: iSelect was designed to be
used for any types of interactice line-based selections.
=head2 Input Data
Input is read either from the command line (I<line1> I<line2> ...) where each
argument corresponds to one buffer line or from F<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 ``C<E<lt>bE<gt>>...C<E<lt>/bE<gt>>'' as in HTML.
=head2 Selections
The selection is either just a single line (default) or multiple lines (option
B<-m>). Per default no lines are selectable. If a line contains the string
``C<E<lt>sE<gt>>'' (or a string with different delimiters configured via
option B<-d>) at any position this string is stripped and the line is
selectable. Its result (printed to F<stdout>) is the line contents itself (but
without the ``C<E<lt>sE<gt>>'' string of course). If option B<-a> is used all
lines are selectable and their result is again the line itself, i.e. using
option B<-a> is the same as adding ``C<E<lt>sE<gt>>'' 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 ``C<E<lt>s:result textE<gt>>''
which results in the output ``C<result text>'' when the corresponding line is
selected.
When you use a specific result via ``C<E<lt>s:result textE<gt>>'' the I<result
text> can contain ``C<%[query text]s>'' and ``C<%[query text]S>''
constructs. For every such construct an interactive query is done and the
result replaces the construct. The ``C<%[query text]S>'' construct is like
``C<%[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 F</dev/tty>, because
the F<stdin> and F<stdout> filehandles are usually tied to the input and
output data streams.
=head2 Output Data
The output is the line itself or the string given with ``C<E<lt>s:result
textE<gt>>''. When multiple line selection mode (option B<-m>) is used the
output is all selected lines theirself or their configured result strings.
Output always is written to F<stdout>.
=head1 OPTIONS
=head2 Input Options
These options control how I<iSelect> parses its input.
=over 4
=item B<-d> I<STR>, B<--delimiter=>I<STR>
Sets the delimiters for the selection tags. The default is `C<E<lt>,E<gt>>',
i.e. the selection tags have to read ``C<E<lt>sE<gt>>'' and ``C<E<lt>s:result
textE<gt>>''
=item B<-c>, B<--strip-comments>
Strips all sharp comment lines from the input buffer before parsing.
=item B<-f>, B<--force-browse>
Browse always, i.e. even when the input buffer contains no or only one line.
=item B<-a>, B<--all-select>
Force all lines to be selectable.
=item B<-e>, B<--exit-no-select>
Exit immediately if no lines are selectable. In this case not even the Curses
screen is initialized.
=back
=head2 Display Options
=over 4
=item B<-p> I<NUM>, B<--position=>I<NUM>
Sets the cursor position to line I<NUM>.
=item B<-k> I<KEY>[:I<OKEY>], B<--key=>I<KEY[:I<OKEY>]>
Defines an additional input key. Per default I<OKEY> is C<RETURN>, i.e. for
instance B<-kf> defines another selection key `C<f>'.
=item B<-m>, B<--multi-line>
Enable multi-line selection where you can select more then one line via SPACE
key.
=item B<-n> I<STR>, B<--name=>I<STR>
Sets the name string, displayed flush left at the bottom of the
browser window.
=item B<-t> I<STR>, B<--title=>I<STR>
Sets the title bar string, displayed centered at the bottom of the
browser window.
=back
=head2 Output Options
=over 4
=item B<-S>, B<--strip-result>
Strip all leading and trailing whitespaces from the result string.
=item B<-K>, B<--key-result>
Prefix the result string (given on F<stdout>) with the corresponding selection
key which was used. This usually is C<RETURN> or C<KEY_RIGHT> but can be any
of the additional keys defined by option B<-k>. When you use B<-kf> and
select a line C<Foo Bar> with key `C<f>' the result string is ``C<f:Foo
Bar>''.
=item B<-P>, B<--position-result>
Prefix the result string (given on F<stdout>) with the corresponding cursor
position followed by a colon. When you selected line I<N> and this line has
the result C<Foo Bar> configured the result string is ``C<N:Foo Bar>''.
=item B<-Q> I<STR>, B<--quit-result=>I<STR>
Sets the result string on quit. Default is the empty string.
=back
=head2 Giving Feedback
=over 4
=item B<-V>, B<--version>
Displays version identification string.
=back
=head1 KEYSTROKES
=head2 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
=head2 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)
=head2 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
=head1 EXAMPLE
As an example we present a real-life situation where iSelect can enhance an
existing functionality. We define two Bash functions (for your
F<$HOME/.bashrc> file) which enhance the built-in `F<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 `F<cd>' command is compatible with Bashs built-in variant for the case
where the specified directory actually exists. When it doesn't, the original
`F<cd>' would immediately give an error (assuming we have no F<CDPATH>
variable defined). Here this enhanced version tries harder. First it searches
for such a directory in a previously built (via F<cds>) F<$HOME/.cdpaths>
files. When no line was found, iSelect just returns the given directory as the
default result and `F<cd>' then fails as usual with an error message. When
only one directory was found, iSelect directly results this particular line to
`F<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 `F<cd>'.
For more useful examples on how to use iSelect, see the F<contrib/> directory
of the iSelect distribution tarball.
=head1 AUTHOR
Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com
=head1 SEE ALSO
iSelect Home: http://www.ossp.org/pkg/tool/iselect/
=cut
##EOF##
