AIHC Haddock

Community
Modules 2

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.

Basic data types

module System.Console.ANSI.Types ansi-terminal-types-1.1.3 · 10 declarations

xterm24LevelGray :: Int -> Word8

Given xterm's standard protocol for a 256-color palette, returns the index to that part of the palette which is a spectrum of 24 grays, from dark gray (0) to near white (23) (black and white are themselves excluded). Throws an error if the gray is outside of the range 0 to 23. An example of use is:

xterm6LevelRGB :: Int -> Int -> Int -> Word8

Given xterm's standard protocol for a 256-color palette, returns the index to that part of the palette which is a 6 level (6x6x6) color cube of 216 RGB colors. Throws an error if any of the red, green or blue channels is outside the range 0 to 5. An example of use is:

xtermSystem :: ColorIntensity -> Color -> Word8

Given xterm's standard protocol for a 256-color palette, returns the index to that part of the palette which corresponds to the 'ANSI' standards' 16 standard, or 'system', colors (eight colors in two intensities). An example of use is:

data BlinkSpeed

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

data Color

ANSI's eight standard colors. They come in two intensities, which are controlled by ColorIntensity. Many terminals allow the colors of the standard palette to be customised, so that, for example, setSGR [ SetColor Foreground Vivid Green ] may not result in bright green characters.

data ColorIntensity

ANSI's standard colors come in two intensities

Dull :: ColorIntensity

Vivid :: ColorIntensity

data SGR

ANSI Select Graphic Rendition (SGR) command

In respect of colors, there are three alternative commands:

  1. the 'ANSI' standards allow for eight standard colors (with two intensities). Windows and many other terminals (including xterm) allow the user to redefine the standard colors (so, for example Vivid Green may not correspond to bright green;

  1. an extension of the standard that allows true colors (24 bit color depth) in RGB space. This is usually the best alternative for more colors; and

  1. another extension that allows a palette of 256 colors, each color specified by an index. Xterm provides a protocol for a palette of 256 colors that many other terminals, including Windows 10, follow. Some terminals (including xterm) allow the user to redefine some or all of the palette colors.

SetColor :: ConsoleLayer -> ColorIntensity -> Color -> SGR

Cursor movement by character

| These functions yield "" when the number is 0 as, on some terminals, a 0 parameter for the underlying 'ANSI' code specifies a default parameter of 1.

cursorUpCode :: Int -> String

Int

Number of lines or characters to move

cursorDownCode :: Int -> String

Int

Number of lines or characters to move

Cursor movement by line

| These functions yield the equivalent of setCursorColumnCode 0 when the number is 0 as, on some terminals, a 0 parameter for the underlying 'ANSI' code specifies a default parameter of 1.

Directly changing cursor position

setCursorColumnCode :: Int -> 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).

Int

0-based column to move to

setCursorPositionCode :: Int -> Int -> 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).

Int

0-based row to move to

Int

0-based column to move to

Saving, restoring and reporting cursor position

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.

Clearing parts of the screen

Enabling and disabling automatic line wrapping

| These functions control whether or not characters automatically wrap to the next line when the cursor reaches the right border.

Scrolling the screen

| These functions yield "" when the number is 0 as, on some terminals, a 0 parameter for the underlying 'ANSI' code specifies a default parameter of 1.

Using screen buffers

Reporting background or foreground colors

reportLayerColorCode :: ConsoleLayer -> String

Code to emit the foreground or backgrond layer color into the console input stream, immediately after being recognised on the output stream, as:

ESC ] <Ps> ; rgb: <red> ; <green> ; <blue> <ST>

where <Ps> is 10 for Foreground and 11 for Background; <red>, <green> and <blue> are the color channel values in hexadecimal (4, 8, 12 and 16 bit values are possible, although 16 bit values are most common); and <ST> is the STRING TERMINATOR (ST). ST depends on the terminal software and may be the BEL character or ESC \ characters.

This function may be of limited, or no, use on Windows operating systems because (1) the control character sequence is not supported on native terminals (2) of difficulties in obtaining the data emitted into the console input stream. See getReportedLayerColor.

Underlining is not supported.

Select Graphic Rendition mode: colors and other whizzy stuff

setSGRCode :: [SGR] -> String

[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.

Cursor visibilty changes

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

hyperlinkCode :: String -> String -> String

Code to introduce a hyperlink.

String

URI

String

Link text

hyperlinkWithIdCode :: String -> String -> String -> 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.

String

Identifier for the link

String

URI

String

Link text

hyperlinkWithParamsCode :: [(String, String)] -> String -> String -> 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.

[(String, String)]

Parameters

String

URI

String

Link text

Changing the title

setTitleCode :: String -> 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).

String

New window title and icon name

Utilities

colorToCode :: Color -> Int

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

type Parameter = Int

Type synonym representing parameter values (without parameter substrings). To represent a paramater value followed by a parameter substring, see ParamWithSubs.

type SubParam = Maybe Int

Type synonym representing parameter elements of a parameter substring. An empty parameter element (which represents a default value for the parameter element) has value Nothing.

type ParamWithSubs = (Parameter, [SubParam])

Type synonym representing parameter values optionally followed by a parameter substring. Parameter substrings were introduced by 13.1.8 of T.416 (03/93) for SGR parameter values 38 and 48 and have subsequently been adapted for other uses.

csi :: [Parameter] -> String -> 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. See csi' for a function that handles parameter values that may be followed by a parameter substring.

[Parameter]

List of parameters for the control sequence.

String

Character(s) that identify the control function.

csi' :: [ParamWithSubs] -> String -> String

Like csi but extended to parameters that may be followed by a parameter substring. The parameter elements of a parameter substring are separated from the parameter value and each other by ':'.

[ParamWithSubs]

List of parameters (each of which may be followed by a parameter substring).

String

Characters(s) that identify the control function.

osc :: String -> String -> String

osc parameterS parametersT, where parameterS specifies the type of operation to perform and parametersT is the other parameter(s) (if any), returns the control sequence comprising the control function OPERATING SYSTEM COMMAND (OSC) followed by the parameters (separated by ';') and ending with the STRING TERMINATOR (ST) "\ESC\\".

String

Ps parameter

String

Pt parameter(s)

sgrToCode :: SGR -> [Parameter]

sgrToCode sgr returns the parameter of the SELECT GRAPHIC RENDITION (SGR) aspect identified by sgr. If the parameter is followed by a parameter substring returns an empty list. See sgrToCode' for a function that handles also parameter values that are followed by a parameter substring.

SGR

The SGR aspect

sgrToCode' :: SGR -> Either ParamWithSubs [Parameter]

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

SGR

The SGR aspect

Build record and source files

Community contribution. The service has not verified this documentation. The generator reported 12 diagnostics.

Target: Linux on x86-64. Some inferred types and resolved links are not available.

Generator: aihc-haddock-aa6debbd-web-3

Metadata snapshot: 657daf55323efbace376e4c5ba45e174010a761423ed513e5feb28ad359b2638

Open the dependency plan · Download the documentation model

Import a package

Enter a package name and an exact version from Hackage. The site contains imported versions only.