vty: A simple terminal UI library

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

'ghc-options: -O2' is rarely needed. Check that it is giving a real benefit and not just imposing longer compile times on your users.
'ghc-options/ghc-prof-options: -fprof*' profiling flags are typically not appropriate for a distributed library package. These flags are useful to profile this package, but when profiling other packages that use this one these flags clutter the profile output with excessive detail. If you think other packages really want to see cost centres from this package then use '-fprof-auto-exported' which puts cost centres only on exported functions. Alternatively, if you want to use this, make it conditional based on a Cabal configuration flag (with 'manual: True' and 'default: False') and enable that flag during development.

vty is terminal GUI library in the niche of ncurses. It is intended to be easy to use, have no confusing corner cases, and good support for common terminal types.

See the vty-examples package as well as the program test/interactive_terminal_test.hs included in the vty package for examples on how to use the library.

Import the Graphics.Vty convenience module to get access to the core parts of the library.

[Skip to Readme]

Properties

Versions	3.0.0, 3.0.1, 3.0.2, 3.0.4, 3.1.0, 3.1.2, 3.1.4, 3.1.6, 3.1.8, 3.1.8.2, 3.1.8.4, 4.0.0, 4.0.0.1, 4.2.1.0, 4.4.0.0, 4.4.0.0.1, 4.6.0.1, 4.6.0.2, 4.6.0.4, 4.6.0.6, 4.7.0.0, 4.7.0.4, 4.7.0.6, 4.7.0.8, 4.7.0.10, 4.7.0.12, 4.7.0.14, 4.7.0.18, 4.7.0.20, 4.7.1, 4.7.2, 4.7.3, 4.7.4, 4.7.5, 5.0.0, 5.0.1, 5.0.2, 5.1.0, 5.1.1, 5.1.3, 5.1.4, 5.2.0, 5.2.1, 5.2.2, 5.2.3, 5.2.4, 5.2.5, 5.2.6, 5.2.7, 5.2.8, 5.2.9, 5.2.10, 5.2.11, 5.3, 5.3.1, 5.4.0, 5.5.0, 5.6, 5.7, 5.7.1, 5.8, 5.8.1, 5.9, 5.9.1, 5.10, 5.11, 5.11.1, 5.11.2, 5.11.3, 5.12, 5.13, 5.14, 5.15, 5.15.1, 5.16, 5.17, 5.17.1, 5.18, 5.18.1, 5.19, 5.19.1, 5.19.2, 5.20, 5.21, 5.22, 5.23, 5.23.1, 5.24, 5.24.1, 5.25, 5.25.1, 5.25.1, 5.26, 5.27, 5.28, 5.28.1, 5.28.2, 5.29, 5.30, 5.31, 5.32, 5.33, 5.34, 5.35, 5.35.1, 5.36, 5.37, 5.38, 5.39, 6.0, 6.1, 6.2, 6.3, 6.4
Change log	CHANGELOG.md
Dependencies	base (>=4.8 && <5), blaze-builder (>=0.3.3.2 && <0.5), bytestring, containers, deepseq (>=1.1 && <1.5), directory, filepath (>=1.0 && <2.0), hashable (>=1.2), microlens (<0.4.11), microlens-mtl, microlens-th, mtl (>=1.1.1.0 && <2.3), parallel (>=2.2 && <3.3), parsec (>=2 && <4), semigroups (>=0.16), stm, terminfo (>=0.3 && <0.5), text (>=0.11.3), transformers (>=0.3.0.0), unix, utf8-string (>=0.3 && <1.1), vector (>=0.7), vty [details]
License	BSD-3-Clause
Author	AUTHORS
Maintainer	Jonathan Daugherty (cygnus@foobox.com)
Category	User Interfaces
Home page	https://github.com/jtdaugherty/vty
Source repo	head: git clone https://github.com/jtdaugherty/vty.git
Uploaded	by JonathanDaugherty at 2018-11-04T15:40:58Z

Modules

[Index] [Quick Jump]

Codec
- Binary
  - UTF8
    - Codec.Binary.UTF8.Debug
Data
- Terminfo
  - Data.Terminfo.Eval
  - Data.Terminfo.Parse
Graphics
- Text
  - Graphics.Text.Width
- Graphics.Vty
  - Graphics.Vty.Attributes
  - Graphics.Vty.Config
  - Graphics.Vty.Debug
  - Graphics.Vty.DisplayAttributes
  - Graphics.Vty.Error
  - Graphics.Vty.Image
    - Graphics.Vty.Image.Internal
  - Graphics.Vty.Inline
    - Graphics.Vty.Inline.Unsafe
  - Graphics.Vty.Input
    - Graphics.Vty.Input.Classify
      - Graphics.Vty.Input.Classify.Parse
      - Graphics.Vty.Input.Classify.Types
    - Graphics.Vty.Input.Events
    - Graphics.Vty.Input.Focus
    - Graphics.Vty.Input.Loop
    - Graphics.Vty.Input.Mouse
    - Graphics.Vty.Input.Paste
    - Graphics.Vty.Input.Terminfo
  - Graphics.Vty.Output
  - Graphics.Vty.Picture
  - Graphics.Vty.PictureToSpans
  - Graphics.Vty.Span

Downloads

vty-5.25.1.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

CoreyOConnor, JonathanDaugherty

For package maintainers and hackage trustees

edit package information

Readme for vty-5.25.1

[back to package description]

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 Config for customizing vty's behavior for a particular terminal.
Uses the TIOCGWINSZ ioctl to find the current window size, which appears to be limited to Linux and BSD.

Sources

Good sources of documentation for terminal programming are:

Key	Shortcut
s	Open this search box
esc	Close this search box
↓,ctrl + j	Move down in search results
↑,ctrl + k	Move up in search results
↵	Go to active search result