ISELECT(1)

✨ ISELECT(1) — the interactive selection tool bestie 💅

okay so you're about to meet iselect, and honestly? she's the main character of your shell scripts. this is the manual page for her, from the Ralf S. Engelschall era of the ossp-iselect project, and we're gonna walk through every single bit of it together, no skips, no cap 🫶

---

🌸 NAME 🌸

iSelect — the Interactive Selection Tool 🎀

---

✨ SYNOPSIS ✨

iselect [-d beg,end] [-cfae] [-p linenum] [-k key[:okey]] [-m] [-n name]
        [-t title] [-SKP] [-Q fallback] line…
iselect [-d beg,end] [-cfae] [-p linenum] [-k key[:okey]] [-m] [-n name]
        [-t title] [-SKP] [-Q fallback] < lines
iselect -V|-h

like, three whole ways to summon her. pick your vibe 💖

---

🦋 DESCRIPTION 🦋

💭 Intent

so iSelect is an interactive line selection tool, and she runs inside a full-screen Curses-based terminal session. iconic behavior, truly.

she can be used either as:

• a user interface frontend that's controlled by the shell, by Perl, or by some other type of script backend acting as her wrapper, or
• in batch, as a pipe filter (usually wedged right between grep and the final executing command).

in other words: iSelect was designed to be used for any type of interactive line-based selection. periodt. 👑

📥 Input Data

if you give her no arguments, lines are read from the standard input stream. otherwise, the lines are used directly.

each selectable line is fully bold. parts of other lines can be set in bold too, by wrapping them in <b>...</b>. yes bestie, that's real markup, go off 💅

✅ Selections

by default, a single line may be chosen; with -m you can select multiple lines.

by default, only lines containing the tag <s> may be selected (or with different delimiters set via -d). -a lets you select all lines, but heads up — the tag is always removed regardless.

selected lines get written to the standard output stream.

the tag has a variant that looks like <s:result text>, which — instead of writing the line itself — writes result text. every format specifier in the form %[prompt string]s or %[prompt string]S in the output gets replaced by a line entered in an interactive prompt. the lowercase s variant allows empty responses; the uppercase S doesn't. no free passes, S said what she said 😤

---

🎀 OPTIONS 🎀

📥 Input Options

• -d beg,end, --delimiter=beg,end — sets the delimiters for the selection tags. the default is < and >, so the selection tags have to read <s> and <s:result text>.
• -c, --strip-comments — discard input lines starting with #.
• -f, --force-browse — open the full-screen browser even if input contains less than <2 lines. (this may happen anyway if a %[prompt]s needs to be substituted.)
• -a, --all-select — force all lines to be selectable. <s> tags are still removed.
• -e, --exit-no-select — exit immediately if no lines are selectable.

👀 Display Options

• -p, --position=linenum — sets the cursor position to the 1-based line number.
• -k, --key=key:okey — maps key to okey. both may be either a printable character or one of SPACE, RETURN, KEY_UP (↑), KEY_DOWN (↓), KEY_LEFT (←), KEY_RIGHT (→), KEY_PPAGE (PgUp), KEY_NPAGE (PgDn). this can be given any number of times, and is applied in order.
• -k, --key=key — same as -k key:RETURN. for example, -k f lets you use f to confirm the selection.
• -m, --multi-line — allow selecting more than one line with Space. (as written: with Space.)
• -n, --name=name — changes the string displayed flush left at the bottom of the browser window from "iSelect".
• -t, --title=title — sets the file ..., displayed centered at the bottom of the browser window.

📤 Output Options

• -S, --strip-result — strip all leading and trailing whitespace from the result string.
• -K, --key-result — prefix each result with the key used to confirm the selection. this is usually "RETURN" or "KEY_RIGHT", but in the presence of -k, this is the (unmapped) key; thus, with -k f, selecting line Foo Bar by pressing f yields f:Foo Bar. a Space is rendered as a literal space, not as "SPACE".
• -P, --position-result — prefix each result with its 1-based line number in the buffer.
• -Q, --quit-result=fallback — write fallback to the standard output stream when quitting.

💬 Giving Feedback

• -V, --version — write the version and licence information to the standard output stream, exit 0.
• -h, --help — write the usage string information to the standard error stream, exit 0.

---

⌨️ 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)
C ............. Clear current marks  (multi-line mode only)

🌈 Others

use these to quit iSelect or to show the help or version pages:

q ............. Quit (exit without selection)
CURSOR-LEFT ... Quit (exit without selection)
h ............. Help Page
v ............. Version Page

---

📁 FILES 📁

the Curses session is always opened on /dev/tty, because the standard I/O streams are usually tied to pipes. she needs her own little stage, bestie 🎭

---

🚦 EXIT STATUS 🚦

• 0 — if a selection was made, a selection wasn't made, or succumbed to SIGINT or SIGTERM.
• 1 — if an unknown [o]key was given or an I/O error occurred.

---

🌟 EXAMPLES 🌟

as an example we present a real-life situation where iSelect can enhance existing functionality. we define two shell functions (for your $HOME/.bashrc file) which enhance the shell's cd built-in. 🔥

#   database scan
cds () {
    find "$HOME" -type d | sort > ~/.dirs &
}

#   enhanced cd command
cd () {
    if [ -d "$1" ]; then
        builtin cd "$1"
    else
        builtin cd "$(grep -E "/$1[^/]*$" ~/.dirs   |
                      iselect -a -Q "$1" -n "chdir" \
                      -t "Change Directory to...")"
    fi
}

this cd() is compatible with the built-in in the case where the specified directory actually exists. when it doesn't, the original cd would immediately give an error (assuming CDPATH is not set). this version tries harder by searching for such a directory in a previously-built (via cds()) ($HOME/.dirs) file. when no match is found, iSelect just returns the given directory as the default result and cd fails as usual. when only one directory was found, iSelect gives it to cd silently. only when more then one directory was found, iSelect shows a menu to pick between matches interactively. the chosen directory is then given to cd.

for more useful examples on how to use iSelect, see /usr/share/doc/iselect/examples. 📚

---

👑 AUTHORS 👑

Ralf S. Engelschall <rse@engelschall.com> (http://www.engelschall.com)

---

🔗 SEE ALSO 🔗

New iSelect Home: https://sr.ht/~nabijaczleweli/ossp

---

okay bestie, that's the whole page, every last flag and keystroke accounted for, nothing skipped, nothing invented 💖

this was ossp-iselect version 1.4.2, dated November 17, 2024 — thank you for coming to her ted talk, she ate and left no crumbs 🫶✨🎀