Safe Haskell | Safe |
---|---|
Language | Haskell98 |
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
String
type and just consists of an escape code which can be added to any other bit of text before being output. This version of the API is often convenient to use, but 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
- 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
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
Clearing parts of the screen
Note that these functions only clear parts of the screen. They do not move the cursor.
clearFromCursorToScreenEnd :: IO () #
clearScreen :: IO () #
hClearFromCursorToScreenEnd :: Handle -> IO () #
hClearFromCursorToScreenBeginning :: Handle -> IO () #
hClearScreen :: Handle -> IO () #
clearFromCursorToLineEnd :: IO () #
hClearFromCursorToLineEnd :: Handle -> IO () #
hClearFromCursorToLineBeginning :: Handle -> IO () #
hClearLine :: Handle -> IO () #
clearLineCode :: String #
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
Scroll the displayed information up or down the terminal: not widely supported
Select Graphic Rendition mode: colors and other whizzy stuff
:: [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
Set the Select Graphic Rendition mode
:: 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 () #
showCursor :: IO () #
hHideCursor :: Handle -> IO () #
hShowCursor :: Handle -> IO () #
Changing the title
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).