Added -^/--head to watch.py and other scripts, RingIO tweaks

This lets you view the first n lines of output instead of the last n
lines, as though the output was piped through head.

This is how the standard watch command works, and can be more useful
when most of the information is at the top, such as in our dbg*.py
scripts (watch.py was originally used as a sort of inotifywait-esque
build runner, which is the main reason it's different).

To make this work, RingIO (renamed from LinesIO) now uses terminal
height as a part of its canvas rendering. This has the added benefit of
more rigorously enforcing the canvas boundaries, but risks breaking when
not associated with a terminal. But that raises the question, does
RingIO even make sense without a terminal?

Worst case you can bypass all of this with -z/--cat.

scripts/plot.py

@@ -167,9 +167,10 @@ else:
                 else:
                     self.add_watch(path, flags)
 
-class LinesIO:
-    def __init__(self, maxlen=None):
+class RingIO:
+    def __init__(self, maxlen=None, head=False):
         self.maxlen = maxlen
+        self.head = head
         self.lines = co.deque(maxlen=maxlen)
         self.tail = io.StringIO()
 
@@ -177,6 +178,9 @@ class LinesIO:
         if maxlen == 0:
             self.resize(0)
 
+    def __len__(self):
+        return len(self.lines)
+
     def write(self, s):
         # note using split here ensures the trailing string has no newline
         lines = s.split('\n')
@@ -204,35 +208,37 @@ class LinesIO:
         if self.maxlen == 0:
             self.resize(0)
 
+        # copy lines
+        lines = self.lines.copy()
+        # pad to fill any existing canvas, but truncate to terminal size
+        h = shutil.get_terminal_size((80, 5))[1]
+        lines.extend('' for _ in range(
+            len(lines),
+            min(RingIO.canvas_lines, h)))
+        while len(lines) > h:
+            if self.head:
+                lines.pop()
+            else:
+                lines.popleft()
+
         # first thing first, give ourself a canvas
-        while LinesIO.canvas_lines < len(self.lines):
+        while RingIO.canvas_lines < len(lines):
             sys.stdout.write('\n')
-            LinesIO.canvas_lines += 1
+            RingIO.canvas_lines += 1
 
-        # clear the bottom of the canvas if we shrink
-        shrink = LinesIO.canvas_lines - len(self.lines)
-        if shrink > 0:
-            for i in range(shrink):
-                sys.stdout.write('\r')
-                if shrink-1-i > 0:
-                    sys.stdout.write('\x1b[%dA' % (shrink-1-i))
-                sys.stdout.write('\x1b[K')
-                if shrink-1-i > 0:
-                    sys.stdout.write('\x1b[%dB' % (shrink-1-i))
-            sys.stdout.write('\x1b[%dA' % shrink)
-            LinesIO.canvas_lines = len(self.lines)
-
-        for i, line in enumerate(self.lines):
+        # write lines from top to bottom so later lines overwrite earlier
+        # lines, note [xA/[xB stop at terminal boundaries
+        for i, line in enumerate(lines):
             # move cursor, clear line, disable/reenable line wrapping
             sys.stdout.write('\r')
-            if len(self.lines)-1-i > 0:
-                sys.stdout.write('\x1b[%dA' % (len(self.lines)-1-i))
+            if len(lines)-1-i > 0:
+                sys.stdout.write('\x1b[%dA' % (len(lines)-1-i))
             sys.stdout.write('\x1b[K')
             sys.stdout.write('\x1b[?7l')
             sys.stdout.write(line)
             sys.stdout.write('\x1b[?7h')
-            if len(self.lines)-1-i > 0:
-                sys.stdout.write('\x1b[%dB' % (len(self.lines)-1-i))
+            if len(lines)-1-i > 0:
+                sys.stdout.write('\x1b[%dB' % (len(lines)-1-i))
         sys.stdout.flush()
 
 
@@ -845,6 +851,7 @@ def main(csv_paths, *,
         legend_below=False,
         subplot={},
         subplots=[],
+        head=False,
         cat=False,
         keep_open=False,
         sleep=None,
@@ -1402,7 +1409,7 @@ def main(csv_paths, *,
                 if cat:
                     draw(sys.stdout)
                 else:
-                    ring = LinesIO()
+                    ring = RingIO(head=head)
                     draw(ring)
                     ring.draw()
 
@@ -1419,13 +1426,8 @@ def main(csv_paths, *,
         except KeyboardInterrupt:
             pass
 
-        if cat:
-            draw(sys.stdout)
-        else:
-            ring = LinesIO()
-            draw(ring)
-            ring.draw()
-        sys.stdout.write('\n')
+        if not cat:
+            sys.stdout.write('\n')
     else:
         draw(sys.stdout)
 
@@ -1644,6 +1646,10 @@ if __name__ == "__main__":
         '--subplot',
         type=AppendSubplot.parse,
         help="Add subplot-specific arguments to the main plot.")
+    parser.add_argument(
+        '-^', '--head',
+        action='store_true',
+        help="Show the first n lines.")
     parser.add_argument(
         '-z', '--cat',
         action='store_true',