1## _ ____ _ _ 2## (_) ___| ___| | ___ ___| |_ 3## / /\___ \ / _ \ |/ _ \/ __| __| 4## / / ___) | __/ | __/ (__| |_ 5## (_( |____/ \___|_|\___|\___|\__| 6## 7## iSelect -- Interactive Selection Tool 8## 9## iSelect is a Curses-based tool for interactive line selection 10## in an ASCII file via a full-screen terminal session. 11## 12## ====================================================================== 13## 14## Copyright (c) 1997-2007 Ralf S. Engelschall. 15## 16## This program is free software; it may be redistributed and/or 17## modified only under the terms of the GNU General Public License, 18## which may be found in the iSelect source distribution. 19## Look at the file COPYING for details. 20## 21## This program is distributed in the hope that it will be useful, 22## but WITHOUT ANY WARRANTY; without even the implied warranty of 23## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 24## See the the GNU General Public License for more details. 25## 26## ====================================================================== 27## 28## iselect.pod -- manual page 29## 30 31=head1 NAME 32 33iSelect -- Interactive Selection Tool 34 35=head1 SYNOPSIS 36 37B<iselect> 38[B<-d> I<STR>,I<STR>] 39[B<-c>] 40[B<-f>] 41[B<-a>] 42[B<-e>] 43[B<-p> I<NUM>] 44[B<-k> I<KEY>[:I<OKEY>]] 45[B<-m>] 46[B<-n> I<STR>] 47[B<-t> I<STR>] 48[B<-S>] 49[B<-K>] 50[B<-P>] 51[B<-Q> I<STR>] 52[I<line1> I<line2> ...] 53 54B<iselect> 55[B<-V>] 56 57=head1 VERSION 58 59@V@ 60 61=head1 DESCRIPTION 62 63=head2 Intend 64 65iSelect is an interactive line selection tool for ASCII files, operating via a 66full-screen Curses-based terminal session. It can be used either as an user 67interface frontend controlled by a Bourne-Shell, Perl or other type of script 68backend as its wrapper or in batch as a pipe filter (usually between F<grep> 69and the final executing command). In other words: iSelect was designed to be 70used for any types of interactice line-based selections. 71 72=head2 Input Data 73 74Input is read either from the command line (I<line1> I<line2> ...) where each 75argument corresponds to one buffer line or from F<stdin> (when no arguments 76are given) where the buffer lines are determined according to the newline 77characters. 78 79You can additionally let substrings displayed in Bold mode for non-selectable 80lines (because the selectable lines are always displayed bold) by using the 81construct ``C<E<lt>bE<gt>>...C<E<lt>/bE<gt>>'' as in HTML. 82 83=head2 Selections 84 85The selection is either just a single line (default) or multiple lines (option 86B<-m>). Per default no lines are selectable. If a line contains the string 87``C<E<lt>sE<gt>>'' (or a string with different delimiters configured via 88option B<-d>) at any position this string is stripped and the line is 89selectable. Its result (printed to F<stdout>) is the line contents itself (but 90without the ``C<E<lt>sE<gt>>'' string of course). If option B<-a> is used all 91lines are selectable and their result is again the line itself, i.e. using 92option B<-a> is the same as adding ``C<E<lt>sE<gt>>'' to every line of the 93input data. When you want a specific result (i.e. not just the line contents 94itself), you have to use the special variant ``C<E<lt>s:result textE<gt>>'' 95which results in the output ``C<result text>'' when the corresponding line is 96selected. 97 98When you use a specific result via ``C<E<lt>s:result textE<gt>>'' the I<result 99text> can contain ``C<%[query text]s>'' and ``C<%[query text]S>'' 100constructs. For every such construct an interactive query is done and the 101result replaces the construct. The ``C<%[query text]S>'' construct is like 102``C<%[query text]s>'' except that the empty string as the query result is not 103accepted on input. 104 105The Curses-based full-screen selection is always done via F</dev/tty>, because 106the F<stdin> and F<stdout> filehandles are usually tied to the input and 107output data streams. 108 109=head2 Output Data 110 111The output is the line itself or the string given with ``C<E<lt>s:result 112textE<gt>>''. When multiple line selection mode (option B<-m>) is used the 113output is all selected lines theirself or their configured result strings. 114Output always is written to F<stdout>. 115 116=head1 OPTIONS 117 118=head2 Input Options 119 120These options control how I<iSelect> parses its input. 121 122=over 4 123 124=item B<-d> I<STR>, B<--delimiter=>I<STR> 125 126Sets the delimiters for the selection tags. The default is `C<E<lt>,E<gt>>', 127i.e. the selection tags have to read ``C<E<lt>sE<gt>>'' and ``C<E<lt>s:result 128textE<gt>>'' 129 130=item B<-c>, B<--strip-comments> 131 132Strips all sharp comment lines from the input buffer before parsing. 133 134=item B<-f>, B<--force-browse> 135 136Browse always, i.e. even when the input buffer contains no or only one line. 137 138=item B<-a>, B<--all-select> 139 140Force all lines to be selectable. 141 142=item B<-e>, B<--exit-no-select> 143 144Exit immediately if no lines are selectable. In this case not even the Curses 145screen is initialized. 146 147=back 148 149=head2 Display Options 150 151=over 4 152 153=item B<-p> I<NUM>, B<--position=>I<NUM> 154 155Sets the cursor position to line I<NUM>. 156 157=item B<-k> I<KEY>[:I<OKEY>], B<--key=>I<KEY[:I<OKEY>]> 158 159Defines an additional input key. Per default I<OKEY> is C<RETURN>, i.e. for 160instance B<-kf> defines another selection key `C<f>'. 161 162=item B<-m>, B<--multi-line> 163 164Enable multi-line selection where you can select more then one line via SPACE 165key. 166 167=item B<-n> I<STR>, B<--name=>I<STR> 168 169Sets the name string, displayed flush left at the bottom of the 170browser window. 171 172=item B<-t> I<STR>, B<--title=>I<STR> 173 174Sets the title bar string, displayed centered at the bottom of the 175browser window. 176 177=back 178 179=head2 Output Options 180 181=over 4 182 183=item B<-S>, B<--strip-result> 184 185Strip all leading and trailing whitespaces from the result string. 186 187=item B<-K>, B<--key-result> 188 189Prefix the result string (given on F<stdout>) with the corresponding selection 190key which was used. This usually is C<RETURN> or C<KEY_RIGHT> but can be any 191of the additional keys defined by option B<-k>. When you use B<-kf> and 192select a line C<Foo Bar> with key `C<f>' the result string is ``C<f:Foo 193Bar>''. 194 195=item B<-P>, B<--position-result> 196 197Prefix the result string (given on F<stdout>) with the corresponding cursor 198position followed by a colon. When you selected line I<N> and this line has 199the result C<Foo Bar> configured the result string is ``C<N:Foo Bar>''. 200 201=item B<-Q> I<STR>, B<--quit-result=>I<STR> 202 203Sets the result string on quit. Default is the empty string. 204 205=back 206 207=head2 Giving Feedback 208 209=over 4 210 211=item B<-V>, B<--version> 212 213Displays version identification string. 214 215=back 216 217=head1 KEYSTROKES 218 219=head2 Cursor Movement 220 221Use these to browse through the selection list. 222 223 CURSOR-UP ..... Move cursor one line up 224 CURSOR-DOWN ... Move cursor one line down 225 PAGE-UP ....... Move cursor one page up 226 PAGE-DOWN ..... Move cursor one page down 227 g ............. Goto first line 228 G ............. Goto last line 229 230=head2 Line Selection 231 232Use these to select one line and exit in standard mode or one or more lines in 233multi-line mode. 234 235 RETURN ........ Select line and exit 236 CURSOR-RIGHT .. Select line and exit 237 SPACE ......... Select line and stay (multi-line mode only) 238 239=head2 Others 240 241Use these to quit iSelect or to show its help and 242version page. 243 244 q ............. Quit (exit without selection) 245 CURSOR-LEFT ... Quit (exit without selection) 246 h ............. Help Page 247 v ............. Version Page 248 249=head1 EXAMPLE 250 251As an example we present a real-life situation where iSelect can enhance an 252existing functionality. We define two Bash functions (for your 253F<$HOME/.bashrc> file) which enhance the built-in `F<cd>' command of the 254shell. 255 256 # database scan for enhanced cd command 257 cds () { 258 (cd $HOME; 259 find . -type d -print |\ 260 sed -e "s;^\.;$HOME;" |\ 261 sort -u >$HOME/.cdpaths ) & 262 } 263 264 # definition of the enhanced cd command 265 cd () { 266 if [ -d $1 ]; then 267 builtin cd $1 268 else 269 builtin cd `egrep "/$1[^/]*$" $HOME/.cdpaths |\ 270 iselect -a -Q $1 -n "chdir" \ 271 -t "Change Directory to..."` 272 fi 273 PS1="\u@\h:$PWD\n:> " 274 } 275 276This new `F<cd>' command is compatible with Bashs built-in variant for the case 277where the specified directory actually exists. When it doesn't, the original 278`F<cd>' would immediately give an error (assuming we have no F<CDPATH> 279variable defined). Here this enhanced version tries harder. First it searches 280for such a directory in a previously built (via F<cds>) F<$HOME/.cdpaths> 281files. When no line was found, iSelect just returns the given directory as the 282default result and `F<cd>' then fails as usual with an error message. When 283only one directory was found, iSelect directly results this particular line to 284`F<cd>'. And only when more then one directory was found, iSelect opens its 285Curses-based selection screen and lets the user choose interactively between 286those directories. The chosen directory is then finally given to `F<cd>'. 287 288For more useful examples on how to use iSelect, see the F<contrib/> directory 289of the iSelect distribution tarball. 290 291=head1 AUTHOR 292 293 Ralf S. Engelschall 294 rse@engelschall.com 295 www.engelschall.com 296 297=head1 SEE ALSO 298 299 iSelect Home: http://www.ossp.org/pkg/tool/iselect/ 300 301=cut 302 303##EOF## 304