README.md
1ansi-terminal
2=============
3
4A Haskell package providing support for 'ANSI' control character sequences for
5terminals on Unix-like operating systems and Windows
6
7Description
8-----------
9
10['ANSI' terminal escape code](http://en.wikipedia.org/wiki/ANSI_escape_sequences)
11support for Haskell, which allows:
12- Colored text output, with control over both foreground and background
13 colors
14- Clearing parts of a line or the screen
15- Hiding or showing the cursor
16- Moving the cursor around
17- Reporting the position of the cursor
18- Scrolling the screen up or down
19- Changing the title of the terminal
20
21By using emulation, it is compatible with versions of 'Command Prompt' and
22'PowerShell' on Windows that did not recognise 'ANSI' escape codes before
23Windows 10 version 1511 was released in November 2015.
24
25If you like this, you may be interested in
26[ansi-wl-pprint](http://github.com/batterseapower/ansi-wl-pprint), which
27provides a pretty-printer that can construct strings containing 'ANSI'
28colorisation.
29
30Not all 'ANSI' escape codes are suported by this library but most (if not
31all) of the popular ones that are well-supported by terminal software are,
32including:
33- Select Graphic Rendition mode (colors and other attributes): `setSGR`
34- Clearing parts of the screen: `clearFromCursorToScreenEnd`,
35 `clearFromCursorToScreenBeginning`, `clearScreen`,
36 `clearFromCursorToLineEnd`, `clearFromCursorToLineBeginning` and
37 `clearLine`
38- Cursor visibility changes: `hideCursor` and `showCursor`
39- Cursor movement by character: `cursorUp`, `cursorDown`, `cursorForward` and
40 `cursorBackward`
41- Cursor movement by line: `cursorUpLine` and `cursorDownLine`
42- Directly changing cursor position: `setCursorColumn` and `setCursorPosition`
43- Saving, restoring and reporting cursor position: `saveCursor`,
44 `restoreCursor` and `reportCursorPosition`
45- Scrolling the screen: `scrollPageUp` and `scrollPageDown`
46- Changing the title: `setTitle`
47
48Each supported escape code or family of codes has a corresponding
49function that comes in three variants:
50
51- A straight `IO` variant that doesn't take a `Handle` and just applies the
52 escape code to `stdout` and any terminal attached to it
53- An `IO` variant similar to above, but which takes a `Handle` to which the
54 escape code should be applied
55- A `String` variant that returns a literal string that should be
56 included to get the effect of the code. However, on Windows systems where
57 emulation has been necessary, these strings will always be blank!
58
59Example
60-------
61
62A full example is
63[available](https://github.com/feuerbach/ansi-terminal/blob/master/app/Example.hs),
64but for a taste of how the library works try the following code:
65
66``` haskell
67import System.Console.ANSI
68
69main = do
70 setCursorPosition 5 0
71 setTitle "ANSI Terminal Short Example"
72
73 setSGR [ SetConsoleIntensity BoldIntensity
74 , SetColor Foreground Vivid Red
75 ]
76 putStr "Hello"
77
78 setSGR [ SetConsoleIntensity NormalIntensity
79 , SetColor Foreground Vivid White
80 , SetColor Background Dull Blue
81 ]
82 putStrLn "World!"
83```
84
85
86
87Documentation
88-------------
89
90Haddock documentation is [available at
91Hackage](http://hackage.haskell.org/packages/archive/ansi-terminal/latest/doc/html/System-Console-ANSI.html).
92
93Credits
94-------
95
96The library is originally written by [Max Bolingbroke](https://github.com/batterseapower)
97
98Maintainers
99-----------
100
101[Mike Pilgrem](https://github.com/mpilgrem) and [Roman Cheplyaka](https://github.com/feuerbach) are the primary maintainers.
102
103[Oliver Charles](https://github.com/ocharles) is the backup maintainer. Please
104get in touch with him if the primary maintainers cannot be reached.
105
){kind=link}