Re #178 Better document current behaviour of functions reading stdin

Author: mpilgrem

ansi-terminal/src/System/Console/ANSI.hs

@@ -742,6 +742,8 @@ getReportedCursorPosition = Internal.getReportedCursorPosition
 -- as mintty, that are not based on the Windows' Console API. (Command Prompt
 -- and PowerShell are based on the Console API.)
 --
+-- This operation may fail with an error if 'stdin' has been redirected.
+--
 -- @since 0.10.3
 getCursorPosition :: IO (Maybe (Int, Int))
 getCursorPosition = hGetCursorPosition stdout
@@ -760,6 +762,8 @@ getCursorPosition = hGetCursorPosition stdout
 -- as mintty, that are not based on the Windows' Console API. (Command Prompt
 -- and PowerShell are based on the Console API.)
 --
+-- This operation may fail with an error if 'stdin' has been redirected.
+--
 -- @since 0.10.1
 hGetCursorPosition :: Handle -> IO (Maybe (Int, Int))
 hGetCursorPosition h = fmap to0base <$> getCursorPosition'
@@ -864,6 +868,8 @@ getReportedLayerColor = Internal.getReportedLayerColor
 --
 -- Underlining is not supported.
 --
+-- This operation may fail with an error if 'stdin' has been redirected.
+--
 -- @since 0.11.4
 getLayerColor :: ConsoleLayer -> IO (Maybe(RGB Word16))
 getLayerColor = hGetLayerColor stdout
@@ -882,6 +888,8 @@ getLayerColor = hGetLayerColor stdout
 --
 -- Underlining is not supported.
 --
+-- This operation may fail with an error if 'stdin' has been redirected.
+--
 -- @since 0.11.4
 hGetLayerColor :: Handle -> ConsoleLayer -> IO (Maybe (RGB Word16))
 hGetLayerColor h layer = do
@@ -976,6 +984,8 @@ layerColor layer = do
 -- as mintty, that are not based on Windows' Console API. (Command Prompt and
 -- PowerShell are based on the Console API.)
 --
+-- This operation may fail with an error if 'stdin' has been redirected.
+--
 -- For a different approach, one that does not use control character sequences
 -- and works when 'stdin' is redirected, see the
 -- <https://hackage.haskell.org/package/terminal-size terminal-size> package.
@@ -999,6 +1009,8 @@ getTerminalSize = hGetTerminalSize stdout
 -- as mintty, that are not based on the Windows' Console API. (Command Prompt
 -- and PowerShell are based on the Console API.)
 --
+-- This operation may fail with an error if 'stdin' has been redirected.
+--
 -- For a different approach, one that does not use control character sequences
 -- and works when 'stdin' is redirected, see the
 -- <https://hackage.haskell.org/package/terminal-size terminal-size> package.

ansi-terminal/unix/System/Console/ANSI/Internal.hs

@@ -92,7 +92,7 @@ hSupportsANSIColor h = (|| isEmacsTerm) <$> hSupportsANSI h
 -- This approach is taken because the use of C function setenv() in one thread
 -- can cause other threads calling C function getenv() to crash. On Unix-like
 -- operating systems, System.Environment.lookupEnv is implemented using C
--- function getenv(). 
+-- function getenv().
 isNotDumb :: Bool
 isNotDumb = unsafePerformIO (lookupEnv "TERM") /= Just "dumb"
 
@@ -102,7 +102,7 @@ isNotDumb = unsafePerformIO (lookupEnv "TERM") /= Just "dumb"
 -- INSIDE_EMACS environment variable exists, that will not change. This approach
 -- is taken because the use of C function setenv() in one thread can cause other
 -- threads calling C function getenv() to crash. On Unix-like operating systems,
--- System.Environment.lookupEnv is implemented using C function getenv(). 
+-- System.Environment.lookupEnv is implemented using C function getenv().
 insideEmacs :: Bool
 insideEmacs = isJust $ unsafePerformIO (lookupEnv "INSIDE_EMACS")