74a7c557fb
This change introduces a new module, Graphics.Vty.UnicodeWidthTable.Install, that is responsible for installing custom unicode width tables into the process. It does so by allocating memory to hold the table, populating the table's character ranges with widths from the UnicodeWidthTable, and then marking the table as ready for use. That causes future calls to 'wcwidth' to consult the new table rather than relying on the built-in logic to compute widths. Note that this functionality breaks the purity of 'wcwidth': 'wcwidth' calls made before the installation of a custom table may return different values after the table is installed, despite 'wcwidth' being a pure function. This choice was made deliberately to simplify the API and is based on the observation that in practice this will probably never be an issue. It's also worth nothing (as is spelled out in the docs, too) that a custom table installation can only be performed at most once per program lifetime. Once a custom table installation is performed, it cannot be undone and no new table can be installed. This, too, is a simplification based on the assumption that in practice multiple tables will usually not be required. |
||
|---|---|---|
| cbits | ||
| ci | ||
| demos | ||
| docs | ||
| scripts | ||
| src | ||
| test | ||
| tools | ||
| .gitignore | ||
| .travis.yml | ||
| AUTHORS | ||
| CHANGELOG.md | ||
| LICENSE | ||
| README.md | ||
| Setup.lhs | ||
| vty.cabal | ||
vty is a terminal interface library. It provides a high-level
interface for doing terminal I/O. Vty is supported on GHC versions
7.10.1 and up.
Install via git with:
git clone git://github.com/jtdaugherty/vty.git
Install via cabal with:
cabal install vty
Features
-
Supports a large number of terminals. vt100, ansi, hurd, linux, screen, etc., or anything with a sufficient terminfo entry.
-
Automatic handling of window resizes.
-
Unicode output on terminals with UTF-8 support.
-
Handles multi-column glyphs. (Requires user to properly configure terminal.)
-
Efficient output. Output buffering and terminal state changes are minimized.
-
Minimizes repaint area, which virtually eliminates the flicker problems that plague ncurses programs.
-
A pure, compositional interface for efficiently constructing display images.
-
Automatically decodes keyboard keys into (key,[modifier]) tuples.
-
Automatically supports refresh on Ctrl-L.
-
Supports a keypress timeout after for lone ESC. The timeout is customizable.
-
The interface is designed for easy extension.
-
Supports ANSI graphics modes (SGR as defined in
console_codes(4)) with a type-safe interface and graceful fallback for terminals with limited or nonexistent support for such modes. -
Properly handles cleanup (but not due to signals).
-
Provides a comprehensive test suite.
-
Supports "normal" and "extended" (SGR) mouse modes as described at http://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking
-
Supports bracketed paste mode as described at http://cirw.in/blog/bracketed-paste
Development Notes
Vty uses threads internally, so programs made with Vty need to be
compiled with the threaded runtime using the GHC -threaded option.
Platform Support
Posix Terminals
Uses terminfo to determine terminal protocol. With some special rules to handle some omissions from terminfo.
Windows
Unsupported (but contributions and testing here are very welcome!)
Contributing
If you decide to contribute, that's great! Here are some guidelines you should consider to make submitting patches easier for all concerned:
- If you want to take on big things, talk to me first; let's have a design/vision discussion before you start coding. Create a GitHub issue and we can use that as the place to hash things out.
- If you make changes, make them consistent with the syntactic conventions already used in the codebase.
- Please provide Haddock documentation for any changes you make.
Development Notes
Under NixOS
Using cabal
After installing ncurses to the user environment:
LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal configure --enable-tests --extra-lib-dirs=$HOME/.nix-profile/lib
LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal build
LIBRARY_PATH=$HOME/.nix-profile/lib/ cabal test
Code Coverage
As of last testing, profiling causes issues with coverage when enabled. To evaluate coverage, configure as follows:
rm -rf dist ; cabal configure --enable-tests --enable-library-coverage \
--disable-library-profiling \
--disable-executable-profiling
Profiling
rm -rf dist ; cabal configure --enable-tests --disable-library-coverage \
--enable-library-profiling \
--enable-executable-profiling
Known Issues
-
Terminals have numerous quirks and bugs. Vty picks what works best for the author in ambiguous or buggy situations.
-
Signal handling of STOP, TERM and INT are nonexistent.
-
The character encoding of the terminal is assumed to be UTF-8 if unicode is used.
-
Terminfo is assumed to be correct unless there is an override configured. Some terminals will not have correct special key support (shifted F10 etc). See
Configfor customizing vty's behavior for a particular terminal. -
Uses the
TIOCGWINSZioctl to find the current window size, which appears to be limited to Linux and BSD.
Sources
Good sources of documentation for terminal programming are:
- https://github.com/b4winckler/vim/blob/master/src/term.c
- http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
- http://ulisse.elettra.trieste.it/services/doc/serial/config.html
- http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html
- http://www.unixwiz.net/techtips/termios-vmin-vtime.html
- http://vt100.net/docs/vt100-ug/chapter3.html