-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Simple ANSI terminal support, with Windows compatibility
--   
--   ANSI terminal support for Haskell: allows cursor movement, screen
--   clearing, color output, showing or hiding the cursor, and changing the
--   title. Works on UNIX and Windows.
@package ansi-terminal
@version 0.11.5


-- | This module exports functions that return <a>String</a> values
--   containing codes in accordance with the 'ANSI' standards for control
--   character sequences described in the documentation of module
--   <a>System.Console.ANSI</a>.
--   
--   The module <a>System.Console.ANSI</a> exports functions with the same
--   names as those in this module. On some versions of Windows, the
--   terminal in use may not be ANSI-capable. When that is the case, the
--   same-named functions exported by module <a>System.Console.ANSI</a>
--   return "", for the reasons set out in the documentation of that
--   module.
--   
--   Consequently, if module <a>System.Console.ANSI</a> is also imported,
--   this module is intended to be imported qualified, to avoid name
--   clashes with those functions. For example:
--   
--   <pre>
--   import qualified System.Console.ANSI.Codes as ANSI
--   </pre>
module System.Console.ANSI.Codes
cursorUpCode :: Int -> String
cursorDownCode :: Int -> String
cursorForwardCode :: Int -> String
cursorBackwardCode :: Int -> String
cursorUpLineCode :: Int -> String
cursorDownLineCode :: Int -> 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).
setCursorColumnCode :: Int -> 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).
setCursorPositionCode :: Int -> Int -> String

saveCursorCode :: String

restoreCursorCode :: String

-- | Code to emit the cursor position into the console input stream,
--   immediately after being recognised on the output stream, as: <tt>ESC [
--   &lt;cursor row&gt; ; &lt;cursor column&gt; R</tt>
--   
--   Note that the information that is emitted is 1-based (the top-left
--   corner is at row 1 column 1) but <a>setCursorPositionCode</a> is
--   0-based.
--   
--   In isolation of <a>getReportedCursorPosition</a> or
--   <a>getCursorPosition</a>, this function may be of limited use on
--   Windows operating systems because of difficulties in obtaining the
--   data emitted into the console input stream.
reportCursorPositionCode :: String
clearFromCursorToScreenEndCode :: String
clearFromCursorToScreenBeginningCode :: String
clearScreenCode :: String
clearFromCursorToLineEndCode :: String
clearFromCursorToLineBeginningCode :: String
clearLineCode :: String
scrollPageUpCode :: Int -> String
scrollPageDownCode :: Int -> String
useAlternateScreenBufferCode :: String
useNormalScreenBufferCode :: String

-- | Code to emit the layer color into the console input stream,
--   immediately after being recognised on the output stream, as: <tt>ESC ]
--   &lt;Ps&gt; ; rgb: &lt;red&gt; ; &lt;green&gt; ; &lt;blue&gt;
--   &lt;ST&gt;</tt> where <tt>&lt;Ps&gt;</tt> is <tt>10</tt> for
--   <a>Foreground</a> and <tt>11</tt> for <a>Background</a>;
--   <tt>&lt;red&gt;</tt>, <tt>&lt;green&gt;</tt> and <tt>&lt;blue&gt;</tt>
--   are the color channel values in hexadecimal (4, 8, 12 and 16 bit
--   values are possible, although 16 bit values are most common); and
--   <tt>&lt;ST&gt;</tt> is the STRING TERMINATOR (ST). ST depends on the
--   terminal software and may be the <tt>BEL</tt> character or <tt>ESC
--   \</tt> 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 <a>getReportedLayerColor</a>.
reportLayerColorCode :: ConsoleLayer -> String
setSGRCode :: [SGR] -> String
hideCursorCode :: String
showCursorCode :: String

-- | Code to introduce a hyperlink.
hyperlinkCode :: String -> String -> 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.
hyperlinkWithIdCode :: String -> String -> String -> String

-- | Code to introduce a hyperlink with (key, value) parameters. Some
--   terminals support an <tt>id</tt> parameter key, so that hyperlinks
--   with the same <tt>id</tt> value are treated as connected.
hyperlinkWithParamsCode :: [(String, String)] -> String -> String -> 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).
setTitleCode :: String -> String

