Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ISELECT(1)		      Ralf S. Engelschall		    ISELECT(1)

       iSelect -- Interactive Selection	Tool

       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]

       1.4.0 (08-Jul-2007)


       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.


       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.

       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

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

       -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.

       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)


       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

       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

	#   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
		 builtin cd `egrep "/$1[^/]*$" $HOME/.cdpaths |\
			     iselect -a	-Q $1 -n "chdir" \
				     -t	"Change	Directory to..."`
	    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.

	 Ralf S. Engelschall

	 iSelect Home:

EN				  2007-07-08			    ISELECT(1)


Want to link to this manual page? Use this URL:

home | help