path: root/pw.1

PW(1)                                       Pipe Watch                                      PW(1)

NAME
       pw - Pipe Watch: monitor recent lines of output from pipe

SYNOPSIS
       command | pw [-i interval] [-l interval] [-n number-of-lines] [-d]

DESCRIPTION
       pw  stands for Pipe Watch. This is a utility which continuously reads textual input from a
       pipe or pipe-like source, and maintains a dynamic display of  the  most  recently  read  N
       lines.

       If  pw  is invoked such that its standard input is a TTY, it simply reads lines and prints
       them in its characteristic way, with control characters replaced  by  caret  codes,  until
       end-of-file is encountered. Long lines aren't clipped, and there is no interactive mode.

       The intended use of pw is that its standard input is a pipe, such as the output of another
       command, or a pipe-like device such as a socket or whatever.  In this  situation,  pw  ex-
       pects  to  be  executed in a TTY session in which a /dev/tty device can be opened, for the
       purposes of obtaining interactive input.  The remaining description pertains to  this  in-
       teractive mode.

       In  interactive mode, pw simultaneously monitors its standard input for the arrival of new
       data, as well as the TTY for interactive commands.  Lines from standard input  are  placed
       into  a  FIFO  buffer.  While the FIFO buffer is not yet full, lines are displayed immedi-
       ately.  After the FIFO buffer fills up with the specified number of lines  (controlled  by
       the  -n  option)  then  pw transitions into a mode in which, old lines are bumped from the
       tail of the FIFO as new ones are added to the head, and refresh operations are required in
       order to display the current FIFO contents.

       The display only refreshes with the latest FIFO data when

       1.     there is some keyboard activity from the terminal; or

       2.     when the interval period has expired without new input having been seen; or else

       3.     whenever the long period elapses.

       In  other words, while the pipe is spewing, and there is no keyboard input, the display is
       updated infrequently, only according to the long interval.

       The display is also updated when standard input indicates end-of-data.  In this situation,
       pw  terminates, unless the -d (do not quit) option has been specified, in which case it pw
       stays in interactive mode. The the end-of-data status is indicated by the string EOF being
       displayed in the status line after the data.

DISPLAY
       Lines  displayed  by  pw  are trimmed not to exceed the number of terminal columns. When a
       line is trimmed, it is terminated by the < character to indicate that there are more char-
       acters. The display may be scrolled interactively to read the long lines.

       The  ASCII  DEL  character (127) is displayed as ^?  and ASCII control characters are dis-
       played as ^@, ^A, ...  ^Z, ...  ^_.  All other characters are sent to the  display  as-is.
       No attempt is made to account for the width of East Asian Unicode characters, and such.

       When  the  display  is scrolled horizontally, the > character appears at the start of each
       line to indicate this state.  Thus, if neither end of a long line  is  currently  visible,
       then its visible portion appears delimited by >...<.

COMMANDS
       When pw enters closed loop operation, the following single-key commands are available:

       q, Ctrl-C
              Quit the program.

       l, Left Arrow
              Scroll the display to the left.

       h, Right Arrow
              Scroll the display to the right.

       0, Home
              Reset scroll to first column.

       Space  Suspend  the  refresh  of  the display.  In suspended mode, input continues to pass
              through the FIFO, but all display refresh is stopped.  The  status  indicator  SUS-
              PENDED  is  displayed below the data. If the the status is already EOF then suspend
              mode cannot be entered.

       Enter  Cancel suspended mode, resuming display refresh. The display is  refreshed  immedi-
              ately and the SUSPENDED status indicator disappears.

       :      Enter colon command mode. In colon command mode, the status line clears and a colon
              prompt appears there. An extended command can be entered.  Pressing Enter in  colon
              mode  dispatches  the  command. Simple editing is available: backspace, Ctrl-W word
              erase and Ctrl-U line erase.  If backspace is used in an empty  colon  line,  colon
              mode  terminates  without executing a command.  Ctrl-C and Esc also terminate colon
              mode without executing a command. Colon commands are documented in the  COLON  COM-
              MANDS section below.

       /pattern, ?pattern
              Activate  trigger  mode if a non-empty pattern is specified, or else cancel trigger
              mode if an empty pattern is specified. The / command specifies head  trigger  mode,
              whereas  ?   specifies tail trigger mode.  Under head trigger mode, the display re-
              freshes only when the most recent line ("head line") in the FIFO matches the speci-
              fied pattern.  The head line is the one which will appear at the bottom of the dis-
              play, since newer lines appear at the bottom and scroll out  toward  the  top.   In
              head  trigger  mode, the status string TRIG (/pattern) appears, showing the pattern
              preceded by a slash.  Under tail trigger mode, the display refreshes only when  the
              least  recent  line  ("tail line") in the FIFO matches the specified pattern.  That
              line is the one which will appear at the top of the display.  In tail trigger mode,
              the  status string TRIG (?pattern) appears, showing the pattern preceded by a ques-
              tion mark.  The pattern is an extended regular expression (ERE).  Trigger  patterns
              saved  in  a  history which may be navigated for recall using the up and down arrow
              keys or Ctrl-P and Ctrl-N.

       Ctrl-Z Suspends pw, and indeed the entire surrounding process group, to the background  to
              gain  shell  access.  This  requires  a job control shell.  When pw is foregrounded
              again, it will refresh the display in a new text area below  the  cursor,  avoiding
              overwriting  anything  in  the terminal. Thus suspending and then immediately fore-
              grounding provides a way to save a snapshot of the window into  the  terminal  ses-
              sions history.

