IPICK(1) manual page

HTML automatically generated with rman
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]

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:

A number, series of numbers or range of numbers
```
(e.g. 1 5 7-14 21-19)
```
The string ‘‘visible’’ meaning all lines currently visible on the screen.
The string ‘‘all’’ meaning all lines.

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

Redo last command
g, K_move

Go to line

q, Q, ^X^C, ZZ, K_exit

Quit

^C

Abort

^L, K_refresh

Refresh

?, K_help

Provide online help

!

Shell command

|

Pipe command. Pipe the current line into the command

Customization

When ipick is invoked, it reads initialization commands from the site customization file (normally /usr/local/lib/ipickrc but see the -V option) and then the user’s customization file .ipickrc in the user’s home directory. Both files are optional. The file can contain blank lines and comments where comments are denoted by the first occurence of the ‘‘#’’ character.
A command must be completely contained on a single line as there is no continuation character. Each token can be separated by one or more white-space characters. A token can be quoted if it requires embedded spaces with either a single or double quote.
Substitution sequences
The following special substitution sequences are recognized:

\b

A backspace character

\f

A form-feed

\e

An escape

\n

The newline character

\r

A carriage-return

\s

A space

\t

A TAB

\\

The back-slash character

\NNN

The character represented by the octal value of NNN

^char

A control character. char can be ‘‘A-Z’’ or ‘‘@’’.

Customization commands
bind-key function keysequence [helptext]

Bind a set of keystrokes to a specific function.

bind-terminfo function terminfo-capability [helptext]

Bind a terminfo capability to a specific

function. If the terminfo functionality has not been built into ipick then this effectively becomes a no-op.

bind-termcap function termcap-capability [helptext]

Bind a termcap capability to a specific

function. If the termcap functionality has not been built into ipick then this effectively becomes a no-op.

include includefile
Where:

function

is a valid ipick function; see FUNCTIONS, for a complete list.

keysequence

is any sequence of keystrokes. The substitution character will typically be useful for this parameter.

helptext

is an optional text string that will be displayed as part of the online help screen. If not present then the keysequence or capability name will be used.

terminfo-capability

A valid terminfo keystroke capability name; see terminfo(5) for more details.

termcap-capability

A valid termcap keystroke capability name; see termcap(5) for more details.

includefile

a path of the file to include.

If

includefile has a leading tilde ‘‘~’’ then ipick performs the usual tilde expansion. That is the string between the tilde and the first ‘‘/’’ character is treated as a login name whose home directory is substituted. An empty login name implies $HOME.

If

includefile contains any shell characters then ipick assumes that it’s a pipeline command and uses popen(3S) rather than fopen(3V) to open the command.

If

includefile is treated as a pipeline command and there is no trailing pipe character ‘‘|’’ then ipick preceeds the pipeline string with the cat(1) command.

The follow sample .ipickrc file demostrates most of the functionality discuss in this section.
```
#
# This file has some comments in it
#
include "~fred/.ipickrc"         # Fred has a cool startup file
include ’/usr/local/lib/ipick_${EDITOR:-EMACS}’
include "grep terminfo /usr/local/lib/ipick_wyse |"
include "$HOME/env/test_bindings"
bind-key QUIT "\e\s\023" "NT250 Exit key"
# Bind the begining of line terminal definition
bind-terminfo beginning-of-line kbeg
bind-termcap beginning-of-line @1
```
Functions
The follow is a list of available functions.

select-range

Enter a range of line numbers to pick

select-all

Mark all lines as picked

clear-range

Enter a range of line numbers which are to have their pick state cleared

clear-all

Mark all lines as not picked

toggle-current

Toggle the picked state of the current line and move the cursor to the next line

toggle-range

Enter a range of line numbers which are to have their pick state toggled

toggle-unread

Toggle the picked state of all unread lines

top-of-screen

Move the cursor to the top of the screen

bottom-of-screen

Move the cursor to the bottom of the screen

previous-line

Move the cursor up one line

next-line

Move the cursor down one line

quit

Exit and write the pick lines to stdout

abort

Exit without writing anything to stdout

help

Display the online help screen

refresh

Clear and re-display the current screen

scroll-left-char

Move the cursor left one position

scroll-right-char

