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

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

Save the cursor position in memory. The only way to access the saved value is with the restoreCursor command.

Since: 0.7.1

Restore the cursor position from memory. There will be no value saved in memory until the first use of the saveCursor command.

Since: 0.7.1

Looking for a way to get the cursors position? See getCursorPosition.

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 setCursorColumn and setCursorPosition are 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

Use the Alternate Screen Buffer. If currently using the Normal Screen Buffer, it will save the cursor position and switch to the Alternate Screen Buffer. It will always clear the Alternate Screen Buffer. The Alternate Screen Buffer has no scroll back facility.

It is an application's responsibility to ensure that it switches back to the Normal Screen Buffer if an exception is raised while the Alternate Screen Buffer is being used. For example, by using bracket_:

bracket_ useAlternateScreenBuffer useNormalScreenBuffer action

Since: 0.11.4

Use the Normal Screen Buffer. If currently using the Alternate Screen Buffer, it will clear the Alternate Screen Buffer, and switch to the Normal Screen Buffer. It will always restore the saved cursor position.

Since: 0.11.4

Looking for a way to get layer colors? See getLayerColor.

Emit the layerColor 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 function is not supported on native terminals and is emulated, but the emulation does not work on Windows Terminal and (2) of difficulties in obtaining the data emitted into the console input stream.

Underlining is not supported.

Since: 0.11.4

Set the Select Graphic Rendition mode

Introduce a hyperlink.

Since: 0.11.3

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

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

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

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

If the handle is not writable (that is, it cannot manage output - see hIsWritable), then pure False is returned.

For Unix-like operating systems, the current implementation checks that: (1) the handle is a terminal; and (2) a TERM environment variable is not set to dumb (which is what the GNU Emacs text editor sets for its integrated terminal).

For Windows, the current implementation checks: first that (1) the handle is a terminal, (2) a TERM environment variable is not set to dumb, and (3) the processing of 'ANSI' control characters in output is enabled; and second, as an alternative, whether the handle is connected to a 'mintty' terminal. (That is because the function hIsTerminalDevice is used to check if the handle is a terminal. However, where a non-native Windows terminal (such as 'mintty') is implemented using redirection, that function will not identify a handle to the terminal as a terminal.) If it is not already enabled, this function does *not* enable the processing of 'ANSI' control characters in output (see hNowSupportsANSI).

Since: 0.6.2

With one exception, equivalent to hSupportsANSI. The exception is that, on Windows only, if a TERM environment variable is not set to dumb and the processing of 'ANSI' control characters in output is not enabled, this function first tries to enable such processing.

@Since 1.0.1

Some terminals (e.g. Emacs) are not fully ANSI compliant but can support ANSI colors. This can be used in such cases, if colors are all that is needed.

Since: 0.9

Attempts to get the reported cursor position, combining the functions reportCursorPosition, getReportedCursorPosition and cursorPosition. Any position (row, column) is translated to be 0-based (that is, the top-left corner is at (0, 0)), consistent with setCursorColumn and setCursorPosition. (Note that the information emitted into the console input stream by reportCursorPosition is 1-based.) Returns Nothing if any data emitted by reportCursorPosition, obtained by getReportedCursorPosition, cannot be parsed by cursorPosition. Uses stdout. If stdout will be redirected, see hGetCursorPosition for a more general function.

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on the Windows' Console API. (Command Prompt and PowerShell are based on the Console API.)

Since: 0.10.3

Attempts to get the reported cursor position, combining the functions hReportCursorPosition (with the specified handle), getReportedCursorPosition and cursorPosition. Any position (row, column) is translated to be 0-based (that is, the top-left corner is at (0, 0)), consistent with hSetCursorColumn and hSetCursorPosition. (Note that the information emitted into the console input stream by hReportCursorPosition is 1-based.) Returns Nothing if any data emitted by hReportCursorPosition, obtained by getReportedCursorPosition, cannot be parsed by cursorPosition.

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on the Windows' Console API. (Command Prompt and PowerShell are based on the Console API.)

Since: 0.10.1

Attempts to get the reported cursor position data from the console input stream. The function is intended to be called immediately after reportCursorPosition (or related functions) have caused characters to be emitted into the stream.

For example, on a Unix-like operating system:

-- set no buffering (if 'no buffering' is not already set, the contents of
-- the buffer will be discarded, so this needs to be done before the cursor
-- positon is emitted)
hSetBuffering stdin NoBuffering
-- ensure that echoing is off
input <- bracket (hGetEcho stdin) (hSetEcho stdin) $ \_ -> do
  hSetEcho stdin False
  reportCursorPosition
  hFlush stdout -- ensure the report cursor position code is sent to the
                -- operating system
  getReportedCursorPosition

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on the Windows' Console API. (Command Prompt and PowerShell are based on the Console API.)

