ansi-terminal

Simple ANSI terminal support, with Windows compatibility https://github.com/feuerbach/ansi-terminal

Version on this page:0.7.1.1
LTS Haskell 11.14:0.8.0.4
Stackage Nightly 2018-06-19:0.8.0.4
Latest on Hackage:0.8.0.4

See all snapshots ansi-terminal appears in

BSD3 licensed by Max Bolingbroke
Maintained by Mike Pilgrem, Roman Cheplyaka

Module documentation for 0.7.1.1

ansi-terminal

A Haskell package providing support for 'ANSI' control character sequences for terminals on Unix-like operating systems and Windows

Description

'ANSI' terminal escape code support for Haskell, which allows:

  • Colored text output, with control over both foreground and background colors
  • Clearing parts of a line or the screen
  • Hiding or showing the cursor
  • Moving the cursor around
  • Reporting the position of the cursor
  • Scrolling the screen up or down
  • Changing the title of the terminal

By using emulation, it is compatible with versions of 'Command Prompt' and 'PowerShell' on Windows that did not recognise 'ANSI' escape codes before Windows 10 version 1511 was released in November 2015.

If you like this, you may be interested in ansi-wl-pprint, which provides a pretty-printer that can construct strings containing 'ANSI' colorisation.

Not all 'ANSI' escape codes are suported by this library but most (if not all) of the popular ones that are well-supported by terminal software are, including:

  • Select Graphic Rendition mode (colors and other attributes): setSGR
  • Clearing parts of the screen: clearFromCursorToScreenEnd, clearFromCursorToScreenBeginning, clearScreen, clearFromCursorToLineEnd, clearFromCursorToLineBeginning and clearLine
  • Cursor visibility changes: hideCursor and showCursor
  • Cursor movement by character: cursorUp, cursorDown, cursorForward and cursorBackward
  • Cursor movement by line: cursorUpLine and cursorDownLine
  • Directly changing cursor position: setCursorColumn and setCursorPosition
  • Saving, restoring and reporting cursor position: saveCursor, restoreCursor and reportCursorPosition
  • Scrolling the screen: scrollPageUp and scrollPageDown
  • Changing the title: setTitle

Each supported escape code or family of codes has a corresponding function that comes in three variants:

  • A straight IO variant that doesn't take a Handle and just applies the escape code to stdout and any terminal attached to it
  • An IO variant similar to above, but which takes a Handle to which the escape code should be applied
  • A String variant that returns a literal string that should be included to get the effect of the code. However, on Windows systems where emulation has been necessary, these strings will always be blank!

Example

A full example is available, but for a taste of how the library works try the following code:

import System.Console.ANSI

main = do
    setCursorPosition 5 0
    setTitle "ANSI Terminal Short Example"

    setSGR [ SetConsoleIntensity BoldIntensity
           , SetColor Foreground Vivid Red
           ]
    putStr "Hello"

    setSGR [ SetConsoleIntensity NormalIntensity
           , SetColor Foreground Vivid White
           , SetColor Background Dull Blue
           ]
    putStrLn "World!"

Documentation

Haddock documentation is available at Hackage.

Credits

The library is originally written by Max Bolingbroke

Maintainers

Mike Pilgrem and Roman Cheplyaka are the primary maintainers.

Oliver Charles is the backup maintainer. Please get in touch with him if the primary maintainers cannot be reached.

Changes

Changes

Version 0.8.0.4

  • On Windows, hSupportsANSI now recognises if the handle is connected to a 'mintty' terminal.

Version 0.8.0.3

  • On Windows, try to enable ANSI on ConHost terminals even if a TERM environment variable exits (such as with the Hyper 2 terminal)
  • Minor improvements to Haddock documentation

Version 0.8.0.2

  • Improve README and Haddock documentation
  • On Windows, fix compatability with earlier GHC versions
  • Drop support for GHC versions before 6.12.1 (released December 2009)

Version 0.8.0.1

  • On Windows, if the standard output channel is valid but not a ConHost terminal, assume it is ANSI-enabled rather than failing
  • On Windows, output the improved error message to the standard error channel rather than the standard output channel

Version 0.8

  • Make the fields of SGR strict
  • Make compatible with GHC 8.2.2
  • Improve the error message on Windows when not ANSI-capable or ConHost
  • Recognise Appveyor build environment as ANSI-enabled

Version 0.7.1.1

getReportedCursorPosition: don't let the cursor reporting code be echo'd

Version 0.7.1

  • Allow saving, restoring, and querying the current cursor position
  • Fix a couple of issues with the Reset emulation on Windows

Version 0.7

Add 24-bit RGB color support

Version 0.6.3.1

Fix Windows + ghc 7.8 compatibility

Version 0.6.3

  • Add ANSI support for Windows
  • Add compatibility with Win32-2.5.0.0 and above

Version 0.6.2.3

Add an example to the haddocks

Version 0.6.2.2

Fix a GHC 7.10 warning

Version 0.6.2.1

Restore compatibility with GHC 7.4 and older

Version 0.6.2

  • Add hSupportsANSI
  • Drop support for base < 4

Version 0.6.1.1

Fix to build with GHC 7.8 on Windows

Version 0.6.1

  • BoldIntensity no longer changes background color on Windows
  • setSGR [] was not equivalent to setSGR [Reset] on Windows, even though it should be according to the documentation. This is now fixed.
comments powered byDisqus