ansi-terminal 0.8.1 → 0.8.2

raw patch · 9 files changed

+91/−10 lines, 9 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• CHANGELOG.md +9/−0
• ansi-terminal.cabal +1/−1
• app/Example.hs +2/−2
• src/System/Console/ANSI.hs +7/−0
• src/System/Console/ANSI/Codes.hs +25/−1
• src/System/Console/ANSI/Unix.hs +1/−0
• src/System/Console/ANSI/Windows.hs +1/−0
• src/includes/Common-Include.hs +41/−5
• src/includes/Exports-Include.hs +4/−1

@@ -1,6 +1,15 @@ Changes
 =======
 
+Version 0.8.2
+-------------
+
+* Add `getCursorPosition0` and deprecate `getCursorPosition`. Any position
+  provided by the latter is 1-based. Any position provided by the former is
+  0-based, consistent with `setCursorColumn` and `setCursorPosition`.
+* Improvements to Haddock documentation in respect of 0-based and 1-based
+  cursor positions.
+
 Version 0.8.1
 -------------
 

@@ -1,5 +1,5 @@ Name:                ansi-terminal
-Version:             0.8.1
+Version:             0.8.2
 Cabal-Version:       >= 1.8
 Category:            User Interfaces
 Synopsis:            Simple ANSI terminal support, with Windows compatibility

@@ -301,11 +301,11 @@   --          11111111112222222222
   -- 12345678901234567890123456789
   -- Report cursor position here:|
-  result <- getCursorPosition
+  result <- getCursorPosition0
   putStrLn " (3rd row, 29th column) to stdin, as CSI 3 ; 29 R.\n"
   case result of
     Just (row, col) -> putStrLn $ "The cursor was at row number " ++
-      show row ++ " and column number " ++ show col ++ ".\n"
+      show (row + 1) ++ " and column number " ++ show (col + 1) ++ ".\n"
     Nothing -> putStrLn "Error: unable to get the cursor position\n"
   pause
   --          11111111112222222222

@@ -22,6 +22,13 @@ --
 --  * Changing the title of the terminal
 --
