packages icon



 ISELECT(1)                          EN                           ISELECT(1)
 Ralf S. Engelschall                                     Ralf S. Engelschall

                                 2007-07-08



 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.




                                    - 1 -          Formatted:  June 23, 2024






 ISELECT(1)                          EN                           ISELECT(1)
 Ralf S. Engelschall                                     Ralf S. Engelschall

                                 2007-07-08



      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]



                                    - 2 -          Formatted:  June 23, 2024






 ISELECT(1)                          EN                           ISELECT(1)
 Ralf S. Engelschall                                     Ralf S. Engelschall

                                 2007-07-08



          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.







                                    - 3 -          Formatted:  June 23, 2024






 ISELECT(1)                          EN                           ISELECT(1)
 Ralf S. Engelschall                                     Ralf S. Engelschall

                                 2007-07-08



        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 ) &
       }














                                    - 4 -          Formatted:  June 23, 2024






 ISELECT(1)                          EN                           ISELECT(1)
 Ralf S. Engelschall                                     Ralf S. Engelschall

                                 2007-07-08



       #   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

 SEE ALSO
        iSelect Home: http://www.ossp.org/pkg/tool/iselect/

















                                    - 5 -          Formatted:  June 23, 2024