Since: 0.7.1

Parses the characters emitted by reportCursorPosition into the console input stream. Returns the cursor row and column as a tuple.

For example, if the characters emitted by reportCursorPosition are in String input then the parser could be applied like this:

let result = readP_to_S cursorPosition input
case result of
    [] -> putStrLn $ "Error: could not parse " ++ show input
    [((row, column), _)] -> putStrLn $ "The cursor was at row " ++ show row
        ++ " and column" ++ show column ++ "."
    (_:_) -> putStrLn $ "Error: parse not unique"

Since: 0.7.1

Attempts to get the current terminal size (height in rows, width in columns).

There is no 'ANSI' control character sequence that reports the terminal size. So, it attempts to set the cursor position beyond the bottom right corner of the terminal and then use getCursorPosition to query the console input stream. It works only on terminals that support each step and if data can be emitted to stdin. (Use hIsTerminalDevice to test if stdin is connected to a terminal.) Uses stdout. If stdout will be redirected, see hGetTerminalSize for a more general function.

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on Windows' Console API. (Command Prompt and PowerShell are based on the Console API.)

For a different approach, one that does not use control character sequences and works when stdin is redirected, see the terminal-size package.

Since: 0.9

Attempts to get the current terminal size (height in rows, width in columns), by writing control character sequences to the specified handle (which will typically be stdout or stderr).

There is no 'ANSI' control character sequence that reports the terminal size. So, it attempts to set the cursor position beyond the bottom right corner of the terminal and then use hGetCursorPosition to query the console input stream. It works only on terminals that support each step and if data can be emitted to stdin. (Use hIsTerminalDevice to test if stdin is connected to a terminal.)

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on the Windows' Console API. (Command Prompt and PowerShell are based on the Console API.)

For a different approach, one that does not use control character sequences and works when stdin is redirected, see the terminal-size package.

Since: 0.10.1

Attempts to get the reported layer color, combining the functions reportLayerColor, getReportedLayerColor and layerColor. Any RGB color is scaled to be 16 bits per channel, the most common format reported by terminal software. Returns Nothing if any data emitted by reportLayerColor, obtained by getReportedLayerColor, cannot be parsed by layerColor. Uses stdout. If stdout will be redirected, see hGetLayerColor for a more general function.

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on the Windows' Console API. (Command Prompt and PowerShell are based on the Console API.) This function also relies on emulation that does not work on Windows Terminal.

Underlining is not supported.

Since: 0.11.4

Attempts to get the reported layer color, combining the functions hReportLayerColor, getReportedLayerColor and layerColor. Any RGB color is scaled to be 16 bits per channel, the most common format reported by terminal software. Returns Nothing if any data emitted by hReportLayerColor, obtained by getReportedLayerColor, cannot be parsed by layerColor.

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on the Windows' Console API. (Command Prompt and PowerShell are based on the Console API.) This function also relies on emulation that does not work on Windows Terminal.

Underlining is not supported.

Since: 0.11.4

Attempts to get the reported layer color data from the console input stream. The function is intended to be called immediately after reportLayerColor (or related functions) have caused characters to be emitted into the stream.

For example, on a Unix-like operating system:

-- set no buffering (if 'no buffering' is not already set, the contents of
-- the buffer will be discarded, so this needs to be done before the cursor
-- positon is emitted)
hSetBuffering stdin NoBuffering
-- ensure that echoing is off
input <- bracket (hGetEcho stdin) (hSetEcho stdin) $ \_ -> do
  hSetEcho stdin False
  reportLayerColor Foreground
  hFlush stdout -- ensure the report cursor position code is sent to the
                -- operating system
  getReportedLayerColor Foreground

On Windows operating systems, the function is not supported on consoles, such as mintty, that are not based on the Windows' Console API. (Command Prompt and PowerShell are based on the Console API.)

Underlining is not supported.

Since: 0.11.4

Parses the characters emitted by reportLayerColor into the console input stream.

For example, if the characters emitted by reportLayerColor are in String input then the parser could be applied like this:

let result = readP_to_S (layerColor layer) input
case result of
    [] -> putStrLn $ "Error: could not parse " ++ show input
    [(col, _)] -> putStrLn $ "The color was " ++ show col ++ "."
    (_:_) -> putStrLn $ "Error: parse not unique"

Underlining is not supported.

Since: 0.11.4

Use heuristics to determine whether a given handle will support 'ANSI' control characters in output. The function is consistent with hNowSupportsANSI.

This function is deprecated as, from version 1.0, the package no longer supports legacy versions of Windows that required emulation.

Since: 0.8.1