-- | <a>colorToCode</a> <tt>color</tt> returns the 0-based index of the
--   color (one of the eight colors in the ANSI standard).
colorToCode :: Color -> Int

-- | <a>csi</a> <tt>parameters controlFunction</tt>, where
--   <tt>parameters</tt> is a list of <a>Int</a>, returns the control
--   sequence comprising the control function CONTROL SEQUENCE INTRODUCER
--   (CSI) followed by the parameter(s) (separated by ';') and ending with
--   the <tt>controlFunction</tt> character(s) that identifies the control
--   function.
csi :: [Int] -> String -> String

-- | <a>osc</a> <tt>parameterS parametersT</tt>, where <tt>parameterS</tt>
--   specifies the type of operation to perform and <tt>parametersT</tt> 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) <tt>"\ESC\\"</tt>.
osc :: String -> String -> String

-- | <a>sgrToCode</a> <tt>sgr</tt> returns the parameter of the SELECT
--   GRAPHIC RENDITION (SGR) aspect identified by <tt>sgr</tt>.
sgrToCode :: SGR -> [Int]


-- | <h2>Introduction</h2>
--   
--   Through this module, this library provides platform-independent
--   support for control character sequences following the 'ANSI' standards
--   (see further below) for terminal software that supports those
--   sequences, running on a Unix-like operating system or on Windows (see
--   further below).
--   
--   The sequences of control characters (also referred to as 'escape'
--   sequences or codes) provide a rich range of functionality for terminal
--   control, which includes:
--   
--   <ul>
--   <li>Colored text output, with control over both foreground and
--   background colors</li>
--   <li>Clearing parts of a line or the screen</li>
--   <li>Hiding or showing the cursor</li>
--   <li>Moving the cursor around</li>
--   <li>Reporting the position of the cursor</li>
--   <li>Scrolling the screen up or down</li>
--   <li>Switching between the Alternate and Normal Screen Buffers</li>
--   <li>Clickable hyperlinks to URIs</li>
--   <li>Changing the title of the terminal</li>
--   </ul>
--   
--   A terminal that supports control character sequences acts on them when
--   they are flushed from the output buffer (with a newline character
--   <tt>"\n"</tt> or, for the standard output channel, <tt>hFlush
--   stdout</tt>).
--   
--   <h2>'ANSI' standards</h2>
--   
--   The 'ANSI' standards refer to (1) standard ECMA-48 `Control Functions
--   for Coded Character Sets' (5th edition, 1991); (2) extensions in ITU-T
--   Recommendation (previously CCITT Recommendation) T.416 (03/93)
--   'Information Technology – Open Document Architecture (ODA) and
--   Interchange Format: Character Content Architectures` (also published
--   as ISO/IEC International Standard 8613-6); and (3) further extensions
--   used by 'XTerm', a terminal emulator for the X Window System. The
--   escape codes are described in a Wikipedia article at
--   <a>http://en.wikipedia.org/wiki/ANSI_escape_code</a> and those codes
--   supported on current versions of Windows at
--   <a>https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences</a>.
--   
--   The whole of the 'ANSI' standards are not supported by this library
--   but most (if not all) of the parts that are popular and well-supported
--   by terminal software are supported (see further below).
--   
--   <h2>Cursor positions</h2>
--   
--   The functions moving the cursor to an absolute position are 0-based
--   (the top-left corner is considered to be at row 0 column 0) (see
--   <a>setCursorPosition</a>) and so is <a>getCursorPosition</a>. The
--   'ANSI' standards themselves are 1-based (that is, the top-left corner
--   is considered to be at row 1 column 1) and some functions reporting
--   the position of the cursor are too (see <a>reportCursorPosition</a>).
--   
--   <h2>Windows and control character sequences</h2>
--   
--   The native terminal software on Windows has developed over time.
--   Before Windows 10 version 1511 (known as the 'November [2015] Update'
--   or 'Threshold 2') that software did not support control character
--   sequences. For that software, this library also provides support for
--   such sequences by using emulation based on the Windows Console API.
--   From 2018, Microsoft introduced the Windows Pseudo Console ('ConPTY')
--   API and then Windows Terminal, with the objective of replacing most of
--   the Windows Console API with the use of control character sequences
--   and retiring the historical user-interface role of Windows Console
--   Host ('ConHost').
--   
--   Terminal software other than the native software exists for Windows.
--   One example is the 'mintty' terminal emulator for 'Cygwin', 'MSYS' or
--   'MSYS2', and dervied projects, and for 'WSL' (Windows Subsystem for
--   Linux).
--   
--   GHC's management of input and output (IO) on Windows has also
--   developed over time. If they are supported by the terminal software,
--   some control character sequences cause data to be emitted into the
--   console input stream. For GHC's historical and default IO manager, the
--   function <tt>hGetBufNonBlocking</tt> in module <a>System.IO</a> 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 <a>https://ghc.haskell.org/trac/ghc/ticket/806</a>).
--   GHC's native IO manager on Windows ('WinIO'), introduced as a preview
--   in <a>GHC 9.0.1</a>, has not yet provided a solution. On Windows, this
--   library uses emulation based on the Windows Console API to try to read
--   data emitted into the console input stream. Functions that use that
--   emulation are not supported on consoles, such as mintty, that are not
--   based on that API.
--   
--   <h2>Function variants provided</h2>
--   
--   Every function exported by this module comes in three variants,
--   namely:
--   
--   <ul>
--   <li>A variant that has an <tt>IO ()</tt> type and doesn't take a
--   <tt>Handle</tt> (for example, <tt>clearScreen :: IO ()</tt>). This
--   variant just outputs the `ANSI` command directly to the standard
--   output channel (<tt>stdout</tt>) and any terminal corresponding to it.
--   Commands issued like this should work as you expect on both Unix-like
--   operating systems and Windows (unless exceptions on Windows are
--   stated).</li>
--   <li>An '<tt>h</tt>...' variant that has an <tt>IO ()</tt> type but
--   takes a <tt>Handle</tt> (for example, <tt>hClearScreen :: Handle -&gt;
--   IO ()</tt>). This variant outputs the `ANSI` command to the supplied
--   handle and any terminal corresponding to it. Commands issued like this
--   should also work as you expect on both Unix-like operating systems and
--   Windows (unless exceptions on Windows are stated).</li>
--   <li>A '...<tt>Code</tt>' variant that has a <tt>String</tt> type (for
--   example, <tt>clearScreenCode :: String</tt>). This variant outputs the
--   sequence of control characters as a <a>String</a>, which can be added
--   to any other bit of text before being output. If a high degree of
--   backwards compatability is rewuired, the use of these codes is
--   discouraged because they will not work on legacy versions of Windows
--   where the terminal in use is not ANSI-enabled (see further above). On
--   Windows, where emulation has been necessary, these variants will
--   always output the empty string. That is done so that it is possible to
--   use them portably; for example, coloring console output on the
--   understanding that you will see colors only if you are running on a
--   Unix-like operating system or a version of Windows where emulation has
--   not been necessary. If the control characters are always required, see
--   module <a>System.Console.ANSI.Codes</a>.</li>
--   </ul>
--   
--   <h2>Examples of use</h2>
--   
--   A simple example is below:
--   
--   <pre>
--   module Main where
--   
--   import System.Console.ANSI
--   
--   -- Set colors and write some text in those colors.
--   main :: IO ()
--   main = do
--     setSGR [SetColor Foreground Vivid Red]
--     setSGR [SetColor Background Vivid Blue]
--     putStrLn "Red-On-Blue"
--     setSGR [Reset]  -- Reset to default colour scheme
--     putStrLn "Default colors."
--   </pre>
--   
--   Another example is below:
--   
--   <pre>
--   module Main where
--   
--   import System.IO (hFlush, stdout)
--   import System.Console.ANSI
--   
--   main :: IO ()
--   main = do
--     setSGR [SetColor Foreground Dull Blue]
--     putStr "Enter your name: "
--     setSGR [SetColor Foreground Dull Yellow]
--     hFlush stdout  -- flush the output buffer before getLine
--     name &lt;- getLine
--     setSGR [SetColor Foreground Dull Blue]
--     putStrLn $ "Hello, " ++ name ++ "!"
--     setSGR [Reset]  -- reset to default colour scheme
--   </pre>
--   
--   For many more examples, see the project's extensive <a>Example.hs</a>
--   file.
module System.Console.ANSI
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

