System.Console.ANSI.Codes

ansi-terminal-1.1.2: Simple ANSI terminal support

Safe Haskell | Safe
Language | Haskell2010

System.Console.ANSI.Codes

Contents

- Basic data types
- Cursor movement by character
- Cursor movement by line
- Directly changing cursor position
- Saving, restoring and reporting cursor position
- Clearing parts of the screen
- Enabling and disabling automatic line wrapping
- Scrolling the screen
- Using screen buffers
- Reporting background or foreground colors
- Select Graphic Rendition mode: colors and other whizzy stuff
- Cursor visibilty changes
- Hyperlinks
- Changing the title
- Utilities

Description

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.

Synopsis

- module System.Console.ANSI.Types
- cursorUpCode :: Int -> String
- cursorDownCode :: Int -> String
- cursorForwardCode :: Int -> String
- cursorBackwardCode :: Int -> String
- cursorUpLineCode :: Int -> String
- cursorDownLineCode :: Int -> String
- setCursorColumnCode :: Int -> String
- setCursorPositionCode :: Int -> Int -> String
- saveCursorCode :: String
- restoreCursorCode :: String
- reportCursorPositionCode :: String
- clearFromCursorToScreenEndCode :: String
- clearFromCursorToScreenBeginningCode :: String
- clearScreenCode :: String
- clearFromCursorToLineEndCode :: String
- clearFromCursorToLineBeginningCode :: String
- clearLineCode :: String
- enableLineWrapCode :: String
- disableLineWrapCode :: String
- scrollPageUpCode :: Int -> String
- scrollPageDownCode :: Int -> String
- useAlternateScreenBufferCode :: String
- useNormalScreenBufferCode :: String
- reportLayerColorCode :: ConsoleLayer -> String
- setSGRCode :: [SGR] -> String
- hideCursorCode :: String
- showCursorCode :: String
- hyperlinkCode :: String -> String -> String
- hyperlinkWithIdCode :: String -> String -> String -> String
- hyperlinkWithParamsCode :: [(String, String)] -> String -> String -> String
- setTitleCode :: String -> String
- colorToCode :: Color -> Int
- type Parameter = Int
- type SubParam = Maybe Int
- type ParamWithSubs = (Parameter, [SubParam])
- csi :: [Parameter] -> String -> String
- csi' :: [ParamWithSubs] -> String -> String
- osc :: String -> String -> String
- sgrToCode :: SGR -> [Parameter]
- sgrToCode' :: SGR -> Either ParamWithSubs [Parameter]

# Basic data types

module System.Console.ANSI.Types

# 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 #

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

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

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.

Since: 0.7.1

# Clearing parts of the screen

clearFromCursorToScreenEndCode :: String #

clearFromCursorToScreenBeginningCode :: String #

clearScreenCode :: String #

clearFromCursorToLineEndCode :: String #

clearFromCursorToLineBeginningCode :: String #

clearLineCode :: String #

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

enableLineWrapCode :: String #

disableLineWrapCode :: String #

# 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`.

scrollPageUpCode #

Arguments

:: Int | Number of lines to scroll by
-> String |

scrollPageDownCode #

Arguments

:: Int | Number of lines to scroll by
-> String |

# Using screen buffers

useAlternateScreenBufferCode :: String #

useNormalScreenBufferCode :: String #

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

Since: 0.11.4

# 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).

type Parameter = Int #

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

Since: 1.1

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

Since: 1.1

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.

Since: 1.1

csi #

Arguments

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

csi' #

Arguments

:: [ParamWithSubs] | List of parameters (each of which may be followed by a parameter substring).
-> String | Characters(s) that identify the control function.
-> 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 '`:`'.

Since: 1.1

osc #

Arguments

:: String | Ps parameter
-> String | Pt parameter(s)
-> 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\\"`.

Since: 0.11.4

sgrToCode #

Arguments

:: SGR | The SGR aspect
-> [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.

sgrToCode' #

Arguments

:: SGR | The SGR aspect
-> Either ParamWithSubs [Parameter] |

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

Since: 1.1