System.Console.ANSI

Provides ANSI terminal support for Windows and ANSI terminal software running on a Unix-like operating system.

The ANSI escape codes are described at http://en.wikipedia.org/wiki/ANSI_escape_code and provide a rich range of functionality for terminal control, which includes:

• Colored text output, with control over both foreground and background colors
• Hiding or showing the cursor
• Moving the cursor around
• Clearing parts of the screen

The most frequently used parts of this ANSI command set are exposed with a platform independent interface by this module. Every function exported comes in three flavours:

• Vanilla: has an IO () type and doesn't take a Handle. This just outputs the ANSI command directly on to the terminal corresponding to stdout. Commands issued like this should work as you expect on both Windows and Unix.
• Chocolate: has an IO () type but takes a Handle. This outputs the ANSI command on the terminal corresponding to the supplied handle. Commands issued like this should also work as your expect on both Windows and Unix.
• Strawberry: has a String type and just consists of an escape code which can be added to any other bit of text before being output. This version of the API is often convenient to use, but due to fundamental limitations in Windows ANSI terminal support will only work on Unix. On Windows these codes will always be the empty string, so it is possible to use them portably for e.g. coloring console output on the understanding that you will only see colors if you are running on a Unix-like operating system.

Example:

-- Set colors and write some text in those colors.
sgrExample :: IO ()
sgrExample = do
    setSGR [SetColor Foreground Vivid Red]
    setSGR [SetColor Background Vivid Blue]
    putStr "Red-On-Blue"
    setSGR [Reset]
    putStr "White-On-Black"

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

Basic data types

data Color

ANSI colors: come in various intensities, which are controlled by ColorIntensity

Constructors

Black

Red

Green

Yellow

Blue

Magenta

Cyan

White

Instances

Bounded Color

Enum Color

Eq Color

Ord Color

Read Color

Show Color

Ix Color

data ColorIntensity

ANSI colors come in two intensities

Constructors

Dull

Vivid

Instances

Bounded ColorIntensity

Enum ColorIntensity

Eq ColorIntensity

Ord ColorIntensity

Read ColorIntensity

Show ColorIntensity

Ix ColorIntensity

data ConsoleLayer

ANSI colors can be set on two different layers

Constructors

Foreground

Background

Instances

Bounded ConsoleLayer

Enum ConsoleLayer

Eq ConsoleLayer

Ord ConsoleLayer

Read ConsoleLayer

Show ConsoleLayer

Ix ConsoleLayer

data BlinkSpeed

ANSI blink speeds: values other than NoBlink are not widely supported

Constructors

SlowBlink

Less than 150 blinks per minute

RapidBlink

More than 150 blinks per minute

NoBlink

Instances

Bounded BlinkSpeed

Enum BlinkSpeed

Eq BlinkSpeed

Ord BlinkSpeed

Read BlinkSpeed

Show BlinkSpeed

Ix BlinkSpeed

data Underlining

ANSI text underlining

Constructors

SingleUnderline

DoubleUnderline

Not widely supported

NoUnderline

Instances

Bounded Underlining

Enum Underlining

Eq Underlining

Ord Underlining

Read Underlining

Show Underlining

Ix Underlining

data ConsoleIntensity

ANSI general console intensity: usually treated as setting the font style (e.g. BoldIntensity causes text to be bold)

Constructors

BoldIntensity

FaintIntensity

Not widely supported: sometimes treated as concealing text

NormalIntensity

Instances

Bounded ConsoleIntensity

Enum ConsoleIntensity

Eq ConsoleIntensity

Ord ConsoleIntensity

Read ConsoleIntensity

Show ConsoleIntensity

Ix ConsoleIntensity

data SGR

ANSI Select Graphic Rendition command

Constructors

Reset

SetConsoleIntensity ConsoleIntensity

SetItalicized Bool

Not widely supported: sometimes treated as swapping foreground and background

SetUnderlining Underlining

SetBlinkSpeed BlinkSpeed

SetVisible Bool

Not widely supported

SetSwapForegroundBackground Bool

SetColor ConsoleLayer ColorIntensity Color

Instances

Eq SGR

Ord SGR

Read SGR

Show SGR

Cursor movement by character

cursorUp

Arguments

:: Int

Number of lines or characters to move

-> IO ()

cursorDown

Arguments

:: Int

Number of lines or characters to move

-> IO ()

cursorForward

Arguments

:: Int

Number of lines or characters to move

-> IO ()

cursorBackward

Arguments

:: Int

Number of lines or characters to move

-> IO ()

hCursorUp

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

hCursorDown

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

hCursorForward

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

hCursorBackward

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

cursorUpCode

Arguments

:: Int

Number of lines or characters to move

-> String

cursorDownCode

Arguments

:: Int

Number of lines or characters to move

-> String

cursorForwardCode

Arguments

:: Int

Number of lines or characters to move

-> String

cursorBackwardCode

Arguments

:: Int

Number of lines or characters to move

-> String

