ansi-terminal 0.9 → 0.9.1

raw patch · 14 files changed

+166/−138 lines, 14 filesdep ~colourPVP ok

version bump matches the API change (PVP)

Dependency ranges changed: colour

API changes (from Hackage documentation)

Files

• CHANGELOG.md +6/−0
• ansi-terminal.cabal +3/−2
• src/System/Console/ANSI.hs +100/−99
• src/System/Console/ANSI/Codes.hs +18/−16
• src/System/Console/ANSI/Types.hs +15/−13
• src/System/Console/ANSI/Unix.hs +1/−0
• src/System/Console/ANSI/Windows.hs +1/−0
• src/System/Console/ANSI/Windows/Detect.hs +1/−0
• src/System/Console/ANSI/Windows/Emulator.hs +1/−0
• src/System/Console/ANSI/Windows/Emulator/Codes.hs +1/−0
• src/System/Console/ANSI/Windows/Foreign.hs +9/−6
• src/System/Win32/Compat.hs +3/−2
• src/includes/Common-Include.hs +2/−0
• src/includes/Common-Safe-Haskell.hs +5/−0

@@ -1,6 +1,12 @@ Changes
 =======
 
+Version 0.9.1
+-------------
+
+* Flag modules with GHC's 'Safe Haskell' language extensions (from GHC 7.2.1).
+* Improvements and corrections to Haddock documentation.
+
 Version 0.9
 -----------
 

@@ -1,5 +1,5 @@ Name:                ansi-terminal
-Version:             0.9
+Version:             0.9.1
 Cabal-Version:       >= 1.8
 Category:            User Interfaces
 Synopsis:            Simple ANSI terminal support, with Windows compatibility
@@ -16,6 +16,7 @@ Extra-Source-Files:     src/includes/Common-Include.hs
                         src/includes/Common-Include-Emulator.hs
                         src/includes/Common-Include-Enabled.hs
+                        src/includes/Common-Safe-Haskell.hs
                         src/includes/Exports-Include.hs
                         CHANGELOG.md
                         README.md
@@ -37,7 +38,7 @@         Include-Dirs:           src/includes
 
         Build-Depends:          base >= 4.3.0.0 && < 5
-                              , colour
+                              , colour >=2.1.0
         if os(windows)
                 Build-Depends:          containers >= 0.5.0.0
                                       , mintty

