safe-coloured-text 0.1.0.0 → 0.2.0.0

raw patch · 5 files changed

+165/−48 lines, 5 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• CHANGELOG.md +9/−0
• safe-coloured-text.cabal +4/−2
• src/Text/Colour.hs +49/−6
• src/Text/Colour/Chunk.hs +62/−16
• src/Text/Colour/Code.hs +41/−24

@@ -0,0 +1,9 @@+# Changelog for safe-coloured-text++## [0.2.0.0] - 2022-06-19++### Changed++* The default output of the library is now `Text`, so that the encoding is not chosen for the user.+  Existing functions for rendering to `ByteString`s have been deprecated but not removed.+* Internal character constants have been changed from `Word8` to `Char`.

@@ -1,11 +1,11 @@ cabal-version: 1.12 --- This file has been generated from package.yaml by hpack version 0.34.4.+-- This file has been generated from package.yaml by hpack version 0.34.7. -- -- see: https://github.com/sol/hpack  name:           safe-coloured-text-version:        0.1.0.0+version:        0.2.0.0 synopsis:       Safely output coloured text category:       User Interfaces homepage:       https://github.com/NorfairKing/safe-coloured-text#readme@@ -16,6 +16,8 @@ license:        MIT license-file:   LICENSE build-type:     Simple+extra-source-files:+    CHANGELOG.md  source-repository head   type: git

