FreeBSD Manual Pages
ISELECT(1) Ralf S. Engelschall ISELECT(1) 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, operat- ing via a full-screen Curses-based terminal session. It can be used ei- ther 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 argu- ments are given) where the buffer lines are determined according to the newline characters. You can additionally let substrings displayed in Bold mode for non-se- lectable 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 corre- sponding 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"'' con- structs. 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 re- sult is not accepted on input. The Curses-based full-screen selection is always done via /dev/tty, be- cause 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 pars- ing. -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 en- hance 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 di- rectory was found, iSelect opens its Curses-based selection screen and lets the user choose interactively between those directories. The cho- sen directory is then finally given to `cd'. For more useful examples on how to use iSelect, see the contrib/ direc- tory 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/ EN 2007-07-08 ISELECT(1)
NAME | SYNOPSIS | VERSION | DESCRIPTION | OPTIONS | KEYSTROKES | EXAMPLE | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=iselect&sektion=1&manpath=FreeBSD+Ports+15.0>