head	1.6;
access;
symbols
	ISELECT_1_4_0:1.6
	ISELECT_1_3_1:1.5
	ISELECT_1_3_0:1.4
	ISELECT_1_2_0:1.1.1.4
	ISELECT_1_1_0:1.1.1.3
	ISELECT_1_0_4:1.1.1.2
	ISELECT_1_0_0:1.1.1.1
	vendor:1.1.1;
locks; strict;
comment	@# @;


1.6
date	2007.07.08.09.28.11;	author rse;	state Exp;
branches;
next	1.5;
commitid	P0IqEKWWbsvcIWos;

1.5
date	2005.10.05.18.19.42;	author rse;	state Exp;
branches;
next	1.4;

1.4
date	2004.09.11.15.22.32;	author rse;	state Exp;
branches;
next	1.3;

1.3
date	2004.09.11.15.18.49;	author rse;	state Exp;
branches;
next	1.2;

1.2
date	2000.07.25.11.44.00;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	97.09.17.07.45.31;	author rse;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	97.09.17.07.45.31;	author rse;	state Exp;
branches;
next	1.1.1.2;

1.1.1.2
date	98.01.03.09.08.52;	author rse;	state Exp;
branches;
next	1.1.1.3;

1.1.1.3
date	98.04.05.16.25.30;	author rse;	state Exp;
branches;
next	1.1.1.4;

1.1.1.4
date	99.03.31.06.47.45;	author rse;	state Exp;
branches;
next	;


desc
@@


1.6
log
@bump up version and copyright information
@
text
@##      _ ____       _           _   
##     (_) ___|  ___| | ___  ___| |_ 
##    / /\___ \ / _ \ |/ _ \/ __| __|
##   / /  ___) |  __/ |  __/ (__| |_ 
##  (_(  |____/ \___|_|\___|\___|\__|
##
##  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##
@


1.5
log
@adjust copyright yearW
@
text
@d14 1
a14 1
##  Copyright (c) 1997-2005 Ralf S. Engelschall.
@


1.4
log
@update URLs
@
text
@d14 1
a14 1
##  Copyright (c) 1997-2004 Ralf S. Engelschall.
@


1.3
log
@modernize source tree
@
text
@d299 1
a299 1
  iSelect Home: http://www.engelschall.com/sw/iselect/
@


1.2
log
@Merge in pending changes
@
text
@d14 1
a14 1
##  Copyright (c) 1996-1999 Ralf S. Engelschall.
@


1.1
log
@Initial revision
@
text
@d14 1
a14 1
##  Copyright (c) 1996,1997 Ralf S. Engelschall, All rights reserved.
d16 9
a24 10
##  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.
d38 1
a38 2
[B<-p> I<NUM>]
[B<-t> I<STRING>]
d40 1
a40 2
[B<-w>]
[B<-l>]
d42 3
a44 1
[B<-s>]
d46 7
a52 3
[B<-d> I<STRING>]
[B<-e>]
[I<STRING> ...]
d63 52
a114 2
iSelect is a Curses-based tool for interactive line selection 
in an ASCII file via a full-screen terminal session.
d118 33
d157 4
a160 1
=item B<-t> I<STRING>, B<--title=>I<STRING>
d162 8
a169 1
Sets the title bar string, displayed at the buttom of the
d172 1
a172 1
=item B<-c>, B<--comment-strip>
d174 2
a175 1
Strips all sharp comment lines from the input buffer before parsing.
d177 1
a177 1
=item B<-w>, B<--whitespace-strip>
d179 1
a179 1
Strips all leading and trailing whitespaces from the result string.
d181 1
a181 1
=item B<-l>, B<--line-prefix>
d183 1
a183 1
Prefix the result with the line number followed by a ':'.
d185 1
a185 1
=item B<-a>, B<--browse-always>
d187 1
a187 2
Browse always, i.e. even when the input buffer contains no or
only one line.
d189 5
a193 1
=item B<-m>, B<--multi-select>
d195 1
a195 2
Enable multi-line selection where you can select more then one line via SPACE
key.
d197 3
a199 1
=item B<-s>, B<--all-selectable>
d201 1
a201 1
Force all lines to be selectable.
d203 1
a203 1
=item B<-d>, B<--abort-string=>I<STRING>
d205 1
a205 1
Sets the abort string. Default is no result.
d207 1
a207 1
=item B<-e>, B<--exit-noselectable>
d209 1
a209 1
Exit immediately if no lines are selectable.
d217 74
d297 1
a297 1
=head1 SEEALSO
d299 1
a299 1
ncurses(3)
@


1.1.1.1
log
@Import iSelect 1.0.0
@
text
@@


1.1.1.2
log
@Import iSelect 1.0.4
@
text
@d14 1
a14 1
##  Copyright (c) 1996,1997,1998 Ralf S. Engelschall.
d39 2
d42 2
a43 1
[B<-f>]
d45 3
d49 1
a49 8
[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> ...]
d60 2
a61 39
=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>.
a64 4
=head2 Input Options

These options control how I<iSelect> parses its input.

d67 1
a67 1
=item B<-c>, B<--strip-comments>
d69 1
a69 1
Strips all sharp comment lines from the input buffer before parsing.
d71 1
a71 1
=item B<-f>, B<--force-browse>
d73 2
a74 1
Browse always, i.e. even when the input buffer contains no or only one line.
d76 1
a76 1
=item B<-a>, B<--all-select>
d78 1
a78 1
Force all lines to be selectable.
d80 1
a80 1
=item B<-e>, B<--exit-no-select>
d82 1
a82 4
Exit immediately if no lines are selectable. In this case not even the Curses
screen is initialized.

=back
d84 1
a84 1
=head2 Display Options
d86 1
a86 1
=over 4
d88 1
a88 1
=item B<-p> I<NUM>, B<--position=>I<NUM>
d90 2
a91 1
Sets the cursor position to line I<NUM>.
d93 1
a93 1
=item B<-m>, B<--multi-line>
d98 1
a98 1
=item B<-n> I<STR>, B<--name=>I<STR>
d100 1
a100 2
Sets the name string, displayed flush left at the bottom of the
browser window.
d102 1
a102 1
=item B<-t> I<STR>, B<--title=>I<STR>
d104 1
a104 18
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>''.
d106 1
a106 1
=item B<-Q> I<STR>, B<--quit-result=>I<STR>
d108 1
a108 7
Sets the result string on quit. Default is the empty string.

=back

=head2 Giving Feedback

=over 4
a115 74
=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.

d122 1
a122 1
=head1 SEE ALSO
d124 1
a124 1
  iSelect Home: http://www.engelschall.com/sw/iselect/
@


1.1.1.3
log
@Import iSelect 1.1.0
@
text
@a38 1
[B<-d> I<STR>,I<STR>]
a43 1
[B<-k> I<KEY>[:I<OKEY>]]
a47 1
[B<-K>]
a76 4
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.

d81 1
a81 2
``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
d83 6
a88 14
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<%s[query text]s>'' and ``C<%s[query text]S>''
constructs. For every such construct an interactive query is done and the
result replaces the construct.  The ``C<%s[query text]S>'' construct is like
``C<%s[query text]s>'' except that the empty string as the query result is not
accepted on input.
d96 4
a99 4
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>.
a108 6
=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>>''

a135 5
=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>'.

a159 8

=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>''.
@


1.1.1.4
log
@Import iSelect 1.2.0
@
text
@d14 1
a14 1
##  Copyright (c) 1996-1999 Ralf S. Engelschall.
d16 10
a25 9
##  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.
@