-- | Move the cursor to the specified column. The column numbering is
--   0-based (that is, the left-most column is numbered 0).
setCursorColumn :: Int -> IO ()

-- | 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).
setCursorPosition :: Int -> Int -> IO ()
hSetCursorColumn :: Handle -> Int -> IO ()
hSetCursorPosition :: Handle -> Int -> Int -> IO ()

-- | Code to move the cursor to the specified column. The column numbering
--   is 0-based (that is, the left-most column is numbered 0).
setCursorColumnCode :: Int -> 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).
setCursorPositionCode :: Int -> Int -> String

-- | Save the cursor position in memory. The only way to access the saved
--   value is with the <a>restoreCursor</a> command.
saveCursor :: IO ()

-- | Restore the cursor position from memory. There will be no value saved
--   in memory until the first use of the <a>saveCursor</a> command.
restoreCursor :: IO ()

-- | Looking for a way to get the cursors position? See
--   <a>getCursorPosition</a>.
--   
--   Emit the cursor position into the console input stream, immediately
--   after being recognised on the output stream, as: <tt>ESC [ &lt;cursor
--   row&gt; ; &lt;cursor column&gt; R</tt>
--   
--   Note that the information that is emitted is 1-based (the top-left
--   corner is at row 1 column 1) but <a>setCursorColumn</a> and
--   <a>setCursorPosition</a> are 0-based.
--   
--   In isolation of <a>getReportedCursorPosition</a> or
--   <a>getCursorPosition</a>, this function may be of limited use on
--   Windows operating systems because of difficulties in obtaining the
--   data emitted into the console input stream.
reportCursorPosition :: IO ()
hSaveCursor :: Handle -> IO ()
hRestoreCursor :: Handle -> IO ()
hReportCursorPosition :: Handle -> IO ()

saveCursorCode :: String

restoreCursorCode :: String

-- | Code to emit the cursor position into the console input stream,
--   immediately after being recognised on the output stream, as: <tt>ESC [
--   &lt;cursor row&gt; ; &lt;cursor column&gt; R</tt>
--   
--   Note that the information that is emitted is 1-based (the top-left
--   corner is at row 1 column 1) but <a>setCursorPositionCode</a> is
--   0-based.
--   
--   In isolation of <a>getReportedCursorPosition</a> or
--   <a>getCursorPosition</a>, this function may be of limited use on
--   Windows operating systems because of difficulties in obtaining the
--   data emitted into the console input stream.
reportCursorPositionCode :: String
clearFromCursorToScreenEnd :: IO ()
clearFromCursorToScreenBeginning :: IO ()
clearScreen :: IO ()
clearFromCursorToLineEnd :: IO ()
clearFromCursorToLineBeginning :: IO ()
clearLine :: IO ()
hClearFromCursorToScreenEnd :: Handle -> IO ()
hClearFromCursorToScreenBeginning :: Handle -> IO ()
hClearScreen :: Handle -> IO ()
hClearFromCursorToLineEnd :: Handle -> IO ()
hClearFromCursorToLineBeginning :: Handle -> IO ()
hClearLine :: Handle -> IO ()
clearFromCursorToScreenEndCode :: String
clearFromCursorToScreenBeginningCode :: String
clearScreenCode :: String
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

-- | 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
--   <a>bracket_</a>:
--   
--   <pre>
--   bracket_ useAlternateScreenBuffer useNormalScreenBuffer action
--   </pre>
useAlternateScreenBuffer :: IO ()

-- | 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.
useNormalScreenBuffer :: IO ()
hUseAlternateScreenBuffer :: Handle -> IO ()
hUseNormalScreenBuffer :: Handle -> IO ()
useAlternateScreenBufferCode :: String
useNormalScreenBufferCode :: String

-- | Looking for a way to get layer colors? See <a>getLayerColor</a>.
--   
--   Emit the layerColor into the console input stream, immediately after
--   being recognised on the output stream, as: <tt>ESC ] &lt;Ps&gt; ; rgb:
--   &lt;red&gt; ; &lt;green&gt; ; &lt;blue&gt; &lt;ST&gt;</tt> where
--   <tt>&lt;Ps&gt;</tt> is <tt>10</tt> for <a>Foreground</a> and
--   <tt>11</tt> for <a>Background</a>; <tt>&lt;red&gt;</tt>,
--   <tt>&lt;green&gt;</tt> and <tt>&lt;blue&gt;</tt> are the color channel
--   values in hexadecimal (4, 8, 12 and 16 bit values are possible,
--   although 16 bit values are most common); and <tt>&lt;ST&gt;</tt> is
--   the STRING TERMINATOR (ST). ST depends on the terminal software and
--   may be the <tt>BEL</tt> character or <tt>ESC \</tt> 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.
reportLayerColor :: ConsoleLayer -> IO ()
hReportLayerColor :: Handle -> ConsoleLayer -> IO ()

-- | Code to emit the layer color into the console input stream,
--   immediately after being recognised on the output stream, as: <tt>ESC ]
--   &lt;Ps&gt; ; rgb: &lt;red&gt; ; &lt;green&gt; ; &lt;blue&gt;
--   &lt;ST&gt;</tt> where <tt>&lt;Ps&gt;</tt> is <tt>10</tt> for
--   <a>Foreground</a> and <tt>11</tt> for <a>Background</a>;
--   <tt>&lt;red&gt;</tt>, <tt>&lt;green&gt;</tt> and <tt>&lt;blue&gt;</tt>
--   are the color channel values in hexadecimal (4, 8, 12 and 16 bit
--   values are possible, although 16 bit values are most common); and
--   <tt>&lt;ST&gt;</tt> is the STRING TERMINATOR (ST). ST depends on the
--   terminal software and may be the <tt>BEL</tt> character or <tt>ESC
--   \</tt> 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 <a>getReportedLayerColor</a>.
reportLayerColorCode :: ConsoleLayer -> String

