git.iko.soy/vty
on 5.18 help sign in
vty/README.md
146 lines 4.3 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/coreyoconnor/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# Platform Support
65## Posix Terminals
67Uses terminfo to determine terminal protocol. With some special rules to
68handle some omissions from terminfo.
70## Windows
72Unsupported (but contributions and testing here are very welcome!)
74# Contributing
76If you decide to contribute, that's great! Here are some guidelines you
77should consider to make submitting patches easier for all concerned:
79 - If you want to take on big things, talk to me first; let's have a
80 design/vision discussion before you start coding. Create a GitHub
81 issue and we can use that as the place to hash things out.
82 - If you make changes, make them consistent with the syntactic
83 conventions already used in the codebase.
84 - Please provide Haddock documentation for any changes you make.
86# Development Notes
88## Under NixOS
90### Using cabal
92After installing `ncurses` to the user environment:
94~~~
95LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal configure --enable-tests --extra-lib-dirs=$HOME/.nix-profile/lib
96LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal build
97LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal test
98~~~
100## Code Coverage
102As of last testing, profiling causes issues with coverage when enabled.
103To evaluate coverage, configure as follows:
105~~~
106rm -rf dist ; cabal configure --enable-tests --enable-library-coverage \
107 --disable-library-profiling \
108 --disable-executable-profiling
109~~~
111## Profiling
113~~~
114rm -rf dist ; cabal configure --enable-tests --disable-library-coverage \
115 --enable-library-profiling \
116 --enable-executable-profiling
117~~~
119# Known Issues
121* Terminals have numerous quirks and bugs. Vty picks what works best for
122 the author in ambiguous or buggy situations.
124* Signal handling of STOP, TERM and INT are nonexistent.
126* The character encoding of the terminal is assumed to be UTF-8 if
127 unicode is used.
129* Terminfo is assumed to be correct unless there is an override
130 configured. Some terminals will not have correct special key support
131 (shifted F10 etc). See `Config` for customizing vty's behavior for a
132 particular terminal.
134* Uses the `TIOCGWINSZ` ioctl to find the current window size, which
135 appears to be limited to Linux and BSD.
137# Sources
139Good sources of documentation for terminal programming are:
141* https://github.com/b4winckler/vim/blob/master/src/term.c
142* http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
143* http://ulisse.elettra.trieste.it/services/doc/serial/config.html
144* http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html
145* http://www.unixwiz.net/techtips/termios-vmin-vtime.html
146* http://vt100.net/docs/vt100-ug/chapter3.html