ansi-terminal-0.5.5: Simple ANSI terminal support, with Windows compatibility

Safe HaskellSafe-Infered

System.Console.ANSI

Contents

Description

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.

Synopsis

Basic data types

data Color Source

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

Constructors

Black 
Red 
Green 
Yellow 
Blue 
Magenta 
Cyan 
White 

data ColorIntensity Source

ANSI colors come in two intensities

Constructors

Dull 
Vivid 

data ConsoleLayer Source

ANSI colors can be set on two different layers

Constructors

Foreground 
Background 

data BlinkSpeed Source

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 

data Underlining Source

ANSI text underlining

Constructors

SingleUnderline 
DoubleUnderline

Not widely supported

NoUnderline 

data ConsoleIntensity Source

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 

data SGR Source

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 

Cursor movement by character

cursorUp,cursorBackward,cursorForward,cursorDownSource

Arguments

:: Int

Number of lines or characters to move

-> IO () 

hCursorUp,hCursorBackward,hCursorForward,hCursorDownSource

Arguments

:: Handle 
-> Int

Number of lines or characters to move

-> IO () 

cursorUpCode,cursorBackwardCode,cursorForwardCode,cursorDownCodeSource

Arguments

:: Int

Number of lines or characters to move

-> String 

Cursor movement by line

cursorDownLine,cursorUpLineSource

Arguments

:: Int

Number of lines to move

-> IO () 

hCursorDownLine,hCursorUpLineSource

Arguments

:: Handle 
-> Int

Number of lines to move

-> IO () 

cursorDownLineCode,cursorUpLineCodeSource

Arguments

:: Int

Number of lines to move

-> String 

Directly changing cursor position

setCursorColumnSource

Arguments

:: Int

0-based column to move to

-> IO () 

hSetCursorColumnSource

Arguments

:: Handle 
-> Int

0-based column to move to

-> IO () 

setCursorColumnCodeSource

Arguments

:: Int

0-based column to move to

-> String 

setCursorPositionSource

Arguments

:: Int

0-based row to move to

-> Int

0-based column to move to

-> IO () 

hSetCursorPositionSource

Arguments

:: Handle 
-> Int

0-based row to move to

-> Int

0-based column to move to

-> IO () 

setCursorPositionCodeSource

Arguments

:: Int

0-based row to move to

-> Int

0-based column to move to

-> String 

Clearing parts of the screen

Scrolling the screen

scrollPageUp,scrollPageDownSource

Arguments

:: Int

Number of lines to scroll by

-> IO () 

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

hScrollPageUp,hScrollPageDownSource

Arguments

:: Handle 
-> Int

Number of lines to scroll by

-> IO () 

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

scrollPageUpCode,scrollPageDownCodeSource

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

setSGRSource

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

hSetSGRSource

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

setSGRCodeSource

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

Changing the title

setTitleSource

Arguments

:: String

New title

-> IO () 

Set the terminal window title

hSetTitleSource

Arguments

:: Handle 
-> String

New title

-> IO () 

Set the terminal window title

setTitleCodeSource

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.