COLON COMMANDS
       First,  some  general remarks. Display refresh doesn't pause during the editing of a colon
       command. If that is required, the suspend command must be used.   The  space  between  the
       command and the argument may be omitted. After a command is executed, a result message ap-
       pears in its place.  This message persists over the poll interval period. The  longer  the
       poll interval (-i option), the longer the result message persists.

       Colon  commands  are saved in a history which may be navigated for recall using the up and
       down arrow keys or Ctrl-P and Ctrl-N.

       :w filename
              Write the current contents of the display into the specified file.

       :a filename
              Append the current contents of the display into the specified file.

       :! filename
              Pipe the current contents of of the display into the specified command.

       :g pattern, :v pattern
              Push a grep pattern onto the grep stack. The :g command pushes a plain pattern; the
              :v  command pushes a logically inverted pattern. The grep stack holds up to 64 pat-
              terns, which are extended regular expressions (EREs).  If the pattern  is  success-
              fully  pushed  onto  the stack, it restricts which lines are admitted into the FIFO
              and available for display.  The plain pattern admits only  the  lines  which  match
              pattern;  the inverted pattern admits only lines which do not match pattern.  Lines
              which are already in the FIFO at the time a new pattern is introduced are  not  af-
              fected.  The status line shows GREP (pattern[, ...])  to indicate that grep mode is
              in effect, and gives the list of patterns, separated by commas. The  inverted  pat-
              terns are indicated by a leading !  character.

       :r[!]  Remove and forget the most recent grep pattern (:gor:v) from the grep stack. If the
              stack depth decrements from 1, the grep mode is disabled and the GREP  status  line
              disappears.  If  the  optional !  modifier is included in the command, then it pops
              the entire stack, forgetting all the patterns and disabling grep mode.

       Any other command results in a brief error message.

OPTIONS
       -i real
              Set the poll interval to number of seconds specified by real.  This is is a  float-
              ing-point  constant such as 3 or 1.5. Exponential notation such as 5E-1 (equivalent
              to 0.5) is permitted.  This interval determines the input poll timeout of pw's  in-
              put processing loop. If no data arrives from the primary input, or from the TTY for
              this amount of time, a timeout occurs, and the display is refreshed if the FIFO has
              changed since the last refresh.  The default poll interval is 1s.

       -l real
              Set the long update interval to number of seconds specified by real.  The format is
              the same as -i, and the default value is 10s. Every time the long  update  interval
              passes,  the  display  is  updated,  if the FIFO has changed since the last update.
              This happens even when input is arriving too rapidly to permit the poll timeout  to
              take  place.  The  purpose of the long interval is to ensure that there are updates
              even when the data source continuously and rapidly produces data, and there  is  no
              TTY  input activity. The long interval should be at least several times longer than
              the short interval. The granularity of the timing of the long interval updates  de-
              pends  on  the  poll interval; in the absence of TTY input, pw will not perform any
              display updates more often that the poll interval, even if  the  long  interval  is
              made smaller than the poll interval.

       -n integer
              Set the number of lines N to the specified decimal integer value. The default value
              is 15.  This value must be positive, and is clipped to the number of display  lines
              available in the terminal, less one.

       -d     Disable auto-quit: when no more input is available, instead of updating the display
              one last time and terminating, pw will updating the status to EOF  and  staying  in
              the  interactive  mode. This is useful when the last portion of the input is of in-
              terest, and contains long lines that require horizontal scrolling.

TERMINATION STATUS
       If pw reaches EOF on standard input without encountering a read error, then  its  termina-
       tion  status will be successful.  This is regardless of whether it automatically quits, or
       whether it stays in interactive mode and then quits due to a quit command.   If  the  data
       ends prematurely due to a read error, or if the program is asked to quit before all of the
       data has been read, then unsuccessful termination status will be indicated.

       Incorrect usage, such as nonexistent options or bad arguments to options, result in a  di-
       agnostic on standard error and an unsuccessful termination.

       Unexpected conditions like out of memory result in abnormal termination (abort).

BUGS
       This was written over the course of a couple of hours, and tested only interactively.

       The  program doesn't respond to window size changes.  The display format, such as the han-
       dling of control characters, is hard-coded.

       The program uses hard-coded ANSI sequences, so it doesn't support interesting  old  termi-
       nals.  On  the  other  hand,  it  carries  no  dependency  on any terminal abstraction li-
       brary/data.

       The intervals and number of lines cannot be dynamically adjusted.

       There is no support for unwrapping long lines, which would be useful for copy and paste.

       During the :!  command's execution, the TTY settings are not restored.

       Most of these issues are easy; patches welcome.

AUTHOR
       Kaz Kylheku <kaz@kylheku.com>

COPYRIGHT
       Copyright 2022, BSD2 License.

Utility Commands                          26 April 2022                                     PW(1)