System.Console.ANSI.Codes

This module exports functions that return String values containing codes in accordance with the 'ANSI' standards for control character sequences described in the documentation of module System.Console.ANSI.

The module System.Console.ANSI exports functions with the same names as those in this module. On some versions of Windows, the terminal in use may not be ANSI-capable. When that is the case, the same-named functions exported by module System.Console.ANSI return "", for the reasons set out in the documentation of that module.

Consequently, if module System.Console.ANSI is also imported, this module is intended to be imported qualified, to avoid name clashes with those functions. For example:

import qualified System.Console.ANSI.Codes as ANSI

Basic data types

module System.Console.ANSI.Types

Cursor movement by character

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

cursorUpLineCode

Arguments

:: Int

Number of lines to move

-> String

cursorDownLineCode

Arguments

:: Int

Number of lines to move

-> String

Directly changing cursor position

setCursorColumnCode

Arguments

:: Int

0-based column to move to

-> String

Code to move the cursor to the specified column. The column numbering is 0-based (that is, the left-most column is numbered 0).

setCursorPositionCode

Arguments

:: Int

0-based row to move to

-> Int

0-based column to move to

-> String

Code to move the cursor to the specified position (row and column). The position is 0-based (that is, the top-left corner is at row 0 column 0).

Saving, restoring and reporting cursor position

saveCursorCode :: String

Since: 0.7.1

restoreCursorCode :: String

Since: 0.7.1

reportCursorPositionCode :: String

Code to emit the cursor position into the console input stream, immediately after being recognised on the output stream, as: ESC [ <cursor row> ; <cursor column> R

Note that the information that is emitted is 1-based (the top-left corner is at row 1 column 1) but setCursorPositionCode is 0-based.

In isolation of getReportedCursorPosition or getCursorPosition, this function may be of limited use on Windows operating systems because of difficulties in obtaining the data emitted into the console input stream. The function hGetBufNonBlocking in module System.IO does not work on Windows. This has been attributed to the lack of non-blocking primatives in the operating system (see the GHC bug report #806 at https://ghc.haskell.org/trac/ghc/ticket/806).

Since: 0.7.1

Clearing parts of the screen

clearFromCursorToScreenEndCode :: String

clearFromCursorToScreenBeginningCode :: String

clearScreenCode :: String

clearFromCursorToLineEndCode :: String

clearFromCursorToLineBeginningCode :: String

clearLineCode :: String

Scrolling the screen

scrollPageUpCode

Arguments

:: Int

Number of lines to scroll by

-> String

scrollPageDownCode

Arguments

:: Int

Number of lines to scroll by

-> String

Select Graphic Rendition mode: colors and other whizzy stuff

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

Cursor visibilty changes

hideCursorCode :: String

showCursorCode :: String

Hyperlinks

Some, but not all, terminals support hyperlinks - that is, clickable text that points to a URI.

hyperlinkCode

Arguments

:: String

URI

-> String

Link text

-> String

Code to introduce a hyperlink.

Since: 0.11.3

hyperlinkWithIdCode

Arguments

:: String

Identifier for the link

-> String

URI

-> String

Link text

-> String

Code to introduce a hyperlink with an identifier for the link. Some terminals support an identifier, so that hyperlinks with the same identifier are treated as connected.

Since: 0.11.3

hyperlinkWithParamsCode

Arguments

:: [(String, String)]

Parameters

-> String

URI

-> String

Link text

-> String

Code to introduce a hyperlink with (key, value) parameters. Some terminals support an id parameter key, so that hyperlinks with the same id value are treated as connected.

Since: 0.11.3

Changing the title

setTitleCode

Arguments

:: String

New window title and icon name

-> String

Code to set the terminal window title and the icon name (that is, the text for the window in the Start bar, or similar).

Utilities

colorToCode :: Color -> Int

colorToCode color returns the 0-based index of the color (one of the eight colors in the ANSI standard).

csi

Arguments

:: [Int]

List of parameters for the control sequence

-> String

Character(s) that identify the control function

-> String

csi parameters controlFunction, where parameters is a list of Int, returns the control sequence comprising the control function CONTROL SEQUENCE INTRODUCER (CSI) followed by the parameter(s) (separated by ';') and ending with the controlFunction character(s) that identifies the control function.

sgrToCode

Arguments

:: SGR

The SGR aspect

-> [Int]

sgrToCode sgr returns the parameter of the SELECT GRAPHIC RENDITION (SGR) aspect identified by sgr.