System.Console.ANSI

Provides ANSI terminal support for ANSI terminal software running on a Unix-like operating system or on a Windows operating system (where supported) or on other Windows operating systems where the terminal in use is not ANSI-enabled.

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 you 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. The use of these codes is generally discouraged because they will not work on Windows operating systems where the terminal in use is not ANSI-enabled (such as those before Windows 10 Threshold 2). On versions of Windows where the terminal in use is not ANSI-enabled, 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 an operating system that is Unix-like or is a version of Windows where the terminal in use is ANSI- enabled.

Example:

-- Set colors and write some text in those colors.
sgrExample :: IO ()
sgrExample = do
    setSGR [SetColor Foreground Vivid Red]
    setSGR [SetColor Background Vivid Blue]
    putStr "Red-On-Blue"
    setSGR [Reset]
    putStr "White-On-Black"

For many more examples, see the project's extensive Example.hs file.

Basic data types

module System.Console.ANSI.Types

Cursor movement by character

cursorUp

Arguments

:: Int

Number of lines or characters to move

-> IO ()

cursorDown

Arguments

:: Int

Number of lines or characters to move

-> IO ()

cursorForward

Arguments

:: Int

Number of lines or characters to move

-> IO ()

cursorBackward

Arguments

:: Int

Number of lines or characters to move

-> IO ()

hCursorUp

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

hCursorDown

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

hCursorForward

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

hCursorBackward

Arguments

:: Handle

-> Int

Number of lines or characters to move

-> IO ()

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

The difference between movements "by character" and "by line" is that *Line functions additionally move the cursor to the start of the line, while functions like cursorUp and cursorDown keep the column the same.

Also keep in mind that *Line functions are not as portable. See https://github.com/feuerbach/ansi-terminal/issues/10 for the details.

cursorUpLine

Arguments

:: Int

Number of lines to move

-> IO ()

cursorDownLine

Arguments

:: Int

Number of lines to move

-> IO ()

hCursorUpLine

Arguments

:: Handle

-> Int

Number of lines to move

-> IO ()

hCursorDownLine

Arguments

:: Handle

-> Int

Number of lines to move

-> IO ()

cursorUpLineCode

Arguments

:: Int

Number of lines to move

-> String

cursorDownLineCode

Arguments

:: Int

Number of lines to move

-> String

Directly changing cursor position

setCursorColumn

Arguments

:: Int

0-based column to move to

-> IO ()

hSetCursorColumn

Arguments

:: Handle

-> Int

0-based column to move to

-> IO ()

setCursorColumnCode

Arguments

:: Int

0-based column to move to

-> String

setCursorPosition

Arguments

:: Int

0-based row to move to

-> Int

0-based column to move to

-> IO ()

hSetCursorPosition

Arguments

:: Handle

-> Int

0-based row to move to

-> Int

0-based column to move to

-> IO ()

setCursorPositionCode

Arguments

:: Int

0-based row to move to

-> Int

0-based column to move to

-> String

Saving, restoring and reporting cursor position

saveCursor :: IO ()

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

hSaveCursor :: Handle -> IO ()

saveCursorCode :: String

restoreCursor :: IO ()

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

hRestoreCursor :: Handle -> IO ()

restoreCursorCode :: String

reportCursorPosition :: IO ()

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

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

hReportCursorPosition :: Handle -> IO ()

reportCursorPositionCode :: String

Clearing parts of the screen

Note that these functions only clear parts of the screen. They do not move the cursor.

clearFromCursorToScreenEnd :: IO ()

clearFromCursorToScreenBeginning :: IO ()

clearScreen :: IO ()

hClearFromCursorToScreenEnd :: Handle -> IO ()

hClearFromCursorToScreenBeginning :: Handle -> IO ()

hClearScreen :: Handle -> IO ()

clearFromCursorToScreenEndCode :: String

clearFromCursorToScreenBeginningCode :: String

clearScreenCode :: String

clearFromCursorToLineEnd :: IO ()

clearFromCursorToLineBeginning :: IO ()

clearLine :: IO ()

hClearFromCursorToLineEnd :: Handle -> IO ()

hClearFromCursorToLineBeginning :: Handle -> IO ()

hClearLine :: Handle -> IO ()

clearFromCursorToLineEndCode :: String

clearFromCursorToLineBeginningCode :: String

clearLineCode :: String

Scrolling the screen

scrollPageUp

Arguments

:: Int

Number of lines to scroll by

-> IO ()

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

scrollPageDown

Arguments

:: Int

Number of lines to scroll by

-> IO ()

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

hScrollPageUp

Arguments

:: Handle

-> Int

Number of lines to scroll by

-> IO ()

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

hScrollPageDown

Arguments

:: Handle

-> Int

Number of lines to scroll by

-> IO ()

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

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

setSGR

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

hSetSGR

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

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

hideCursor :: IO ()

showCursor :: IO ()

hHideCursor :: Handle -> IO ()

hShowCursor :: Handle -> IO ()

hideCursorCode :: String

showCursorCode :: String

Changing the title

setTitle

Arguments

:: String

New title

-> IO ()

Set the terminal window title

hSetTitle

Arguments

:: Handle

-> String

New title

-> IO ()

Set the terminal window title

setTitleCode

Arguments

:: String

New Icon Name and Window Title

-> String

XTerm control sequence to set the Icon Name and Window Title.

Checking if handle supports ANSI

hSupportsANSI :: Handle -> IO Bool

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

The current implementation checks that the handle is a terminal, and that the TERM environment variable doesn't say dumb (which is what Emacs sets for its own terminal).

Getting the cursor position

getCursorPosition :: IO (Maybe (Int, Int))

Attempts to get the reported cursor position, combining the functions reportCursorPosition, getReportedCursorPosition and cursorPosition. Returns Nothing if any data emitted by reportCursorPosition, 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 Win32 console of the Windows API. (Command Prompt and PowerShell are based on the Win32 console.)

getReportedCursorPosition :: IO String

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:

hSetBuffering stdin NoBuffering -- set no buffering (the contents of the
                                -- buffer will be discarded, so this needs
                                -- to be done before the cursor positon is
                                -- emitted)
reportCursorPosition
hFlush stdout -- ensure the report cursor position code is sent to the
              -- operating system
input <- getReportedCursorPosition

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

cursorPosition :: ReadP (Int, Int)

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"