##      _ ____       _           _   
##     (_) ___|  ___| | ___  ___| |_ 
##    / /\___ \ / _ \ |/ _ \/ __| __|
##   / /  ___) |  __/ |  __/ (__| |_ 
##  (_(  |____/ \___|_|\___|\___|\__|
##
##  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) 1996,1997,1998 Ralf S. Engelschall.
##
##  This program is free software; it may be redistributed and/or modified
##  only under the terms of either the Artistic License or the GNU General
##  Public License, which may be found in the ePerl source distribution.
##  Look at the files ARTISTIC and COPYING or run ``eperl -l'' to receive
##  a built-in copy of both license files.
##
##  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 either the
##  Artistic License or the GNU General Public License for more details.
##
##  ======================================================================
##
##  iselect.pod -- manual page 
##

=head1 NAME

iSelect -- Interactive Selection Tool

=head1 SYNOPSIS

B<iselect>
[B<-c>]
[B<-f>]
[B<-a>]
[B<-e>]
[B<-p> I<NUM>]
[B<-m>]
[B<-n> I<STR>]
[B<-t> I<STR>]
[B<-S>]
[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. 

=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<%%S%%>'' 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<%%S%%>'' 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<%%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 ``C<%%S:result text%%>'' which results in the
output ``C<result text>'' when the corresponding line is selected.

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<%%S:...%%>''.  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<-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<-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<-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.engelschall.com/sw/iselect/

=cut

##EOF##