-- | Set the Select Graphic Rendition mode
setSGR :: [SGR] -> IO ()
hSetSGR :: Handle -> [SGR] -> IO ()
setSGRCode :: [SGR] -> String
hideCursor :: IO ()
showCursor :: IO ()
hHideCursor :: Handle -> IO ()
hShowCursor :: Handle -> IO ()
hideCursorCode :: String
showCursorCode :: String

-- | Introduce a hyperlink.
hyperlink :: String -> String -> IO ()

-- | 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.
hyperlinkWithId :: String -> String -> String -> IO ()

-- | Introduce a hyperlink with (key, value) parameters. Some terminals
--   support an <tt>id</tt> parameter key, so that hyperlinks with the same
--   <tt>id</tt> value are treated as connected.
hyperlinkWithParams :: [(String, String)] -> String -> String -> IO ()
hHyperlink :: Handle -> String -> String -> IO ()
hHyperlinkWithId :: Handle -> String -> String -> String -> IO ()
hHyperlinkWithParams :: Handle -> [(String, String)] -> String -> String -> IO ()

-- | Code to introduce a hyperlink.
hyperlinkCode :: String -> String -> 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.
hyperlinkWithIdCode :: String -> String -> String -> String

-- | Code to introduce a hyperlink with (key, value) parameters. Some
--   terminals support an <tt>id</tt> parameter key, so that hyperlinks
--   with the same <tt>id</tt> value are treated as connected.
hyperlinkWithParamsCode :: [(String, String)] -> String -> String -> String

