.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ISELECT 1"
.TH ISELECT 1 "2004-09-11" "EN" "Ralf S. Engelschall"
.SH "NAME"
iSelect \-\- Interactive Selection Tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBiselect\fR
[\fB\-d\fR \fI\s-1STR\s0\fR,\fI\s-1STR\s0\fR]
[\fB\-c\fR]
[\fB\-f\fR]
[\fB\-a\fR]
[\fB\-e\fR]
[\fB\-p\fR \fI\s-1NUM\s0\fR]
[\fB\-k\fR \fI\s-1KEY\s0\fR[:\fI\s-1OKEY\s0\fR]]
[\fB\-m\fR]
[\fB\-n\fR \fI\s-1STR\s0\fR]
[\fB\-t\fR \fI\s-1STR\s0\fR]
[\fB\-S\fR]
[\fB\-K\fR]
[\fB\-P\fR]
[\fB\-Q\fR \fI\s-1STR\s0\fR]
[\fIline1\fR \fIline2\fR ...]
.PP
\&\fBiselect\fR
[\fB\-V\fR]
.SH "VERSION"
.IX Header "VERSION"
1.3.0 (11\-Sep\-2004)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Sh "Intend"
.IX Subsection "Intend"
iSelect is an interactive line selection tool for \s-1ASCII\s0 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 \fIgrep\fR
and the final executing command). In other words: iSelect was designed to be
used for any types of interactice line-based selections.
.Sh "Input Data"
.IX Subsection "Input Data"
Input is read either from the command line (\fIline1\fR \fIline2\fR ...) where each
argument corresponds to one buffer line or from \fIstdin\fR (when no arguments
are given) where the buffer lines are determined according to the newline
characters. 
.PP
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 ``\f(CW\*(C`<b>\*(C'\fR...\f(CW\*(C`</b>\*(C'\fR'' as in \s-1HTML\s0.
.Sh "Selections"
.IX Subsection "Selections"
The selection is either just a single line (default) or multiple lines (option
\&\fB\-m\fR). Per default no lines are selectable. If a line contains the string
``\f(CW\*(C`<s>\*(C'\fR'' (or a string with different delimiters configured via
option \fB\-d\fR) at any position this string is stripped and the line is
selectable. Its result (printed to \fIstdout\fR) is the line contents itself (but
without the ``\f(CW\*(C`<s>\*(C'\fR'' string of course). If option \fB\-a\fR is used all
lines are selectable and their result is again the line itself, i.e. using
option \fB\-a\fR is the same as adding ``\f(CW\*(C`<s>\*(C'\fR'' 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 ``\f(CW\*(C`<s:result text>\*(C'\fR''
which results in the output ``\f(CW\*(C`result text\*(C'\fR'' when the corresponding line is
selected.
.PP
When you use a specific result via ``\f(CW\*(C`<s:result text>\*(C'\fR'' the \fIresult
text\fR can contain ``\f(CW\*(C`%[query text]s\*(C'\fR'' and ``\f(CW\*(C`%[query text]S\*(C'\fR''
constructs. For every such construct an interactive query is done and the
result replaces the construct.  The ``\f(CW\*(C`%[query text]S\*(C'\fR'' construct is like
``\f(CW\*(C`%[query text]s\*(C'\fR'' except that the empty string as the query result is not
accepted on input.
.PP
The Curses-based full-screen selection is always done via \fI/dev/tty\fR, because
the \fIstdin\fR and \fIstdout\fR filehandles are usually tied to the input and
output data streams.
.Sh "Output Data"
.IX Subsection "Output Data"
The output is the line itself or the string given with ``\f(CW\*(C`<s:result
text>\*(C'\fR''.  When multiple line selection mode (option \fB\-m\fR) is used the
output is all selected lines theirself or their configured result strings.
Output always is written to \fIstdout\fR.
.SH "OPTIONS"
.IX Header "OPTIONS"
.Sh "Input Options"
.IX Subsection "Input Options"
These options control how \fIiSelect\fR parses its input.
.IP "\fB\-d\fR \fI\s-1STR\s0\fR, \fB\-\-delimiter=\fR\fI\s-1STR\s0\fR" 4
.IX Item "-d STR, --delimiter=STR"
Sets the delimiters for the selection tags. The default is `\f(CW\*(C`<,>\*(C'\fR',
i.e. the selection tags have to read ``\f(CW\*(C`<s>\*(C'\fR'' and ``\f(CW\*(C`<s:result
text>\*(C'\fR''
.IP "\fB\-c\fR, \fB\-\-strip\-comments\fR" 4
.IX Item "-c, --strip-comments"
Strips all sharp comment lines from the input buffer before parsing.
.IP "\fB\-f\fR, \fB\-\-force\-browse\fR" 4
.IX Item "-f, --force-browse"
Browse always, i.e. even when the input buffer contains no or only one line.
.IP "\fB\-a\fR, \fB\-\-all\-select\fR" 4
.IX Item "-a, --all-select"
Force all lines to be selectable.
.IP "\fB\-e\fR, \fB\-\-exit\-no\-select\fR" 4
.IX Item "-e, --exit-no-select"
Exit immediately if no lines are selectable. In this case not even the Curses
screen is initialized.
.Sh "Display Options"
.IX Subsection "Display Options"
.IP "\fB\-p\fR \fI\s-1NUM\s0\fR, \fB\-\-position=\fR\fI\s-1NUM\s0\fR" 4
.IX Item "-p NUM, --position=NUM"
Sets the cursor position to line \fI\s-1NUM\s0\fR.
.IP "\fB\-k\fR \fI\s-1KEY\s0\fR[:\fI\s-1OKEY\s0\fR], \fB\-\-key=\fR\fIKEY[:\fI\s-1OKEY\s0\fI]\fR" 4
.IX Item "-k KEY[:OKEY], --key=KEY[:OKEY]"
Defines an additional input key. Per default \fI\s-1OKEY\s0\fR is \f(CW\*(C`RETURN\*(C'\fR, i.e.  for
instance \fB\-kf\fR defines another selection key `\f(CW\*(C`f\*(C'\fR'.
.IP "\fB\-m\fR, \fB\-\-multi\-line\fR" 4
.IX Item "-m, --multi-line"
Enable multi-line selection where you can select more then one line via \s-1SPACE\s0
key.
.IP "\fB\-n\fR \fI\s-1STR\s0\fR, \fB\-\-name=\fR\fI\s-1STR\s0\fR" 4
.IX Item "-n STR, --name=STR"
Sets the name string, displayed flush left at the bottom of the
browser window.
.IP "\fB\-t\fR \fI\s-1STR\s0\fR, \fB\-\-title=\fR\fI\s-1STR\s0\fR" 4
.IX Item "-t STR, --title=STR"
Sets the title bar string, displayed centered at the bottom of the
browser window.
.Sh "Output Options"
.IX Subsection "Output Options"
.IP "\fB\-S\fR, \fB\-\-strip\-result\fR" 4
.IX Item "-S, --strip-result"
Strip all leading and trailing whitespaces from the result string.
.IP "\fB\-K\fR, \fB\-\-key\-result\fR" 4
.IX Item "-K, --key-result"
Prefix the result string (given on \fIstdout\fR) with the corresponding selection
key which was used. This usually is \f(CW\*(C`RETURN\*(C'\fR or \f(CW\*(C`KEY_RIGHT\*(C'\fR but can be any
of the additional keys defined by option \fB\-k\fR.  When you use \fB\-kf\fR and
select a line \f(CW\*(C`Foo Bar\*(C'\fR with key `\f(CW\*(C`f\*(C'\fR' the result string is ``\f(CW\*(C`f:Foo
Bar\*(C'\fR''.
.IP "\fB\-P\fR, \fB\-\-position\-result\fR" 4
.IX Item "-P, --position-result"
Prefix the result string (given on \fIstdout\fR) with the corresponding cursor
position followed by a colon. When you selected line \fIN\fR and this line has
the result \f(CW\*(C`Foo Bar\*(C'\fR configured the result string is ``\f(CW\*(C`N:Foo Bar\*(C'\fR''.
.IP "\fB\-Q\fR \fI\s-1STR\s0\fR, \fB\-\-quit\-result=\fR\fI\s-1STR\s0\fR" 4
.IX Item "-Q STR, --quit-result=STR"
Sets the result string on quit. Default is the empty string.
.Sh "Giving Feedback"
.IX Subsection "Giving Feedback"
.IP "\fB\-V\fR, \fB\-\-version\fR" 4
.IX Item "-V, --version"
Displays version identification string.
.SH "KEYSTROKES"
.IX Header "KEYSTROKES"
.Sh "Cursor Movement"
.IX Subsection "Cursor Movement"
Use these to browse through the selection list.
.PP
.Vb 6
\&  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
.Ve
.Sh "Line Selection"
.IX Subsection "Line Selection"
Use these to select one line and exit in standard mode or one or more lines in
multi-line mode.
.PP
.Vb 3
\&  RETURN ........ Select line and exit
\&  CURSOR-RIGHT .. Select line and exit
\&  SPACE ......... Select line and stay (multi-line mode only)
.Ve
.Sh "Others"
.IX Subsection "Others"
Use these to quit iSelect or to show its help and
version page.
.PP
.Vb 4
\&  q ............. Quit (exit without selection)
\&  CURSOR-LEFT ... Quit (exit without selection)
\&  h ............. Help Page
\&  v ............. Version Page
.Ve
.SH "EXAMPLE"
.IX Header "EXAMPLE"
As an example we present a real-life situation where iSelect can enhance an
existing functionality. We define two Bash functions (for your
\&\fI$HOME/.bashrc\fR file) which enhance the built-in `\fIcd\fR' command of the
shell.
.PP
.Vb 7
\& #   database scan for enhanced cd command
\& cds () {
\&     (cd $HOME; 
\&      find . -type d -print |\e
\&      sed -e "s;^\e.;$HOME;" |\e
\&      sort -u >$HOME/.cdpaths ) &
\& }
.Ve
.PP
.Vb 11
\& #   definition of the enhanced cd command
\& cd () {
\&     if [ -d $1 ]; then
\&          builtin cd $1
\&     else
\&          builtin cd `egrep "/$1[^/]*$" $HOME/.cdpaths |\e
\&                      iselect -a -Q $1 -n "chdir" \e
\&                              -t "Change Directory to..."` 
\&     fi
\&     PS1="\eu@\eh:$PWD\en:> "
\& }
.Ve
.PP
This new `\fIcd\fR' command is compatible with Bashs built-in variant for the case
where the specified directory actually exists. When it doesn't, the original
`\fIcd\fR' would immediately give an error (assuming we have no \fI\s-1CDPATH\s0\fR
variable defined).  Here this enhanced version tries harder. First it searches
for such a directory in a previously built (via \fIcds\fR) \fI$HOME/.cdpaths\fR
files. When no line was found, iSelect just returns the given directory as the
default result and `\fIcd\fR' then fails as usual with an error message. When
only one directory was found, iSelect directly results this particular line to
`\fIcd\fR'. 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 `\fIcd\fR'.
.PP
For more useful examples on how to use iSelect, see the \fIcontrib/\fR directory
of the iSelect distribution tarball.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\&  Ralf S. Engelschall
\&  rse@engelschall.com
\&  www.engelschall.com
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\&  iSelect Home: http://www.ossp.org/pkg/tool/iselect/
.Ve