@@ -0,0 +1,89 @@
1+The first project I focused on when I became fun-employed was improving Vty: A terminal output
2+library for Haskell software.
3+<lj-cut/>
4+Oh I know what you're thinking... Well no, but *I* think it's rediculous to spend time on a
5+*terminal* library. Something like OpenGL or web related, hell anything where any significant activity
6+has happened in the past few years seems more reasonable. Oh well.
7+
8+This is a diary of completing vty 4 mostly written after I was done. No really specific technical
9+stuff is contained in this post. I suppose it counts as a sort of postmortem.
10+
11+I had taken over as maintainer of vty 3 from Stefan O'Rear. Vty 3 already worked great and I didn't
12+really see me doing much. Still there is always something to improve. In this case vty did not
13+support the various terminals people wanted to use. And characters that occupy multiple output
14+columns were causing corruption.
15+
16+Plus, optimization is always fun. So trying my hands at optimizing Haskell code sounded great.
17+Especially when, for the most part, there was an already fast and already working version to compare
18+performance data against: Vty 3.
19+
20+I figured low level optimization was what I should start on. Which only makes sense considering I
21+was only interested in optimization fun at the time. ;-) The result of this were much faster than
22+before. However, since I wasn't changing the design in any significant fashion some optimizations
23+could not be implemented. In the end this route was only useful to define reasonable performance
24+goals for a rewritter output layer.
25+
26+In addition I was learning Mandarin at the time. I wanted to, of course, create software to help me
27+study. Since I have an infatuation with terminal user interfaces I wanted a terminal library that
28+could handle double-width characters. I couldn't see an effective way to implement this with vty 3's
29+implementation.
30+
31+Anybody who has needed to reimplement, or deal with the horrors of a botch reimplementation, knows
32+how dangerous this can be. A botched reimplementation ends up costing more than continueing to
33+maintain the old implementation. A reimplementation is only feasable if the immediate cost of
34+performing the work is offset by the profits the improvements provide.
35+
36+A particular source of trouble for vty was the insanity of dealing with terminals or terminal
37+emulators. I'm never going to refer to the physical box of relays from the 70s and 80s that is
38+properly called a terminal again. Terminal emulators are now be refered to as terminals and the
39+others don't exist. So...
40+
41+Terminals are software driven character displays and a keyboard. The software controls the diplay by
42+serializing to the STDOUT UTF-8 byte character sequences. Which are then displayed. And control
43+codes which modify the display of the characters. Input from the keyboard and events are read from
44+STDIN.
45+
46+Why the fuck something as old as a terminal hasn't been beaten down into a simple, universally
47+supported set of operations by now is a mystery. I don't think curses are terminfo count. I suspect
48+if support for everything that cannot support the required interface is dropped things would only be
49+better. For this reason I only focused on supporting the following terminals: xterm-256-color with
50+UTF-8; Mac OS X Terminal.app; gnome terminal, kde terminal; and rxvt-unicode. Basically: All the
51+terminals I could easily use and behaved close to how I expected.
52+
53+While I did not consider supporting the Windows platform I hoped that the abstractions used to
54+handle the various non-Windows terminals would simplify supporting Windows in the future.
55+
56+To assure the re-implementation did not introduce regressions I repeatedly:
57+0. Characterized vty 3's implementation. Both in terms of functionality and performance.
58+1. Defined the semantics for the new implementation.
59+2. Verified the new implementation performed as expected: The semantics defined in 1 were
60+implemented correctly; No characteristics of vty 3's implementation that should be maintained
61+are missing; Verified characteristics of vty 3 that caused issues were not maintained.
62+
63+Not all the verification steps could be automated. Some I didn't know how to. Others were
64+just verified through informal analysis.
65+
66+The verification of some features was done by implementing an interactive test that guided and
67+recorded the results of a manual review. For instance the libraries representation of red and what
68+is actually required to get a terminal to display red. The only reasonable way to verify that final
69+map was for me to sit there and look at the output. Then record whether or not the output was as
70+expected. Since the same tests were going to have to be performed repeatedly and I wanted to record
71+the results of the tests I formalized this process in software: tests/interactive_terminal_test.hs.
72+This program recorded the results of: Describing a test to a user; Performing the test; Requesting
73+from the user if the test passed or failed; Then recording the users response. This paid for itself
74+very quickly. Not only did provide the framework to easily create about 15 individual tests. But
75+the program could also worked as a sort of bug reporting tool for users.
76+
77+The verification that could be entirely automated was done either through the type system or
78+<a href="http://en.wikipedia.org/wiki/QuickCheck">QuickCheck 2</a> based verification tests.
79+In short an loose terms: QuickCheck informally verifies equations satisfy user specified predicates
80+for arbitrarially generated input. Not all input is attempted; that'd take too long. However enough
81+is tried to be reasonably sure that an implementation works. The looseness of the verification is
82+made up for the fact that QuickCheck tests are *extremely* easy and quick to implement.
83+
84+I used a very simple Makefile to manage the execution of tests. The usage followed:
85+ make => built and ran all tests.
86+ make TEST => build and run test with name TEST. The output for a test was logged to a "results"
87+ directory.
88+Nothing fancy, but enough.
89+