-- | Set the terminal window title and icon name (that is, the text for the
--   window in the Start bar, or similar).
setTitle :: String -> IO ()
hSetTitle :: Handle -> String -> IO ()

-- | Code to set the terminal window title and the icon name (that is, the
--   text for the window in the Start bar, or similar).
setTitleCode :: String -> String

-- | Use heuristics to determine whether the functions defined in this
--   package will work with a given handle. This function assumes that the
--   handle is writable (that is, it manages output - see
--   <a>hIsWritable</a>).
--   
--   For Unix-like operating systems, the current implementation checks
--   that: (1) the handle is a terminal; and (2) a <tt>TERM</tt>
--   environment variable is not set to <tt>dumb</tt> (which is what the
--   GNU Emacs text editor sets for its integrated terminal).
--   
--   For Windows, the current implementation performs the same checks as
--   for Unix-like operating systems and, as an alternative, checks whether
--   the handle is connected to a 'mintty' terminal. (That is because the
--   function <a>hIsTerminalDevice</a> 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.) On Windows 10, if
--   the handle is identified as connected to a native terminal, this
--   function does <i>not</i> enable the processing of 'ANSI' control
--   characters in output (see <a>hSupportsANSIWithoutEmulation</a>).
hSupportsANSI :: Handle -> IO Bool