Cursor movement by line

cursorUpLine

Arguments

:: Int

Number of lines to move

-> IO ()

cursorDownLine

Arguments

:: Int

Number of lines to move

-> IO ()

hCursorUpLine

Arguments

:: Handle

-> Int

Number of lines to move

-> IO ()

hCursorDownLine

Arguments

:: Handle

-> Int

Number of lines to move

-> IO ()

cursorUpLineCode

Arguments

:: Int

Number of lines to move

-> String

cursorDownLineCode

Arguments

:: Int

Number of lines to move

-> String

Directly changing cursor position

setCursorColumn

Arguments

:: Int

0-based column to move to

-> IO ()

hSetCursorColumn

Arguments

:: Handle

-> Int

0-based column to move to

-> IO ()

setCursorColumnCode

Arguments

:: Int

0-based column to move to

-> String

setCursorPosition

Arguments

:: Int

0-based row to move to

-> Int

0-based column to move to

-> IO ()

hSetCursorPosition

Arguments

:: Handle

-> Int

0-based row to move to

-> Int

0-based column to move to

-> IO ()

setCursorPositionCode

Arguments

:: Int

0-based row to move to

-> Int

0-based column to move to

-> String

Clearing parts of the screen

clearFromCursorToScreenEnd :: IO ()

clearFromCursorToScreenBeginning :: IO ()

clearScreen :: IO ()

hClearFromCursorToScreenEnd :: Handle -> IO ()

hClearFromCursorToScreenBeginning :: Handle -> IO ()

hClearScreen :: Handle -> IO ()

clearFromCursorToScreenEndCode :: String

clearFromCursorToScreenBeginningCode :: String

clearScreenCode :: String

clearFromCursorToLineEnd :: IO ()

clearFromCursorToLineBeginning :: IO ()

clearLine :: IO ()

hClearFromCursorToLineEnd :: Handle -> IO ()

hClearFromCursorToLineBeginning :: Handle -> IO ()

hClearLine :: Handle -> IO ()

clearFromCursorToLineEndCode :: String

clearFromCursorToLineBeginningCode :: String

clearLineCode :: String

Scrolling the screen

scrollPageUp

Arguments

:: Int

Number of lines to scroll by

-> IO ()

Scroll the displayed information up or down the terminal: not widely supported

scrollPageDown

Arguments

:: Int

Number of lines to scroll by

-> IO ()

Scroll the displayed information up or down the terminal: not widely supported

hScrollPageUp

Arguments

:: Handle

-> Int

Number of lines to scroll by

-> IO ()

Scroll the displayed information up or down the terminal: not widely supported

hScrollPageDown

Arguments

:: Handle

-> Int

Number of lines to scroll by

-> IO ()

Scroll the displayed information up or down the terminal: not widely supported

scrollPageUpCode

Arguments

:: Int

Number of lines to scroll by

-> String

Scroll the displayed information up or down the terminal: not widely supported

scrollPageDownCode

Arguments

:: Int

Number of lines to scroll by

-> String

Scroll the displayed information up or down the terminal: not widely supported

Select Graphic Rendition mode: colors and other whizzy stuff

setSGR

Arguments

:: [SGR]

Commands: these will typically be applied on top of the current console SGR mode. An empty list of commands is equivalent to the list [Reset]. Commands are applied left to right.

-> IO ()

Set the Select Graphic Rendition mode

hSetSGR

Arguments

:: Handle

-> [SGR]

Commands: these will typically be applied on top of the current console SGR mode. An empty list of commands is equivalent to the list [Reset]. Commands are applied left to right.

-> IO ()

Set the Select Graphic Rendition mode

setSGRCode

Arguments

:: [SGR]

Commands: these will typically be applied on top of the current console SGR mode. An empty list of commands is equivalent to the list [Reset]. Commands are applied left to right.

-> String

Set the Select Graphic Rendition mode

Cursor visibilty changes

hideCursor :: IO ()

showCursor :: IO ()

hHideCursor :: Handle -> IO ()

hShowCursor :: Handle -> IO ()

hideCursorCode :: String

showCursorCode :: String

Changing the title

setTitle

Arguments

:: String

New title

-> IO ()

Set the terminal window title

hSetTitle

Arguments

:: Handle

-> String

New title

-> IO ()

Set the terminal window title

setTitleCode

Arguments

:: String

New title

-> String

Set the terminal window title

Thanks to Brandon S. Allbery and Curt Sampson for pointing me in the right direction on xterm title setting on haskell-cafe. The "0" signifies that both the title and "icon" text should be set: i.e. the text for the window in the Start bar (or similar) as well as that in the actual window title. This is chosen for consistent behaviour between Unixes and Windows.

Checking if handle supports ANSI

hSupportsANSI :: Handle -> IO Bool

Use heuristics to determine whether the functions defined in this package will work with a given handle.

The current implementation checks that the handle is a terminal, and that the TERM environment variable doesn't say dumb (whcih is what Emacs sets for its own terminal).