@@ -62,32 +62,75 @@      -- * Rendering -    -- ** Rendering chunks to bytestring builders-    renderChunks,-    renderChunk,+    -- ** Rendering chunks to strict bytestring in UTF8+    renderChunksUtf8BS,+    renderChunkUtf8BS, -    -- ** Rendering chunks to strict bytestring+    -- ** Rendering chunks to lazy bytestring builders in UTF8+    renderChunksUtf8BSBuilder,+    renderChunkUtf8BSBuilder,++    -- ** Rendering chunks to strict Text+    renderChunksText,+    renderChunkText,++    -- ** Rendering chunks to lazy text+    renderChunksLazyText,+    renderChunkLazyText,++    -- ** Rendering chunks to lazy text builder+    renderChunksBuilder,+    renderChunkBuilder,++    -- ** Decrecated rendering chunks to strict bytestring in UTF8     renderChunksBS,     renderChunkBS, +    -- ** Deprecated rendering chunks to lazy bytestring builders in UTF8+    renderChunks,+    renderChunk,+     -- * IO     TerminalCapabilities (..),      -- ** Outputting chunks directly+    putChunksUtf8With,+    putChunksLocaleWith,+    hPutChunksUtf8With,+    hPutChunksLocaleWith,     putChunksWith,     hPutChunksWith,   ) where  import qualified Data.ByteString.Builder as SBB+import qualified Data.Text.IO as TIO import System.IO import Text.Colour.Capabilities import Text.Colour.Chunk  -- | Print a list of chunks to stdout with given 'TerminalCapabilities'.+putChunksUtf8With :: TerminalCapabilities -> [Chunk] -> IO ()+putChunksUtf8With tc = hPutChunksUtf8With tc stdout++-- | Print a list of chunks to stdout with given 'TerminalCapabilities' in an encoding according to the system's locale.+putChunksLocaleWith :: TerminalCapabilities -> [Chunk] -> IO ()+putChunksLocaleWith tc = hPutChunksWith tc stdout++-- | Deprecated synonym of 'putChunksUtf8With' putChunksWith :: TerminalCapabilities -> [Chunk] -> IO ()-putChunksWith tc = hPutChunksWith tc stdout+putChunksWith = putChunksUtf8With+{-# DEPRECATED putChunksWith "Use putChunksLocaleWith, or putChunksUtf8With if you must." #-}  -- | Print a list of chunks to the given 'Handle' with given 'TerminalCapabilities'.+hPutChunksUtf8With :: TerminalCapabilities -> Handle -> [Chunk] -> IO ()+hPutChunksUtf8With tc h cs = SBB.hPutBuilder h $ renderChunksUtf8BSBuilder tc cs++-- | Print a list of chunks to the given 'Handle' with given 'TerminalCapabilities' in an encoding according to the system's locale.+hPutChunksLocaleWith :: TerminalCapabilities -> Handle -> [Chunk] -> IO ()+hPutChunksLocaleWith tc h cs = TIO.hPutStr h $ renderChunksText tc cs++-- | Deprecated synonym of 'hPutChunksUtf8With' hPutChunksWith :: TerminalCapabilities -> Handle -> [Chunk] -> IO ()-hPutChunksWith tc h cs = SBB.hPutBuilder h $ renderChunks tc cs+hPutChunksWith = hPutChunksUtf8With+{-# DEPRECATED hPutChunksWith "Use hPutChunksLocaleWith, or hPutChunksUtf8With if you must." #-}

@@ -5,13 +5,15 @@ module Text.Colour.Chunk where  import Data.ByteString (ByteString)-import Data.ByteString.Builder (Builder)-import qualified Data.ByteString.Builder as SBB-import qualified Data.ByteString.Lazy as LB+import qualified Data.ByteString.Builder as ByteString import Data.Maybe import Data.String import Data.Text (Text) import qualified Data.Text.Encoding as TE+import qualified Data.Text.Lazy as LT+import qualified Data.Text.Lazy.Builder as LTB+import qualified Data.Text.Lazy.Builder as Text+import qualified Data.Text.Lazy.Encoding as LTE import Data.Validity import Data.Word import GHC.Generics (Generic)@@ -49,27 +51,71 @@   Colour8Bit {} -> tc < With8BitColours   Colour24Bit {} -> tc < With24BitColours --- | Render a chunk directly to bytestring.+-- | Render chunks directly to a UTF8-encoded 'Bytestring'.+renderChunksUtf8BS :: Foldable f => TerminalCapabilities -> f Chunk -> ByteString+renderChunksUtf8BS tc = TE.encodeUtf8 . renderChunksText tc++-- | Deprecated synonym for 'renderChunksUtf8BS' renderChunksBS :: Foldable f => TerminalCapabilities -> f Chunk -> ByteString-renderChunksBS tc = LB.toStrict . SBB.toLazyByteString . renderChunks tc+renderChunksBS = renderChunksUtf8BS+{-# DEPRECATED renderChunksBS "Use renderChunksText, or renderChunksUtf8BS if you must." #-} --- | Render chunks to a bytestring builder-renderChunks :: Foldable f => TerminalCapabilities -> f Chunk -> Builder-renderChunks tc = foldMap (renderChunk tc)+-- | Render chunks to a UTF8-encoded 'ByteString' 'Bytestring.Builder'.+renderChunksUtf8BSBuilder :: Foldable f => TerminalCapabilities -> f Chunk -> ByteString.Builder+renderChunksUtf8BSBuilder tc = foldMap (renderChunkUtf8BSBuilder tc) --- | Render a chunk directly to bytestring.+-- | Deprecated synonym for 'renderChunksUtf8BSBuilder'+renderChunks :: Foldable f => TerminalCapabilities -> f Chunk -> ByteString.Builder+renderChunks = renderChunksUtf8BSBuilder+{-# DEPRECATED renderChunks "Use renderChunksBuilder, or renderChunksUtf8BSBuilder if you must." #-}++-- | Render chunks directly to strict 'Text'.+renderChunksText :: Foldable f => TerminalCapabilities -> f Chunk -> Text+renderChunksText tc = LT.toStrict . renderChunksLazyText tc++-- | Render chunks directly to lazy 'LT.Text'.+renderChunksLazyText :: Foldable f => TerminalCapabilities -> f Chunk -> LT.Text+renderChunksLazyText tc = LTB.toLazyText . renderChunksBuilder tc++-- | Render chunks to a lazy 'LT.Text' 'Text.Builder'+renderChunksBuilder :: Foldable f => TerminalCapabilities -> f Chunk -> Text.Builder+renderChunksBuilder tc = foldMap (renderChunkBuilder tc)++-- | Render a chunk directly to a UTF8-encoded 'Bytestring'.+renderChunkUtf8BS :: TerminalCapabilities -> Chunk -> ByteString+renderChunkUtf8BS tc = TE.encodeUtf8 . renderChunkText tc++-- | Deprecated synonym for 'renderChunkUtf8BS' renderChunkBS :: TerminalCapabilities -> Chunk -> ByteString-renderChunkBS tc = LB.toStrict . SBB.toLazyByteString . renderChunk tc+renderChunkBS = renderChunkUtf8BS+{-# DEPRECATED renderChunkBS "Use renderChunkText, or renderChunkUtf8BS if you must." #-} --- | Render a chunk to a bytestring builder-renderChunk :: TerminalCapabilities -> Chunk -> Builder-renderChunk tc c@Chunk {..} =+-- | Render a chunk directly to a UTF8-encoded 'Bytestring' 'ByteString.Builder'.+renderChunkUtf8BSBuilder :: TerminalCapabilities -> Chunk -> ByteString.Builder+renderChunkUtf8BSBuilder tc = LTE.encodeUtf8Builder . renderChunkLazyText tc++-- | Deprecated synonym for 'renderChunkUtf8BSBuilder'+renderChunk :: TerminalCapabilities -> Chunk -> ByteString.Builder+renderChunk = renderChunkUtf8BSBuilder+{-# DEPRECATED renderChunk "Use renderChunkBuilder, or renderChunkUtf8BSBuilder if you must." #-}++-- | Render a chunk directly to strict 'Text'.+renderChunkText :: TerminalCapabilities -> Chunk -> Text+renderChunkText tc = LT.toStrict . renderChunkLazyText tc++-- | Render a chunk directly to strict 'LT.Text'.+renderChunkLazyText :: TerminalCapabilities -> Chunk -> LT.Text+renderChunkLazyText tc = LTB.toLazyText . renderChunkBuilder tc++-- | Render a chunk to a lazy 'LT.Text' 'Text.Builder'+renderChunkBuilder :: TerminalCapabilities -> Chunk -> Text.Builder+renderChunkBuilder tc c@Chunk {..} =   if plainChunk tc c-    then SBB.byteString (TE.encodeUtf8 chunkText)+    then LTB.fromText chunkText     else       mconcat-        [ renderCSI (SGR $ chunkSGR tc c),-          SBB.byteString (TE.encodeUtf8 chunkText),+        [ renderCSI (SGR (chunkSGR tc c)),+          LTB.fromText chunkText,           renderCSI (SGR [Reset])         ] 

@@ -4,11 +4,13 @@ module Text.Colour.Code where  import Data.ByteString (ByteString)-import Data.ByteString.Builder (Builder)-import qualified Data.ByteString.Builder as SBB-import qualified Data.ByteString.Internal as SBI-import qualified Data.ByteString.Lazy as LB import Data.List+import Data.Text (Text)+import qualified Data.Text.Encoding as TE+import qualified Data.Text.Lazy as LT+import qualified Data.Text.Lazy.Builder as LTB+import qualified Data.Text.Lazy.Builder as Text+import qualified Data.Text.Lazy.Builder.Int as LTB import Data.Validity import Data.Validity.ByteString () import Data.Validity.Text ()@@ -16,14 +18,14 @@ import GHC.Generics (Generic)  -- https://en.wikipedia.org/wiki/Escape_character#ASCII_escape_character-asciiEscape :: Word8-asciiEscape = SBI.c2w '\ESC'+asciiEscape :: Char+asciiEscape = '\ESC' -csiStart :: Word8-csiStart = SBI.c2w '['+csiStart :: Char+csiStart = '[' -csiDelimiter :: Word8-csiDelimiter = SBI.c2w ';'+csiDelimiter :: Char+csiDelimiter = ';'  newtype CSI   = SGR [SGR]@@ -31,24 +33,39 @@  instance Validity CSI --- | Render a CSI directly to bytestring.+-- | Render a CSI directly to 'ByteString' using UTF8.+-- -- You probably want to use 'renderCSI' instead. -- This is just for testing.-renderCSIBS :: CSI -> ByteString-renderCSIBS = LB.toStrict . SBB.toLazyByteString . renderCSI+renderCSIUtf8BS :: CSI -> ByteString+renderCSIUtf8BS = TE.encodeUtf8 . renderCSIText +-- | Render a CSI directly to strict 'Text'.+--+-- You probably want to use 'renderCSI' instead.+-- This is just for testing.+renderCSIText :: CSI -> Text+renderCSIText = LT.toStrict . renderCSILazyText++-- | Render a CSI directly to lazy 'LT.Text'.+--+-- You probably want to use 'renderCSI' instead.+-- This is just for testing.+renderCSILazyText :: CSI -> LT.Text+renderCSILazyText = LTB.toLazyText . renderCSI+ -- https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences-renderCSI :: CSI -> Builder+renderCSI :: CSI -> Text.Builder renderCSI =   let csi ps c =         mconcat-          [ SBB.word8 asciiEscape,-            SBB.word8 csiStart,-            csiParamsToWords ps,-            SBB.word8 c+          [ LTB.singleton asciiEscape,+            LTB.singleton csiStart,+            renderCSIParams ps,+            LTB.singleton c           ]    in \case-        SGR sgrs -> csi (concatMap sgrToCSIParams sgrs) (SBI.c2w 'm')+        SGR sgrs -> csi (concatMap sgrToCSIParams sgrs) 'm'  -- https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters data SGR@@ -67,13 +84,13 @@  instance Validity SGR -csiParamsToWords :: [Word8] -> Builder-csiParamsToWords = mconcat . intersperse (SBB.word8 csiDelimiter) . map csiParamToWord+renderCSIParams :: [Word8] -> Text.Builder+renderCSIParams = mconcat . intersperse (LTB.singleton csiDelimiter) . map renderCSIParam -csiParamToWord :: Word8 -> Builder-csiParamToWord = \case+renderCSIParam :: Word8 -> Text.Builder+renderCSIParam = \case   0 -> mempty-  w -> SBB.word8Dec w+  w -> LTB.decimal w  sgrToCSIParams :: SGR -> [Word8] sgrToCSIParams = \case