| Safe Haskell | Safe |
|---|---|
| Language | Haskell98 |
System.Console.ANSI
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
- Scrolling the screen
- Select Graphic Rendition mode: colors and other whizzy stuff
- Cursor visibilty changes
- Changing the title
- Checking if handle supports ANSI
- Getting the cursor position
Description
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 aHandle. 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 aHandle. 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
Stringtype 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.
- module System.Console.ANSI.Types
- cursorUp :: Int -> IO ()
- cursorDown :: Int -> IO ()
- cursorForward :: Int -> IO ()
- cursorBackward :: Int -> IO ()
- hCursorUp :: Handle -> Int -> IO ()
- hCursorDown :: Handle -> Int -> IO ()
- hCursorForward :: Handle -> Int -> IO ()
- hCursorBackward :: Handle -> Int -> IO ()
- cursorUpCode :: Int -> String
- cursorDownCode :: Int -> String
- cursorForwardCode :: Int -> String
- cursorBackwardCode :: Int -> String
- cursorUpLine :: Int -> IO ()
- cursorDownLine :: Int -> IO ()
- hCursorUpLine :: Handle -> Int -> IO ()
- hCursorDownLine :: Handle -> Int -> IO ()
- cursorUpLineCode :: Int -> String
- cursorDownLineCode :: Int -> String
- setCursorColumn :: Int -> IO ()
- hSetCursorColumn :: Handle -> Int -> IO ()
- setCursorColumnCode :: Int -> String
- setCursorPosition :: Int -> Int -> IO ()
- hSetCursorPosition :: Handle -> Int -> Int -> IO ()
- setCursorPositionCode :: Int -> Int -> String
- saveCursor :: IO ()
- hSaveCursor :: Handle -> IO ()
- saveCursorCode :: String
- restoreCursor :: IO ()
- hRestoreCursor :: Handle -> IO ()
- restoreCursorCode :: String
- reportCursorPosition :: IO ()
- hReportCursorPosition :: Handle -> IO ()
- reportCursorPositionCode :: String
- 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
- scrollPageUp :: Int -> IO ()
- scrollPageDown :: Int -> IO ()
- hScrollPageUp :: Handle -> Int -> IO ()
- hScrollPageDown :: Handle -> Int -> IO ()
- scrollPageUpCode :: Int -> String
- scrollPageDownCode :: Int -> String
- setSGR :: [SGR] -> IO ()
- hSetSGR :: Handle -> [SGR] -> IO ()
- setSGRCode :: [SGR] -> String
- hideCursor :: IO ()
- showCursor :: IO ()
- hHideCursor :: Handle -> IO ()
- hShowCursor :: Handle -> IO ()
- hideCursorCode :: String
- showCursorCode :: String
- setTitle :: String -> IO ()
- hSetTitle :: Handle -> String -> IO ()
- setTitleCode :: String -> String
- hSupportsANSI :: Handle -> IO Bool
- getCursorPosition :: IO (Maybe (Int, Int))
- getReportedCursorPosition :: IO String
- cursorPosition :: ReadP (Int, Int)
Basic data types
module System.Console.ANSI.Types
Cursor movement by character
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.
Directly changing cursor position
Saving, restoring and reporting cursor position
saveCursor :: IO () Source #
Save the cursor position in memory. The only way to access the saved value
is with the restoreCursor command.
hSaveCursor :: Handle -> IO () Source #
restoreCursor :: IO () Source #
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 () Source #
reportCursorPosition :: IO () Source #
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 () Source #
Clearing parts of the screen
Note that these functions only clear parts of the screen. They do not move the cursor.
clearFromCursorToScreenEnd :: IO () Source #
clearScreen :: IO () Source #
hClearFromCursorToScreenEnd :: Handle -> IO () Source #
hClearFromCursorToScreenBeginning :: Handle -> IO () Source #
hClearScreen :: Handle -> IO () Source #
clearFromCursorToLineEnd :: IO () Source #
hClearFromCursorToLineEnd :: Handle -> IO () Source #
hClearFromCursorToLineBeginning :: Handle -> IO () Source #
hClearLine :: Handle -> IO () Source #
Scrolling the screen
Scroll the displayed information up or down the terminal: not widely supported
Scroll the displayed information up or down the terminal: not widely supported
Scroll the displayed information up or down the terminal: not widely supported
Scroll the displayed information up or down the terminal: not widely supported
Select Graphic Rendition mode: colors and other whizzy stuff
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 |
| -> IO () |
Set the Select Graphic Rendition mode
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 |
| -> IO () |
Set the Select Graphic Rendition mode
Cursor visibilty changes
hideCursor :: IO () Source #
showCursor :: IO () Source #
hHideCursor :: Handle -> IO () Source #
hShowCursor :: Handle -> IO () Source #
Changing the title
XTerm control sequence to set the Icon Name and Window Title.
Checking if handle supports ANSI
hSupportsANSI :: Handle -> IO Bool Source #
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)) Source #
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 Source #
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 <- getReportedCursorPositionOn 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) Source #
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"