Table of Contents

Name

ipick - A screen-based filter to interactively pick lines

Syntax

ipick [-abdhrRvV] [-m minimum] [-M maximum] [-t fixed-title-text] [-T stdin-title-lines] [-X xterm-name-substring] [filename]

Description

ipick reads lines of text from the standard input or the optional filename and uses curses(3) to present them as a full-screen selection list. ipick provides numerous commands to select, navigate, scroll and search through this list. On quitting, ipick writes the selected lines to the standard output.

Typically you would use ipick as a final-filter to glue your neat, pre-stored pipelines and scripts together in a friendly way so that people other than Unix-o-philes can use them.

See MOTIVATION, towards the end, for a more detailed discussion.

Options

Options can appear in any order so long as they precede the filename.

-a
Automatically exit when the number of lines selected is within the minimum and maximum values allowed (see -m and -M options).
-b
Activate the audible alarm on invalid keystroke commands. Not normally needed as ipick always generates an error message. Normally you would set this option only for inexperienced users.
-d
Drain the standard input on exit. This avoids the possibility of upstream processes receiving a SIGPIPE. This is more a nicety than a necessity. Furthermore, using this option could prove expensive if the upstream process is a long way from finishing!
-h, -?
Print an extended help message describing these options.
-m
Minimum number of lines that the user must select before ipick will exit.
-M
maximum number of lines that the user may select select before ipick will exit.
You would typically use the minimum and maximum settings
in conjunction with the -a and/or -r options to ensure an orderly and predictable outcome of the picking process.
-r
Restricted mode. In this mode the user cannot escape the clutches of ipick except as defined by the other command-line options. This disables the shell and pipe commands. Additionally, this disables keyboard signals by setting the terminal to raw mode instead of cbreak mode. Note that raw mode has other side-effects; see stty(1) for more details.
-R
Do not set terminal input to raw mode. The main effects of this option is that the stty(1) control character sequences remain active and are thus capable of generating keyboard signals such as SIGINT and SIGQUIT. Note that ipick has an abort command that can be bound to your normal ‘‘intr’’ or ‘‘quit’’ characters; see stty(1) for more details on raw mode.
-t fixed-title-text
Text to use as a title on the screen. ipick creates a ‘‘fixed title’’ containing the given text starting at the top line of the screen. ipick does not scroll this part of the title horizontally with the data. If the fixed-title-text contains embedded newlines, ipick handles them correctly.
-T stdin-title-lines
ipick will read stdin-title-lines lines from the standard input and use these as the ‘‘variable title’’ which follows the ‘‘fixed title’’. This option is especially useful when the upstream process generates a title line, such as ps(1) , or w(1) . ipick scrolls this part of the title horizontally with the data.
If the standard input is less than
stdin-title-lines long, then ipick terminates silently.
If you define a title with either
-t or -T, then ipick separates the title from the data with a line of hyphens.
-v
Invert the selections. With this option, ipick writes the lines the user did not select to stdout.
-V
Print a message containing the version, compilation options, location of the system-wide customization file and the obligatory copyright message.
-X xterm-name-substring
ipick compares the xterm-name-substring with the terminal type defined in $TERM. If it matches, ipick sends the escape sequences needed to enable and disable mouse-tracking. The default xterm-name-substring is ‘‘xterm’’, so real xterm(1) users need do nothing. The comparison is case-sensitive. See XTERM MOUSE TRACKING for more information.

The -m, -M and -r options allow you to carefully control the actions and predict the results of a user. For example, if you use

ipick -m 1 -M 1 -r

then you can write the rest of the pipeline assuming that ipick will produce one and only one line of output.

Keyboard Commands

ipick accepts numerous keyboard commands, perhaps the most important being ? which provides online help.

ipick is ecumenical regarding keybindings as it implements a reasonable set of emacs, vi and more keybindings concurrently! Additionally, ipick binds all of the commonly used commands to function keys as defined in the TERMINFO (or the corresponding termcap) definition file. This means that users can avoid learning the idiosyncratic nature of vi and emacs keystrokes.

Finally, ipick can be customized with both a system wide startup file and and a user startup file. See CUSTOMIZATION, for a detailed discussion of these files. For the purposes of this section it is assumed that no customization is in effect.

The list of keyboard commands uses the following symbols:

^A -- control-A
Press Control and ‘‘A’’ together E-A -- Escape-A Press Escape followed by ‘‘A’’
K_tttt
identifies the TERMINFO (or termcap) key_tttt used. This is the ‘‘Variable name’’, not the ‘‘Capname’’ in the man page.

Selection Commands

<CR>, K_ent
Toggle the selection state of the current line, then move to the next line if present
0-9
Select the specific line number
S
Select all lines
C
Clear all lines
+
Toggle the state of unread lines
s, K_select
Select the ‘‘line-range’’ nominated
c, K_clear
Clear the ‘‘line-range’’ nominated
t
Toggle the selection state of the ‘‘line-range’’ nominated

The ‘‘line-range’’ given to the ‘‘s’’, ‘‘c’’ and ‘‘t’’ commands may consist of any one of:

You may shorten both ‘‘visible’’ and ‘‘all’’ to just ‘‘v’’ and ‘‘a’’ respectively. ipick ignores the case of these strings.

Positioning commands

T, K_beg
Top of File
B, K_end
Bottom of File
H, K_home
Top of screen
L, K_ll
Bottom of screen
^N, j, K_down
Next line
^P, k, K_up
Previous line

Vertical scrolling

^U
Up half the screen
^D
Down half the screen
E-v, b, K_ppage, K_rindex
Up full screen
^V, <Space>, K_npage, K_index
Down full screen

Horizontal scrolling

^B, h, K_left
Scroll left one character
^F, l, K_right
Scroll right one character
^I (TAB)
Scroll right one tabstop
E-i, K_cbt
Scroll left one tabstop
^A, ^ (circumflex)
Scroll to beginning of line
^E, $
Scroll to end of line
<
Scroll left half screen
>
Scroll right half screen

Searching

^S, E-s, /, K_find
Forward search
^R, E-r, \
Reverse search
n
Redo forward search
N
Redo reverse search
*, K_next
Find next selected line
&, K_prev
Find previous selected line

Miscellaneous