ansi-terminal
Simple ANSI terminal support, with Windows compatibility
https://github.com/UnkindPartition/ansi-terminal
Version on this page: | 0.11.5 |
LTS Haskell 22.37: | 1.0.2 |
Stackage Nightly 2024-10-07: | 1.1.1 |
Latest on Hackage: | 1.1.1 |
ansi-terminal-0.11.5@sha256:2fe3d006b9ea0dc1a5537a029edb0bc2bbe56a33a6d95264b38b54c58e931e51,3752
Module documentation for 0.11.5
- System
- System.Console
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
- Switching between the Alternate and Normal Screen Buffers
- Clickable hyperlinks to URIs
- 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
andclearLine
- Cursor visibility changes:
hideCursor
andshowCursor
- Cursor movement by character:
cursorUp
,cursorDown
,cursorForward
andcursorBackward
- Cursor movement by line:
cursorUpLine
andcursorDownLine
- Directly changing cursor position:
setCursorColumn
andsetCursorPosition
- Saving, restoring and reporting cursor position:
saveCursor
,restoreCursor
andreportCursorPosition
- Scrolling the screen:
scrollPageUp
andscrollPageDown
- 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 aHandle
and just applies the escape code tostdout
and any terminal attached to it - An
IO
variant similar to above, but which takes aHandle
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.11.5
- Module
System.Console.ANSI.Types
spun out to new dependency packageansi-terminal-types-0.11.5
. - Drop support for GHC versions before GHC 7.10.1 (released March 2015).
- Improvements to Haddock documentation.
Version 0.11.4
- Add
reportLayerColor
,getReportedLayerColor
andgetLayerColor
for querying the layer color on terminals that support the functionality. - Add
useAlternateScreenBuffer
anduseNormalScreenBuffer
, and support for switching between the Alternate and Normal Screen Buffers. - When the argument is
0
,cursorUpCode
,cursorDownCode
,cursorForwardCode
,cursorBackwardCode
,scrollPageUpCode
andscrollPageDownCode
now yield""
, andcursorUpLineCode
andcursorDownLineCode
now yield the equivalent ofsetCursorColumnCode 0
. This is because, on some terminals, a0
parameter for the underlying ‘ANSI’ code specifies a default parameter of1
. - Add
osc
as a utility function, for OSC sequences. setTitle
now uses the recommended STRING TERMINATOR (ST) of\ESC\\
, rather than the legacy\BEL
(\007
), and filters the title of all non-printable characters, not just\BEL
.- Improvements to Haddock documentation.
Version 0.11.3
- Add
hyperlink
,hyperlinkWithId
andhyperlinkWithParams
, and support for clickable hyperlinks.
Version 0.11.2
- On Windows, fix compatability with the Windows I/O Manager (WinIO) when
GHC >= 9.0.1 but
Win32
< 2.9.0.0. - Improvements to Haddock documentation.
Version 0.11.1
- On Windows, fix compatability with the Windows I/O Manager (WinIO) introduced
in GHC 9.0.1, by incorporating changes made in package
Win32-2.13.2.0
in that regard. - Improvements to Haddock documentation.
Version 0.11
- Remove deprecated
getCursorPosition0
. (UsegetCursorPosition
instead.) - On Unix-like operating systems, the temporary turning off of echoing is moved
from
getReportedCursorPosition
tohGetCursorPositon
. - On Unix-like operating systems, fix a bug in
getCursorPosition
andhGetCursorPosition
, where the console input stream was was not always clear before the cursor position was emitted into it.
Version 0.10.3
- Add
getCursorPosition
as a synonym ofgetCursorPosition0
and deprecate the latter.
Version 0.10.2
hGetTerminalSize
now 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).
Version 0.10.1
- Add
hGetCursorPosition
andhGetTerminalSize
. - On Unix-like operating systems, fix a bug where
getReportedCursorPosition
could block indefinitely if no information was forthcoming on the console input stream. - Improvements to Haddock documentation.
Version 0.10
- Add support for setting the default color with new
SetDefaultColor
constructor of theSGR
type. getTerminalSize
now flushes thestdout
channel, to ensure the cursor position is unaffected.
Version 0.9.1
- Flag modules with GHC’s ‘Safe Haskell’ language extensions (from GHC 7.2.1).
- Improvements and corrections to Haddock documentation.
Version 0.9
- Add support for 256-color palettes with new
SetPaletteColor
constructor of theSGR
type, andxterm6LevelRGB
,xterm24LevelGray
andxtermSystem
. - Remove deprecated
getCursorPosition
. (UsegetCursorPosition0
instead.) - Add
hSupportsANSIColor
. - Add
getTerminalSize
. - Improvements to Haddock documentation.
Version 0.8.2
- Add
getCursorPosition0
and deprecategetCursorPosition
. Any position provided by the latter is 1-based. Any position provided by the former is 0-based, consistent withsetCursorColumn
andsetCursorPosition
. - Improvements to Haddock documentation in respect of 0-based and 1-based cursor positions.
Version 0.8.1
- Add
hSupportsANSIWithoutEmulation
. On Windows 10, if the handle is identified as connected to a native terminal (‘Command Prompt’ or ‘PowerShell’), the processing of ‘ANSI’ control characters will be enabled.
Version 0.8.0.4
- On Windows,
hSupportsANSI
now recognises if the handle is connected to a ‘mintty’ terminal. - Drop support for GHC versions before GHC 7.0.1 (released November 2010)
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 WindowssetSGR []
was not equivalent tosetSGR [Reset]
on Windows, even though it should be according to the documentation. This is now fixed.