Simple ANSI terminal support, with Windows compatibility
|Version on this page:||0.10.3|
|LTS Haskell 20.23:||0.11.4|
|Stackage Nightly 2023-05-30:||0.11.5|
|Latest on Hackage:||1.0|
Module documentation for 0.10.3
A Haskell package providing support for ‘ANSI’ control character sequences for terminals on Unix-like operating systems and Windows
‘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):
- Clearing parts of the screen:
- Cursor visibility changes:
- Cursor movement by character:
- Cursor movement by line:
- Directly changing cursor position:
- Saving, restoring and reporting cursor position:
- Scrolling the screen:
- Changing the title:
Each supported escape code or family of codes has a corresponding function that comes in three variants:
- A straight
IOvariant that doesn’t take a
Handleand just applies the escape code to
stdoutand any terminal attached to it
IOvariant similar to above, but which takes a
Handleto which the escape code should be applied
Stringvariant 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!
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!"
Haddock documentation is available at Hackage.
The library is originally written by Max Bolingbroke
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.
getCursorPositionas a synonym of
getCursorPosition0and deprecate the latter.
hGetTerminalSizenow assumes a terminal is no bigger than 9,999 by 9,999 (previously, no bigger than 999 by 999).
- On Windows, fix a bug where emulated cursor movement functions differed from Windows 10 (movement bounded by the current viewport).
- On Unix-like operating systems, fix a bug where
getReportedCursorPositioncould block indefinitely if no information was forthcoming on the console input stream.
- Improvements to Haddock documentation.
- Add support for setting the default color with new
SetDefaultColorconstructor of the
getTerminalSizenow flushes the
stdoutchannel, to ensure the cursor position is unaffected.
- Flag modules with GHC’s ‘Safe Haskell’ language extensions (from GHC 7.2.1).
- Improvements and corrections to Haddock documentation.
- Add support for 256-color palettes with new
SetPaletteColorconstructor of the
- Remove deprecated
- Improvements to Haddock documentation.
getCursorPosition. Any position provided by the latter is 1-based. Any position provided by the former is 0-based, consistent with
- Improvements to Haddock documentation in respect of 0-based and 1-based cursor positions.
hSupportsANSIWithoutEmulation. On Windows 10, if the handle is identifed as connected to a native terminal (‘Command Prompt’ or ‘PowerShell’), the processing of ‘ANSI’ control characters will be enabled.
- On Windows,
hSupportsANSInow recognises if the handle is connected to a ‘mintty’ terminal.
- Drop support for GHC versions before GHC 7.0.1 (released November 2010)
- 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
- 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)
- 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
- Make the fields of
- 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
getReportedCursorPosition: don’t let the cursor reporting code be echo’d
- Allow saving, restoring, and querying the current cursor position
- Fix a couple of issues with the Reset emulation on Windows
Add 24-bit RGB color support
Fix Windows + ghc 7.8 compatibility
- Add ANSI support for Windows
- Add compatibility with Win32-126.96.36.199 and above
Add an example to the haddocks
Fix a GHC 7.10 warning
Restore compatibility with GHC 7.4 and older
- Drop support for
base < 4
Fix to build with GHC 7.8 on Windows
BoldIntensityno 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.