-- | 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.
hSupportsANSIColor :: Handle -> IO Bool

-- | Use heuristics to determine whether a given handle will support 'ANSI'
--   control characters in output. (On Windows versions before Windows 10,
--   that means 'support without emulation'.)
--   
--   If the handle is not writable (that is, it cannot manage output - see
--   <a>hIsWritable</a>), then <tt>pure (Just False)</tt> is returned.
--   
--   On Unix-like operating systems, with one exception, the function is
--   consistent with <a>hSupportsANSI</a>. The exception is if the handle
--   is not writable.
--   
--   On Windows, what is returned will depend on what the handle is
--   connected to and the version of the operating system. If the handle is
--   identified as connected to a 'mintty' terminal, <tt>pure (Just
--   True)</tt> is returned. If it is identified as connected to a native
--   terminal, then, on Windows 10, the processing of 'ANSI' control
--   characters will be enabled and <tt>pure (Just True)</tt> returned;
--   and, on versions of Windows before Windows 10, <tt>pure (Just
--   False)</tt> is returned. Otherwise, if a <tt>TERM</tt> environment
--   variable is set to <tt>dumb</tt>, <tt>pure (Just False)</tt> is
--   returned. In all other cases of a writable handle, <tt>pure
--   Nothing</tt> is returned; this indicates that the heuristics cannot
--   assist - the handle may be connected to a file or to another type of
--   terminal.
hSupportsANSIWithoutEmulation :: Handle -> IO (Maybe Bool)

-- | Attempts to get the reported cursor position, combining the functions
--   <a>reportCursorPosition</a>, <a>getReportedCursorPosition</a> and
--   <a>cursorPosition</a>. Any position <tt>(row, column)</tt> is
--   translated to be 0-based (that is, the top-left corner is at <tt>(0,
--   0)</tt>), consistent with <a>setCursorColumn</a> and
--   <a>setCursorPosition</a>. (Note that the information emitted into the
--   console input stream by <a>reportCursorPosition</a> is 1-based.)
--   Returns <a>Nothing</a> if any data emitted by
--   <a>reportCursorPosition</a>, obtained by
--   <a>getReportedCursorPosition</a>, cannot be parsed by
--   <a>cursorPosition</a>. Uses <a>stdout</a>. If <a>stdout</a> will be
--   redirected, see <a>hGetCursorPosition</a> 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.)
getCursorPosition :: IO (Maybe (Int, Int))

-- | Attempts to get the reported cursor position, combining the functions
--   <a>hReportCursorPosition</a> (with the specified handle),
--   <a>getReportedCursorPosition</a> and <a>cursorPosition</a>. Any
--   position <tt>(row, column)</tt> is translated to be 0-based (that is,
--   the top-left corner is at <tt>(0, 0)</tt>), consistent with
--   <a>hSetCursorColumn</a> and <a>hSetCursorPosition</a>. (Note that the
--   information emitted into the console input stream by
--   <a>hReportCursorPosition</a> is 1-based.) Returns <a>Nothing</a> if
--   any data emitted by <a>hReportCursorPosition</a>, obtained by
--   <a>getReportedCursorPosition</a>, cannot be parsed by
--   <a>cursorPosition</a>.
--   
--   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.)
hGetCursorPosition :: Handle -> IO (Maybe (Int, Int))

-- | Attempts to get the reported cursor position data from the console
--   input stream. The function is intended to be called immediately after
--   <a>reportCursorPosition</a> (or related functions) have caused
--   characters to be emitted into the stream.
--   
--   For example, on a Unix-like operating system:
--   
--   <pre>
--   -- 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 &lt;- bracket (hGetEcho stdin) (hSetEcho stdin) $ \_ -&gt; do
--     hSetEcho stdin False
--     reportCursorPosition
--     hFlush stdout -- ensure the report cursor position code is sent to the
--                   -- operating system
--     getReportedCursorPosition
--   </pre>
--   
--   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.)
getReportedCursorPosition :: IO String