Move the cursor right one position

beginning-of-line

Move the cursor to the first character position

end-of-line

Move the cursor to the last character position of the current line

scroll-tab

Move the cursor forward one tabstop

scroll-backtab

Move the cursor back one tabstop

scroll-left-screen

Move the cursor left by one half the width of the screen

scroll-right-screen

Move the cursor right by one half the width of the screen

scroll-up-half

Move the cursor up by one half of the height of the screen

scroll-down-half

Move the cursor down by one half of the height of the screen

scroll-up-full

Move the cursor up a full screen

scroll-down-full

Move the cursor down a full screen

beginning-of-file

Move the cursor to the first line

end-of-file

Move the cursor to the end of all the input lines. If data is from an upstream process, ipick will read until this process writes end of file

search-forward

Enter the search forward string

search-backward

Enter the reverse search string

re-search-forward

Continue the search forwards

re-search-backward

Continue the search backwards

next-selected

Move the cursor to the next line selected

previous-selected

Move the cursor to the previous line selected

goto-line

Enter a line number to position to

shell

Enter a shell command

pipe

Enter a command which will have the current line written to it’s stdin

redo-command

Redo the last command

xterm-mouse

Define the xterm escape prefix. Only to be used if you really know what you’re doing (Which I don’t when it comes to nroff(1) )

invalid-command

Treat as an invalid command and generate an error message

Xterm Mouse Tracking

ipick has limited support for xterm’s ‘‘mouse tracking’’ capability (the X11 ‘‘normal tracking mode’’ not the X10 compatibility mode).
To enable this facility in a particular xterm you have to send it a special escape sequence. To quote from xterm(1) , ‘‘[mouse tracking] is enabled by specifying parameter 1000 to DECSET’’. ipick does this automatically when it detects a terminal type of xterm. If your xterm clone uses a different name, you can use the -X option to tell ipick what it is.
When you enable this facility, your xterm will pass any mouse events to ipick in a form that ipick recognizes. In all cases, the down event defines the start of a range of lines and the up event defines the end of the range -- so dragging is useful.
Each mouse button has the following function:

Button

Description
Set the selected status of the range
Toggle the selected status of the range
Clear the selected status of the range

Note that ipick ignores augmentation of mouse events with the Shift, Control and Meta keys.

The xterm facility is limited in that chording the mouse buttons seems to be undefined. Furthermore, the release (or mouse-up) doesn’t specify the button. Accordingly ipick takes a conservative approach to mouse-events and tends to discard anything unexpected.

Diagnostics

Exit codes.

Normal termination -- at least one line selected
Normal termination -- no lines selected
Abnormal termination

Notes

If no input exists, or if the -T option causes ipick to consume all its input, then ipick terminates silently with an exit code of 1.

Each Newline terminated string in fixed-title-text (see the -t option) becomes a separate line on the fixed-title section of the screen.

ipick only reads lines from the standard input as needed (and after each keyboard command) rather than reading all input lines on starting. This is especially useful if the upstream process generates output lines slowly as ipick is able to display lines as soon as they become available -- within the constraints of any buffering. It is also useful if the upstream process has the potential to generate an enormous number of lines of output prior to completion.

ipick processes binary files correctly, but it’s hard to imagine that this capability is especially useful.

When constructing pipelines, be aware of the fact that many commands don’t take multiple parameters. In these cases, use xargs -l1 if your system has it.

Restrictions

ipick is designed to process modest amounts of data. The data is held in memory and all functions are coded simplistically. If you ask ipick to handle large amounts of data, it does so sluggishly and consumes excessive system resources.

ipick takes a passive approach to ambiguous function key definitions -- later definitions override earlier definitions.

The search function does not handle regular expressions.

Because of the way in which ipick reads the standard input, using ipick with data from the keyboard does not work as you would want (In fact ipick should probably insist on a pipe or a file as input, just as more does). The workaround is to use the ‘‘here document’’ capability of the shell (the ‘‘<<’’ redirection).

ipick arbitrarily expands tab characters to 8-column tabstops.

Bugs

The online help does not display properly if the screen is less than 80 columns wide.

Directions implied by movement and scrolling commands apply to the cursor, not the data.

