Through this module, this library provides platform-independent support for control character sequences following the 'ANSI' standards (see further below) for terminal software that supports those sequences, running on a Unix-like operating system or Windows.

The sequences of control characters (also referred to as 'escape' sequences or codes) provide a rich range of functionality for terminal control, which includes:

• 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

The native terminal software on Windows is 'Command Prompt' or `PowerShell`. Before Windows 10 version 1511 (known as the 'November [2015] Update' or 'Threshold 2') that software did not support such control sequences. For that software, this library also provides support for such sequences by using emulation.

Terminal software other than the native software exists for Windows. One example is the 'mintty' terminal emulator for 'Cygwin', 'MSYS' or 'MSYS2', and dervied projects, and for 'WSL' (Windows Subsystem for Linux).

The 'ANSI' standards refer to (1) standard ECMA-48 `Control Functions for Coded Character Sets' (5th edition, 1991); (2) extensions in ITU-T Recommendation (previously CCITT Recommendation) T.416 (03/93) 'Information Technology – Open Document Architecture (ODA) and Interchange Format: Character Content Architectures` (also published as ISO/IEC International Standard 8613-6); and (3) further extensions used by 'XTerm', a terminal emulator for the X Window System. The escape codes are described in a Wikipedia article at http://en.wikipedia.org/wiki/ANSI_escape_code and those codes supported on current versions of Windows at https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences.

The whole of the 'ANSI' standards are not supported by this library but most (if not all) of the parts that are popular and well-supported by terminal software are supported. Every function exported by this module comes in three variants, namely:

• A variant that has an IO () type and doesn't take a Handle (for example, clearScreen :: IO ()). This variant just outputs the `ANSI` command directly to the standard output channel (stdout) and any terminal corresponding to it. Commands issued like this should work as you expect on both Unix-like operating systems and Windows.
• An 'h...' variant that has an IO () type but takes a Handle (for example, hClearScreen :: Handle -> IO ()). This variant outputs the `ANSI` command to the supplied handle and any terminal corresponding to it. Commands issued like this should also work as you expect on both Unix-like operating systems and Windows.
• A '...Code' variant that has a String type (for example, clearScreenCode :: String). This variant outputs the sequence of control characters as a String, which can be added to any other bit of text before being output. The use of these codes is generally discouraged because they will not work on legacy versions of Windows where the terminal in use is not ANSI-enabled (see further above). On Windows, where emulation has been necessary, these variants will always output the empty string. That is done so that it is possible to use them portably; for example, coloring console output on the understanding that you will see colors only if you are running on a Unix-like operating system or a version of Windows where emulation has not been necessary. If the control characters are always required, see module System.Console.ANSI.Codes.

Example:

module Main where

import System.Console.ANSI

-- Set colors and write some text in those colors.
main = do
  setSGR [SetColor Foreground Vivid Red]
  setSGR [SetColor Background Vivid Blue]
  putStrLn "Red-On-Blue"
  setSGR [Reset]  -- Reset to default colour scheme
  putStrLn "Default colors."

For many more examples, see the project's extensive Example.hs file.

The difference between movements "by character" and "by line" is that *Line functions additionally move the cursor to the start of the line, while functions like cursorUp and cursorDown keep the column the same.

Also keep in mind that *Line functions are not as portable. See https://github.com/feuerbach/ansi-terminal/issues/10 for the details.

Note that these functions only clear parts of the screen. They do not move the cursor.