git.iko.soy/vty
on 5.23 help sign in
vty/README.md
151 lines 4.5 kB history raw
1[![Build Status](https://travis-ci.org/jtdaugherty/vty.png)](https://travis-ci.org/jtdaugherty/vty)
3`vty` is a terminal interface library. It provides a high-level
4interface for doing terminal I/O. Vty is supported on GHC versions
57.10.1 and up.
7Install via `git` with:
9```
10git clone git://github.com/jtdaugherty/vty.git
11```
13Install via `cabal` with:
15```
16cabal install vty
17```
19# Features
21* Supports a large number of terminals. vt100, ansi, hurd, linux,
22 screen, etc., or anything with a sufficient terminfo entry.
24* Automatic handling of window resizes.
26* Unicode output on terminals with UTF-8 support.
28* Handles multi-column glyphs. (Requires user to properly configure
29 terminal.)
31* Efficient output. Output buffering and terminal state changes are
32 minimized.
34* Minimizes repaint area, which virtually eliminates the flicker
35 problems that plague ncurses programs.
37* A pure, compositional interface for efficiently constructing display
38 images.
40* Automatically decodes keyboard keys into (key,[modifier]) tuples.
42* Automatically supports refresh on Ctrl-L.
44* Supports a keypress timeout after for lone ESC. The timeout is
45 customizable.
47* The interface is designed for easy extension.
49* Supports ANSI graphics modes (SGR as defined in `console_codes(4)`)
50 with a type-safe interface and graceful fallback for terminals
51 with limited or nonexistent support for such modes.
53* Properly handles cleanup (but not due to signals).
55* Provides a comprehensive test suite.
57* Supports "normal" and "extended" (SGR) mouse modes as described at
58 http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking
60* Supports bracketed paste mode as described at
61 http://cirw.in/blog/bracketed-paste
63# Development Notes
65Vty uses threads internally, so programs made with Vty need to be
66compiled with the threaded runtime using the GHC `-threaded` option.
68# Platform Support
70## Posix Terminals
72Uses terminfo to determine terminal protocol. With some special rules to
73handle some omissions from terminfo.
75## Windows
77Unsupported (but contributions and testing here are very welcome!)
79# Contributing
81If you decide to contribute, that's great! Here are some guidelines you
82should consider to make submitting patches easier for all concerned:
84 - If you want to take on big things, talk to me first; let's have a
85 design/vision discussion before you start coding. Create a GitHub
86 issue and we can use that as the place to hash things out.
87 - If you make changes, make them consistent with the syntactic
88 conventions already used in the codebase.
89 - Please provide Haddock documentation for any changes you make.
91# Development Notes
93## Under NixOS
95### Using cabal
97After installing `ncurses` to the user environment:
99~~~
100LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal configure --enable-tests --extra-lib-dirs=$HOME/.nix-profile/lib
101LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal build
102LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal test
103~~~
105## Code Coverage
107As of last testing, profiling causes issues with coverage when enabled.
108To evaluate coverage, configure as follows:
110~~~
111rm -rf dist ; cabal configure --enable-tests --enable-library-coverage \
112 --disable-library-profiling \
113 --disable-executable-profiling
114~~~
116## Profiling
118~~~
119rm -rf dist ; cabal configure --enable-tests --disable-library-coverage \
120 --enable-library-profiling \
121 --enable-executable-profiling
122~~~
124# Known Issues
126* Terminals have numerous quirks and bugs. Vty picks what works best for
127 the author in ambiguous or buggy situations.
129* Signal handling of STOP, TERM and INT are nonexistent.
131* The character encoding of the terminal is assumed to be UTF-8 if
132 unicode is used.
134* Terminfo is assumed to be correct unless there is an override
135 configured. Some terminals will not have correct special key support
136 (shifted F10 etc). See `Config` for customizing vty's behavior for a
137 particular terminal.
139* Uses the `TIOCGWINSZ` ioctl to find the current window size, which
140 appears to be limited to Linux and BSD.
142# Sources
144Good sources of documentation for terminal programming are:
146* https://github.com/b4winckler/vim/blob/master/src/term.c
147* http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
148* http://ulisse.elettra.trieste.it/services/doc/serial/config.html
149* http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html
150* http://www.unixwiz.net/techtips/termios-vmin-vtime.html
151* http://vt100.net/docs/vt100-ug/chapter3.html