ISELECT(1)

🎀 NAME 🎀

iselect(1) — Interactive Selection Tool 💖

Okay so bestie, this is iselect(1), the interactive selection tool. Slay.

✨ 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 🦋

The version identification string is @V@. Periodt.

🌸 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 a 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 interactive line-based selections. Literally its whole thing.

📥 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 be 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. No cap, that's the bold-mode glow-up.

🎯 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 "%s[query text]s" and "%s[query text]S" constructs. For every such construct an interactive query is done and the result replaces the construct. The "%s[query text]S" construct is like "%s[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. Main character energy: the UI gets its own terminal.

📤 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 themselves or their configured result strings. Output is always 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 than 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 Bash's 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 than 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. Vibe check: passed.

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

📜 COPYRIGHT 📜

Copyright (c) 1996-1999 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.

🌈 SEE ALSO 🌈

iSelect Home: http://www.engelschall.com/sw/iselect/

---

✨ That's the whole vibe, bestie. Source/version: EN Tools; date: 1980-01-01; manual: ISELECT(1). Go slay a selection 💅💖