-- | Parses the characters emitted by <a>reportCursorPosition</a> into the
--   console input stream. Returns the cursor row and column as a tuple.
--   
--   For example, if the characters emitted by <a>reportCursorPosition</a>
--   are in <a>String</a> <tt>input</tt> then the parser could be applied
--   like this:
--   
--   <pre>
--   let result = readP_to_S cursorPosition input
--   case result of
--       [] -&gt; putStrLn $ "Error: could not parse " ++ show input
--       [((row, column), _)] -&gt; putStrLn $ "The cursor was at row " ++ show row
--           ++ " and column" ++ show column ++ "."
--       (_:_) -&gt; putStrLn $ "Error: parse not unique"
--   </pre>
cursorPosition :: ReadP (Int, Int)

-- | 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
--   <a>getCursorPosition</a> to query the console input stream. It works
--   only on terminals that support each step and if data can be emitted to
--   <a>stdin</a>. (Use <a>hIsTerminalDevice</a> to test if <a>stdin</a> is
--   connected to a terminal.) Uses <a>stdout</a>. If <a>stdout</a> will be
--   redirected, see <a>hGetTerminalSize</a> 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 <a>stdin</a> is redirected, see the
--   <a>terminal-size</a> package.
getTerminalSize :: IO (Maybe (Int, Int))

-- | 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 <a>stdout</a> or <tt>stderr</tt>).
--   
--   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
--   <a>hGetCursorPosition</a> to query the console input stream. It works
--   only on terminals that support each step and if data can be emitted to
--   <a>stdin</a>. (Use <a>hIsTerminalDevice</a> to test if <a>stdin</a> 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 <a>stdin</a> is redirected, see the
--   <a>terminal-size</a> package.
hGetTerminalSize :: Handle -> IO (Maybe (Int, Int))

-- | Attempts to get the reported layer color, combining the functions
--   <a>reportLayerColor</a>, <a>getReportedLayerColor</a> and
--   <a>layerColor</a>. Any RGB color is scaled to be 16 bits per channel,
--   the most common format reported by terminal software. Returns
--   <a>Nothing</a> if any data emitted by <a>reportLayerColor</a>,
--   obtained by <a>getReportedLayerColor</a>, cannot be parsed by
--   <a>layerColor</a>. Uses <a>stdout</a>. If <a>stdout</a> will be
--   redirected, see <a>hGetLayerColor</a> 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.
getLayerColor :: ConsoleLayer -> IO (Maybe (RGB Word16))

-- | Attempts to get the reported layer color, combining the functions
--   <a>hReportLayerColor</a>, <a>getReportedLayerColor</a> and
--   <a>layerColor</a>. Any RGB color is scaled to be 16 bits per channel,
--   the most common format reported by terminal software. Returns
--   <a>Nothing</a> if any data emitted by <a>hReportLayerColor</a>,
--   obtained by <a>getReportedLayerColor</a>, cannot be parsed by
--   <a>layerColor</a>.
--   
--   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.
hGetLayerColor :: Handle -> ConsoleLayer -> IO (Maybe (RGB Word16))

-- | Attempts to get the reported layer color data from the console input
--   stream. The function is intended to be called immediately after
--   <a>reportLayerColor</a> (or related functions) have caused characters
--   to be emitted into the stream.
--   
--   For example, on a Unix-like operating system:
--   
--   <pre>
--   -- 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 &lt;- bracket (hGetEcho stdin) (hSetEcho stdin) $ \_ -&gt; do
--     hSetEcho stdin False
--     reportLayerColor Foreground
--     hFlush stdout -- ensure the report cursor position code is sent to the
--                   -- operating system
--     getReportedLayerColor Foreground
--   </pre>
--   
--   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.)
getReportedLayerColor :: ConsoleLayer -> IO String

-- | Parses the characters emitted by <a>reportLayerColor</a> into the
--   console input stream.
--   
--   For example, if the characters emitted by <a>reportLayerColor</a> are
--   in <a>String</a> <tt>input</tt> then the parser could be applied like
--   this:
--   
--   <pre>
--   let result = readP_to_S (layerColor layer) input
--   case result of
--       [] -&gt; putStrLn $ "Error: could not parse " ++ show input
--       [(col, _)] -&gt; putStrLn $ "The color was " ++ show col ++ "."
--       (_:_) -&gt; putStrLn $ "Error: parse not unique"
--   </pre>
layerColor :: ConsoleLayer -> ReadP (RGB Word16)