@@ -1,102 +1,103 @@--- | 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 Windows.
---
--- The sequences of control characters (also referred to as \'escape\' sequences
--- or codes) provide a rich range of functionality for terminal control, which
--- includes:
---
---  * Colored text output, with control over both foreground and background
---    colors
---
---  * Clearing parts of a line or the screen
---
---  * Hiding or showing the cursor
---
---  * Moving the cursor around
---
---  * Reporting the position of the cursor
---
---  * Scrolling the screen up or down
---
---  * 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
--- control sequences. For that software, this library also provides support for
--- such sequences by using emulation.
---
--- 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).
---
--- 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 <http://en.wikipedia.org/wiki/ANSI_escape_code> and
--- those codes supported on current versions of Windows at
--- <https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences>.
---
--- 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. Every function exported by this module comes
--- in three variants, namely:
---
---  * A variant that has an @IO ()@ type and doesn't take a @Handle@ (for
---    example, @clearScreen :: IO ()@). This variant just outputs the \`ANSI\`
---    command directly to the standard output channel ('stdout') and any
---    terminal corresponding to it. Commands issued like this should work as you
---    expect on both Unix-like operating systems and Windows.
---
---  * An \'@h@...\' variant that has an @IO ()@ type but takes a @Handle@ (for
---    example, @hClearScreen :: Handle -> IO ()@). 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.
---
---  * A \'...@Code@\' variant that has a @String@ type (for example,
---    @clearScreenCode :: String@). This variant outputs the sequence of control
---    characters as a 'String', 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 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 "System.Console.ANSI.Codes".
---
--- Example:
---
--- > module Main where
--- >
--- > import System.Console.ANSI
--- >
--- > -- Set colors and write some text in those colors.
--- > 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."
---
--- For many more examples, see the project's extensive
--- <https://github.com/feuerbach/ansi-terminal/blob/master/app/Example.hs Example.hs> file.
+#include "Common-Safe-Haskell.hs"
+
+{-| 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 Windows.
+
+The sequences of control characters (also referred to as \'escape\' sequences or
+codes) provide a rich range of functionality for terminal control, which
+includes:
+
+ * Colored text output, with control over both foreground and background colors
+
+ * Clearing parts of a line or the screen
+
+ * Hiding or showing the cursor
+
+ * Moving the cursor around
+
+ * Reporting the position of the cursor
+
+ * Scrolling the screen up or down
+
+ * 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 control sequences. For that
+software, this library also provides support for such sequences by using
+emulation.
+
+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).
+
+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
+<http://en.wikipedia.org/wiki/ANSI_escape_code> and those codes supported on
+current versions of Windows at
+<https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences>.
+
+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. Every function exported by this module comes in three
+variants, namely:
+
+ * A variant that has an @IO ()@ type and doesn't take a @Handle@ (for example,
+   @clearScreen :: IO ()@). This variant just outputs the \`ANSI\` command
+   directly to the standard output channel ('stdout') and any terminal
+   corresponding to it. Commands issued like this should work as you expect on
+   both Unix-like operating systems and Windows.
+
+ * An \'@h@...\' variant that has an @IO ()@ type but takes a @Handle@ (for
+   example, @hClearScreen :: Handle -> IO ()@). 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.
+
+ * A \'...@Code@\' variant that has a @String@ type (for example,
+   @clearScreenCode :: String@). This variant outputs the sequence of control
+   characters as a 'String', 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 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
+   "System.Console.ANSI.Codes".
+
+Example:
+
+> module Main where
+>
+> import System.Console.ANSI
+>
+> -- Set colors and write some text in those colors.
+> 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."
+
+For many more examples, see the project's extensive
+<https://github.com/feuerbach/ansi-terminal/blob/master/app/Example.hs Example.hs> file.
+-}
 #if defined(WINDOWS)
 module System.Console.ANSI
   (

@@ -1,19 +1,21 @@--- | This module exports functions that return 'String' values containing codes
--- in accordance with the \'ANSI\' standards for control character sequences
--- described in the documentation of module "System.Console.ANSI".
---
--- The module "System.Console.ANSI" 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 "System.Console.ANSI" return \"\", for the reasons set out in the
--- documentation of that module.
---
--- Consequently, if module "System.Console.ANSI" is also imported, this module
--- is intended to be imported qualified, to avoid name clashes with those
--- functions. For example:
---
--- > import qualified System.Console.ANSI.Codes as ANSI
---
+#include "Common-Safe-Haskell.hs"
+
+{-| This module exports functions that return 'String' values containing codes
+in accordance with the \'ANSI\' standards for control character sequences
+described in the documentation of module "System.Console.ANSI".
+
+The module "System.Console.ANSI" 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
+"System.Console.ANSI" return \"\", for the reasons set out in the documentation
+of that module.
+
+Consequently, if module "System.Console.ANSI" is also imported, this module is
+intended to be imported qualified, to avoid name clashes with those functions.
+For example:
+
+> import qualified System.Console.ANSI.Codes as ANSI
+-}
 module System.Console.ANSI.Codes
   (
     -- * Basic data types

@@ -1,13 +1,15 @@--- | The \'ANSI\' standards refer to the visual style of displaying characters
--- as their \'graphic rendition\'. The style includes the color of a character
--- or its background, the intensity (bold, normal or faint) of a character, or
--- whether the character is italic or underlined (single or double), blinking
--- (slowly or rapidly) or visible or not. The \'ANSI\' codes to establish the
--- graphic rendition for subsequent text are referred to as SELECT GRAPHIC
--- RENDITION (SGR).
---
--- This module exports types and functions used to represent SGR aspects. See
--- also 'System.Console.ANSI.setSGR' and related functions.
+#include "Common-Safe-Haskell.hs"
+
+{-| The \'ANSI\' standards refer to the visual style of displaying characters as
+their \'graphic rendition\'. The style includes the color of a character or its
+background, the intensity (bold, normal or faint) of a character, or whether the
+character is italic or underlined (single or double), blinking (slowly or
+rapidly) or visible or not. The \'ANSI\' codes to establish the graphic
+rendition for subsequent text are referred to as SELECT GRAPHIC RENDITION (SGR).
+
+This module exports types and functions used to represent SGR aspects. See also
+'System.Console.ANSI.setSGR' and related functions.
+-}
 module System.Console.ANSI.Types
   (
   -- * Types used to represent SGR aspects
@@ -137,7 +139,7 @@ -- colors. Throws an error if any of the red, green or blue channels is outside
 -- the range 0 to 5. An example of use is:
 --
--- >>> setSGR [ SetRGBColor $ xterm6LevelRGB 5 2 0 ] -- Dark Orange
+-- >>> setSGR [ SetPaletteColor $ xterm6LevelRGB 5 2 0 ] -- Dark Orange
 --
 -- @since 0.9
 xterm6LevelRGB :: Int -> Int -> Int -> Word8
@@ -155,7 +157,7 @@ -- gray (0) to near white (23) (black and white are themselves excluded). Throws
 -- an error if the gray is outside of the range 0 to 23. An example of use is:
 --
--- >>> setSGR [ SetRGBColor $ xterm24LevelGray 12 ] -- Gray50
+-- >>> setSGR [ SetPaletteColor $ xterm24LevelGray 12 ] -- Gray50
 --
 -- @since 0.9
 xterm24LevelGray :: Int -> Word8
@@ -171,7 +173,7 @@ -- standard, or \'system\', colors (eight colors in two intensities). An example
 -- of use is:
 --
--- >>> setSGR [ SetRGBColor $ xtermSystem Vivid Green ]
+-- >>> setSGR [ SetPaletteColor $ xtermSystem Vivid Green ]
 --
 -- @since 0.9
 xtermSystem :: ColorIntensity -> Color -> Word8

@@ -1,3 +1,4 @@+#include "Common-Safe-Haskell.hs"
 {-# OPTIONS_HADDOCK hide #-}
 
 module System.Console.ANSI.Unix

@@ -1,3 +1,4 @@+#include "Common-Safe-Haskell.hs"
 {-# OPTIONS_HADDOCK hide #-}
 
 module System.Console.ANSI.Windows

@@ -1,3 +1,4 @@+{-# LANGUAGE Trustworthy #-}
 {-# OPTIONS_HADDOCK hide #-}
 
 module System.Console.ANSI.Windows.Detect

@@ -1,3 +1,4 @@+{-# LANGUAGE Trustworthy #-}
 {-# OPTIONS_HADDOCK hide #-}
 
 module System.Console.ANSI.Windows.Emulator

@@ -1,3 +1,4 @@+#include "Common-Safe-Haskell.hs"
 {-# OPTIONS_HADDOCK hide #-}
 
 module System.Console.ANSI.Windows.Emulator.Codes

@@ -1,9 +1,11 @@-{-# OPTIONS_HADDOCK hide #-}
-{-# LANGUAGE RankNTypes #-}
+#include "Common-Safe-Haskell.hs"
+{-# OPTIONS_HADDOCK hide        #-}
+{-# LANGUAGE RankNTypes         #-}
 {-# LANGUAGE DeriveDataTypeable #-}
 
--- | "System.Win32.Console" is really very impoverished, so I have had to do all
--- the FFI myself.
+{-| "System.Win32.Console" is really very impoverished, so I have had to do all
+the FFI myself.
+-}
 module System.Console.ANSI.Windows.Foreign
   (
     -- Re-exports from Win32.Types
@@ -58,8 +60,9 @@ import Data.Char (chr, ord)
 import Data.Typeable (Typeable)
 import Foreign.C.Types (CInt (..), CWchar (..))
-import Foreign.Marshal (alloca, allocaArray, maybeWith, peekArray, with,
-  withArrayLen)
+import Foreign.Marshal.Alloc (alloca)
+import Foreign.Marshal.Array (allocaArray, peekArray, withArrayLen)
+import Foreign.Marshal.Utils (maybeWith, with)
 import Foreign.Ptr (Ptr, castPtr, plusPtr)
 import Foreign.Storable (Storable (..))
 -- `SHORT` and `withHandleToHANDLE` are not both available before Win32-2.5.1.0

@@ -1,8 +1,9 @@+#include "Common-Safe-Haskell.hs"
 {-# OPTIONS_HADDOCK hide #-}
 
 {-| The Win32 library ships with GHC. Win32-2.1 first shipped with GHC 6.6
-(released October 2006). Win32-2.5.4.1 first shipped with GHC 8.2.1
-(released July 2017), replacing Win32-2.3.1.1.
+(released October 2006). Win32-2.5.4.1 first shipped with GHC 8.2.1 (released
+July 2017), replacing Win32-2.3.1.1.
 
 The ansi-terminal library makes use of functionality in Win32-2.1 and other
 functionality first added to Win32-2.5.0.0 or Win32-2.5.1.0 (from ansi-terminal

@@ -137,6 +137,8 @@ -- | 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.
+--
+-- @since 0.9
 hSupportsANSIColor :: Handle -> IO Bool
 hSupportsANSIColor h = (||) <$> hSupportsANSI h <*> isEmacsTerm
   where

@@ -0,0 +1,5 @@+#if __GLASGOW_HASKELL__ >= 704
+{-# LANGUAGE Safe #-}
+#elif __GLASGOW_HASKELL__ >= 702
+{-# LANGUAGE Trustworthy #-}
+#endif