+-- 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
+-- 'setCursorPosition') and so is 'getCursorPosition0'. 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 'reportCursorPosition').
+--
 -- The native terminal software on Windows is \'Command Prompt\' or
 -- \`PowerShell\`. Before Windows 10 version 1511 (known as the \'November
 -- [2015] Update\' or \'Threshold 2\') that software did not support such

@@ -134,18 +134,42 @@ cursorDownLineCode n = csi [n] "E"
 cursorUpLineCode n = csi [n] "F"
 
+-- | 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 -- ^ 0-based column to move to
                     -> String
 setCursorColumnCode n = csi [n + 1] "G"
 
+-- | 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 -- ^ 0-based row to move to
                       -> Int -- ^ 0-based column to move to
                       -> String
 setCursorPositionCode n m = csi [n + 1, m + 1] "H"
 
-saveCursorCode, restoreCursorCode, reportCursorPositionCode :: String
+-- | @since 0.7.1
+saveCursorCode, restoreCursorCode :: String
 saveCursorCode = "\ESC7"
 restoreCursorCode = "\ESC8"
+
+-- | Code to emit the cursor position into the console input stream, immediately
+-- after being recognised on the output stream, as:
+-- @ESC [ \<cursor row> ; \<cursor column> R@
+--
+-- Note that the information that is emitted is 1-based (the top-left corner is
+-- at row 1 column 1) but 'setCursorPositionCode' is 0-based.
+--
+-- In isolation of 'getReportedCursorPosition' or 'getCursorPosition0', 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>).
+--
+-- @since 0.7.1
+reportCursorPositionCode :: String
+
 reportCursorPositionCode = csi [] "6n"
 
 clearFromCursorToScreenEndCode, clearFromCursorToScreenBeginningCode,

@@ -101,6 +101,7 @@ 
 -- getCursorPosition :: IO (Maybe (Int, Int))
 -- (See Common-Include.hs for Haddock documentation)
+{-# DEPRECATED getCursorPosition "Use getCursorPosition0 instead." #-}
 getCursorPosition = do
   input <- bracket (hGetBuffering stdin) (hSetBuffering stdin) $ \_ -> do
     hSetBuffering stdin NoBuffering -- set no buffering (the contents of the

@@ -192,4 +192,5 @@ 
 -- getCursorPosition :: IO (Maybe (Int, Int))
 -- (See Common-Include.hs for Haddock documentation)
+{-# DEPRECATED getCursorPosition "Use getCursorPosition0 instead." #-}
 getCursorPosition = E.getCursorPosition

@@ -35,6 +35,9 @@ hSetCursorColumn :: Handle
                  -> Int -- ^ 0-based column to move to
                  -> IO ()
+
+-- | Move the cursor to the specified column. The column numbering is 0-based
+-- (that is, the left-most column is numbered 0).
 setCursorColumn :: Int -- ^ 0-based column to move to
                 -> IO ()
 setCursorColumn = hSetCursorColumn stdout
@@ -43,6 +46,9 @@                    -> Int -- ^ 0-based row to move to
                    -> Int -- ^ 0-based column to move to
                    -> 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 -- ^ 0-based row to move to
                   -> Int -- ^ 0-based column to move to
                   -> IO ()
@@ -52,24 +58,36 @@ 
 -- | Save the cursor position in memory. The only way to access the saved value
 -- is with the 'restoreCursor' command.
+--
+-- @since 0.7.1
 saveCursor :: IO ()
+
 -- | Restore the cursor position from memory. There will be no value saved in
 -- memory until the first use of the 'saveCursor' command.
+--
+-- @since 0.7.1
 restoreCursor :: IO ()
+
 -- | Looking for a way to get the cursors position? See
--- 'getCursorPosition'.
+-- 'getCursorPosition0'.
 --
 -- 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
+-- Note that the information that is emitted is 1-based (the top-left corner is
+-- at row 1 column 1) but 'setCursorColumn' and 'setCursorPosition' are
+-- 0-based.
+--
+-- In isolation of 'getReportedCursorPosition' or 'getCursorPosition0', 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>).
+--
+-- @since 0.7.1
 reportCursorPosition :: IO ()
 
 saveCursor = hSaveCursor stdout
@@ -151,6 +169,7 @@ -- >         ++ " and column" ++ show column ++ "."
 -- >     (_:_) -> putStrLn $ "Error: parse not unique"
 --
+-- @since 0.7.1
 cursorPosition :: ReadP (Int, Int)
 cursorPosition = do
   void $ char '\ESC'
@@ -183,14 +202,31 @@ -- 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.)
+--
+-- @since 0.7.1
 getReportedCursorPosition :: IO String
 
 -- | 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'.
+-- 'reportCursorPosition', 'getReportedCursorPosition' and 'cursorPosition'. Any
+-- position @(row, column)@ is translated to be 0-based (that is, the top-left
+-- corner is at @(0, 0)@), consistent with `setCursorColumn` and
+-- `setCursorPosition`. (Note that the information emitted by
+-- 'reportCursorPosition' is 1-based.) 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.)
+--
+-- @since 0.8.2
+getCursorPosition0 :: IO (Maybe (Int, Int))
+getCursorPosition0 = fmap to0base <$> getCursorPosition
+ where
+  to0base (row, col) = (row - 1, col - 1)
+
+-- | Similar to 'getCursorPosition0', but does not translate the 1-based data
+-- emitted by 'reportCursorPosition' to be 0-based.
+--
+-- @since 0.7.1
 getCursorPosition :: IO (Maybe (Int, Int))

@@ -110,6 +110,9 @@   , hSupportsANSIWithoutEmulation
 
     -- * Getting the cursor position
-  , getCursorPosition
+  , getCursorPosition0
   , getReportedCursorPosition
   , cursorPosition
+
+    -- * Deprecated
+  , getCursorPosition