ansi-terminal: Simple ANSI terminal support

[ bsd3, library, user-interfaces ] [ Propose Tags ]

ANSI terminal support for Haskell: allows cursor movement, screen clearing, color output, showing or hiding the cursor, and changing the title. Works on UNIX and Windows.


[Skip to Readme]

Modules

[Index] [Quick Jump]

Flags

Automatic Flags
NameDescriptionDefault
example

Build the example application

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1, 0.2, 0.2.1, 0.3.0, 0.3.1, 0.4.0, 0.5.0, 0.5.1, 0.5.2, 0.5.3, 0.5.4, 0.5.5, 0.5.5.1, 0.6, 0.6.1, 0.6.1.1, 0.6.2, 0.6.2.1, 0.6.2.2, 0.6.2.3, 0.6.3, 0.6.3.1, 0.7, 0.7.1, 0.7.1.1, 0.8, 0.8.0.1, 0.8.0.2, 0.8.0.3, 0.8.0.4, 0.8.1, 0.8.2, 0.9, 0.9.1, 0.10, 0.10.1, 0.10.2, 0.10.3, 0.11, 0.11.1, 0.11.2, 0.11.3, 0.11.4, 0.11.5, 1.0, 1.0.1, 1.0.2, 1.1, 1.1.1 (info)
Change log CHANGELOG.md
Dependencies ansi-terminal, ansi-terminal-types (==1.1), base (>=4.8.0.0 && <5), colour (>=2.1.0) [details]
License BSD-3-Clause
Author Max Bolingbroke
Maintainer Mike Pilgrem <public@pilgrem.com>, Roman Cheplyaka <roma@ro-che.info>
Category User Interfaces
Home page https://github.com/UnkindPartition/ansi-terminal
Source repo head: git clone git://github.com/UnkindPartition/ansi-terminal.git
Uploaded by mpilgrem at 2024-04-23T23:02:24Z
Distributions Arch:0.11.4, Debian:0.10.3, Fedora:0.11.5, FreeBSD:0.6.2.1, LTSHaskell:1.0.2, NixOS:1.0.2, Stackage:1.1.1, openSUSE:1.0.2
Reverse Dependencies 220 direct, 4573 indirect [details]
Executables ansi-terminal-example
Downloads 392344 total (1257 in the last 30 days)
Rating 2.5 (votes: 3) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-04-23 [all 1 reports]

Readme for ansi-terminal-1.1.1

[back to package description]

ansi-terminal GitHub CI

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 foreground, background and (where supported) underlining 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
  • Switching between the Alternate and Normal Screen Buffers
  • Clickable hyperlinks to URIs
  • Changing the title of the terminal

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.

Example

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

import System.Console.ANSI
import System.IO (stdout)

main :: IO ()
main = do
  stdoutSupportsANSI <- hNowSupportsANSI stdout
  if stdoutSupportsANSI
    then 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!"
    else
      putStrLn "Standard output does not support 'ANSI' escape codes."

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.