ipick does not know when include files opened with popen(1) fail. This can sometimes cause ipick to wait for ever depending on the state of the child process.

Motivation

It is the very essence of Unix to make useful commands with the generic construct:

generate_listing |: FILTER | do_something

do_something ‘generate_listing |: FILTER‘

The problem is FILTER. Getting it correct for the simplistic case is easy, making it perfect and bullet-proof is not. This is especially true if the pipeline is being developed for the user community.

Think about how you typically build a pipeline for the following requests:

‘‘Kill my awk process, it’s hung my terminal.’’: ‘‘Remove my print job, I’ve run the wrong report.’’
‘‘Remove that message queue, then re-run the daemon.’’

Either you construct a nice obscure FILTER using some combination of grep(1) , awk(1) , perl(1) , or sed(1) -- usually after you’ve had a look at the generate_listing output a couple of times to make sure you don’t zap the wrong thing! Alternatively you run the generate_listing program a couple of times until you’ve memorized the relevant identifier (such as pid, job number, queue id), then you run the do_something program and re-type the relevant identifier trying as best you can to avoid mis-typing and mis-remembering.

In other words, tedious and error-prone.

Of course, when the time comes to give your neat pipeline or script to the user community, how do you give it an easy to use, safe, bullet-proof interface? Do you knock up a quick shell wrapper with token prompts, perfunctory checking and an interface that’s almost the same as your last shell wrapper?

If any of these situations sound familiar then ipick may well be your pipeline panacea! (Well, at least marginally useful.)

This is because ipick makes the user the final part of the FILTER in a safe, friendly manner, often obviating the need for shell wrappers and such.

The example of selecting and removing a set of print jobs is the easiest way to demonstrate ipick. With the pipeline:

lpq | grep ‘whoami‘ | ipick | awk ’{ print $3 }’ | xargs lprmYou use

ipick to select the print jobs to be removed and the pipeline does the rest, removing only those print jobs selected with ipick. Another example:

kill -9 ‘ps | ipick -T1 | awk ’{ print $1 }’‘you simply select the lines with the relevant pids then: exit from ipick -- the pipeline does the rest by killing only those processes you selected with ipick.

Examples

A few more examples to get you started. Normally you would define each of these as a function or alias in your shell. (Of course, I present these examples as ideas. They are not complete, bullet-proof functions.)

Pick source files to edit.

vi ‘ls -1 *.c | ipick -m1‘Pick a directory to cd to.

cd ‘ls -l | grep ’^d’ | ipick -m1 -M1 -a | cut -c46-‘

Pick files to extract from a tar file in the default tape drive.

tar t | ipick | xargs tar xvI find this especially useful when the archive: contains l-o-o-o-ng filenames.

Actually, in its current form the above example has a number of limitations, so a more complete solution to an interactive tar is:

tar tvf ${1:-/dev/rmt8} | sed -e ’s./$..’ | ipick | cut -c42- | xargs -v -t tar xvf ${1:-/dev/rmt8} {}

Clean up a directory containing many junk files.

The following pipeline does this by letting you select the files you want to keep, and deleting the rest.

rm ‘ls -l | grep ’^-’ | ipick -v -t "Which files to keep ?" | cut -c46-‘

Part of the login script to set the terminal type

#! /bin/sh...export TERMTERM=‘ipick -m1 -M1 -r -a -T3 <<EOD | cut -f1 -d’ ’ Pick the terminal type that you are logged intovt100 The old grey terminals in the conference roomxterm The new fancy terminals in the bosses officesun One of the workstations in the sysadmin’s office!EOD‘...

Site conventions for predefined files

If you get really keen, you can have a site convention for all pre-defined ipick files, such as:

first two lines are always header
first space separated field is always the output selection value

Then you can define a generic function or script (let’s call it ipickf) such as:

ipick -a -m1 -M1 -r -T2 $HOME/pickfiles/$1 | cut -f1 -d’ ’then use it around the traps as:

TERM=‘ipickf TERM‘Version

ipick: version 1.1, dated 28 February, 1993.

Author

Substantial man page improvements by DaviD W. Sanderson <dws@ssec.wisc.edu>

ipick may only be copied under the terms of either the Artistic License or the GNU General Public Licence, which may be found in the ipick source kit.