Ubuntu Manpage: iSelect -- Interactive Selection Tool

Provided by: iselect_1.4.0-2build1_amd64

NAME

       iSelect -- Interactive Selection Tool

SYNOPSIS

       iselect [-d STR,STR] [-c] [-f] [-a] [-e] [-p NUM] [-k KEY[:OKEY]] [-m] [-n STR] [-t STR] [-S] [-K] [-P]
       [-Q STR] [line1 line2 ...]

       iselect [-V]

VERSION

       1.4.0 (08-Jul-2007)

DESCRIPTION

   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 grep and the
       final executing command). In other words: iSelect was designed to be used for any types of interactice
       line-based selections.

   Input Data
       Input is read either from the command line (line1 line2 ...) where each argument corresponds to one
       buffer line or from 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 ``"<b>"..."</b>"'' as in HTML.

   Selections
       The selection is either just a single line (default) or multiple lines (option -m). Per default no lines
       are selectable. If a line contains the string ``"<s>"'' (or a string with different delimiters configured
       via option -d) at any position this string is stripped and the line is selectable. Its result (printed to
       stdout) is the line contents itself (but without the ``"<s>"'' string of course). If option -a is used
       all lines are selectable and their result is again the line itself, i.e. using option -a is the same as
       adding ``"<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 ``"<s:result text>"'' which results in the
       output ``"result text"'' when the corresponding line is selected.

       When you use a specific result via ``"<s:result text>"'' the result text can contain ``"%[query text]s"''
       and ``"%[query text]S"'' constructs. For every such construct an interactive query is done and the result
       replaces the construct.  The ``"%[query text]S"'' construct is like ``"%[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 /dev/tty, because the stdin and stdout
       filehandles are usually tied to the input and output data streams.

   Output Data
       The output is the line itself or the string given with ``"<s:result text>"''.  When multiple line
       selection mode (option -m) is used the output is all selected lines theirself or their configured result
       strings.  Output always is written to stdout.

OPTIONS

Input Options
These options control how iSelect parses its input.

-d STR, --delimiter=STR
Sets the delimiters for the selection tags. The default is `"<,>"', i.e. the selection tags have to
read ``"<s>"'' and ``"<s:result text>"''

-c, --strip-comments
Strips all sharp comment lines from the input buffer before parsing.

-f, --force-browse
Browse always, i.e. even when the input buffer contains no or only one line.

-a, --all-select
Force all lines to be selectable.

-e, --exit-no-select
Exit immediately if no lines are selectable. In this case not even the Curses screen is initialized.

Display Options
-p NUM, --position=NUM
Sets the cursor position to line NUM.

-k KEY[:OKEY], --key=KEY[:OKEY]
Defines an additional input key. Per default OKEY is "RETURN", i.e. for instance -kf defines another
selection key `"f"'.

-m, --multi-line
Enable multi-line selection where you can select more then one line via SPACE key.

-n STR, --name=STR
Sets the name string, displayed flush left at the bottom of the browser window.

-t STR, --title=STR
Sets the title bar string, displayed centered at the bottom of the browser window.

Output Options
-S, --strip-result
Strip all leading and trailing whitespaces from the result string.

-K, --key-result
Prefix the result string (given on stdout) with the corresponding selection key which was used. This
usually is "RETURN" or "KEY_RIGHT" but can be any of the additional keys defined by option -k. When
you use -kf and select a line "Foo Bar" with key `"f"' the result string is ``"f:Foo Bar"''.

-P, --position-result
Prefix the result string (given on stdout) with the corresponding cursor position followed by a
colon. When you selected line N and this line has the result "Foo Bar" configured the result string
is ``"N:Foo Bar"''.

-Q STR, --quit-result=STR
Sets the result string on quit. Default is the empty string.

Giving Feedback
-V, --version
Displays version identification string.

KEYSTROKES

   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

   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)

   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

EXAMPLE

       As an example we present a real-life situation where iSelect can enhance an  existing  functionality.  We
       define  two  Bash  functions (for your $HOME/.bashrc file) which enhance the built-in `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 `cd' command is compatible with  Bashs  built-in  variant  for  the  case  where  the  specified
       directory  actually  exists. When it doesn't, the original `cd' would immediately give an error (assuming
       we have no CDPATH variable defined).  Here this enhanced version tries harder. First it searches for such
       a directory in a previously built (via cds) $HOME/.cdpaths files. When no line was  found,  iSelect  just
       returns  the  given  directory  as the default result and `cd' then fails as usual with an error message.
       When only one directory was found, iSelect directly results this particular line to `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 `cd'.

       For more useful examples on how to use iSelect, see the contrib/ directory of  the  iSelect  distribution
       tarball.

AUTHOR

         Ralf S. Engelschall
         rse@engelschall.com
         www.engelschall.com