-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Print text to terminal with colors and effects
--
-- Please see README.md
@package rainbow
@version 0.34.2.2
-- | All the main types in Rainbow. Using this module you can specify that
-- you want different formatting for 8- and 256-color terminals. Many of
-- the names in this module conflict with the names in Rainbow, so
-- it's probably best to import this module qualified.
module Rainbow.Types
-- | A color; a Nothing value means that the terminal's default
-- color is used. The type of the Maybe generally will be an
-- Enum8 to represent one of 8 colors, or a Word8 to
-- represent one of 256 colors.
newtype Color a
Color :: Maybe a -> Color a
-- | A simple enumeration for eight values. Represents eight colors.
data Enum8
E0 :: Enum8
E1 :: Enum8
E2 :: Enum8
E3 :: Enum8
E4 :: Enum8
E5 :: Enum8
E6 :: Enum8
E7 :: Enum8
enum8toWord8 :: Enum8 -> Word8
black :: Enum8
red :: Enum8
green :: Enum8
yellow :: Enum8
blue :: Enum8
magenta :: Enum8
cyan :: Enum8
white :: Enum8
grey :: Word8
brightRed :: Word8
brightGreen :: Word8
brightYellow :: Word8
brightBlue :: Word8
brightMagenta :: Word8
brightCyan :: Word8
brightWhite :: Word8
-- | Text formatting such as bold, italic, etc.
data Format
Format :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Format
[_bold] :: Format -> Bool
[_faint] :: Format -> Bool
[_italic] :: Format -> Bool
[_underline] :: Format -> Bool
[_blink] :: Format -> Bool
[_inverse] :: Format -> Bool
[_invisible] :: Format -> Bool
[_strikeout] :: Format -> Bool
underline :: Lens' Format Bool
strikeout :: Lens' Format Bool
italic :: Lens' Format Bool
invisible :: Lens' Format Bool
inverse :: Lens' Format Bool
faint :: Lens' Format Bool
bold :: Lens' Format Bool
blink :: Lens' Format Bool
-- | The foreground and background color, and the Format. This
-- represents all colors and formatting attributes for either an 8- or
-- 256-color terminal.
data Style a
Style :: Color a -> Color a -> Format -> Style a
[_fore] :: Style a -> Color a
[_back] :: Style a -> Color a
[_format] :: Style a -> Format
format :: forall a_akmi. Lens' (Style a_akmi) Format
fore :: forall a_akmi. Lens' (Style a_akmi) (Color a_akmi)
back :: forall a_akmi. Lens' (Style a_akmi) (Color a_akmi)
-- | Holds the Style for both 8- and 256-color terminals.
data Scheme
Scheme :: Style Enum8 -> Style Word8 -> Scheme
[_style8] :: Scheme -> Style Enum8
[_style256] :: Scheme -> Style Word8
style8 :: Lens' Scheme (Style Enum8)
style256 :: Lens' Scheme (Style Word8)
-- | A chunk is some textual data coupled with a description of what color
-- the text is, attributes like whether it is bold or underlined, etc.
-- The chunk knows what foreground and background colors and what
-- attributes to use for both an 8 color terminal and a 256 color
-- terminal.
data Chunk
Chunk :: Scheme -> Text -> Chunk
[_scheme] :: Chunk -> Scheme
[_yarn] :: Chunk -> Text
-- | Creates a Chunk with no formatting and with the given text. A
-- Chunk is also an instance of IsString so you can create
-- them with the OverloadedStrings extension. Such a
-- Chunk has the text of the string and no formatting.
chunk :: Text -> Chunk
yarn :: Lens' Chunk Text
scheme :: Lens' Chunk Scheme
-- | Stores colors that may affect 8-color terminals, 256-color terminals,
-- both, or neither.
data Radiant
Radiant :: Color Enum8 -> Color Word8 -> Radiant
[_color8] :: Radiant -> Color Enum8
[_color256] :: Radiant -> Color Word8
color8 :: Lens' Radiant (Color Enum8)
color256 :: Lens' Radiant (Color Word8)
instance GHC.Generics.Generic Rainbow.Types.Radiant
instance GHC.Show.Show Rainbow.Types.Radiant
instance GHC.Classes.Ord Rainbow.Types.Radiant
instance GHC.Classes.Eq Rainbow.Types.Radiant
instance GHC.Base.Semigroup Rainbow.Types.Radiant
instance GHC.Base.Monoid Rainbow.Types.Radiant
instance GHC.Generics.Generic Rainbow.Types.Chunk
instance GHC.Classes.Ord Rainbow.Types.Chunk
instance GHC.Show.Show Rainbow.Types.Chunk
instance GHC.Classes.Eq Rainbow.Types.Chunk
instance GHC.Base.Semigroup Rainbow.Types.Chunk
instance Data.String.IsString Rainbow.Types.Chunk
instance GHC.Base.Monoid Rainbow.Types.Chunk
instance GHC.Base.Semigroup Rainbow.Types.Scheme
instance GHC.Base.Monoid Rainbow.Types.Scheme
instance GHC.Generics.Generic Rainbow.Types.Scheme
instance GHC.Show.Show Rainbow.Types.Scheme
instance GHC.Classes.Ord Rainbow.Types.Scheme
instance GHC.Classes.Eq Rainbow.Types.Scheme
instance GHC.Base.Semigroup (Rainbow.Types.Style a)
instance GHC.Base.Monoid (Rainbow.Types.Style a)
instance Data.Traversable.Traversable Rainbow.Types.Style
instance Data.Foldable.Foldable Rainbow.Types.Style
instance GHC.Base.Functor Rainbow.Types.Style
instance GHC.Generics.Generic (Rainbow.Types.Style a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Rainbow.Types.Style a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Rainbow.Types.Style a)
instance GHC.Show.Show a => GHC.Show.Show (Rainbow.Types.Style a)
instance GHC.Base.Semigroup Rainbow.Types.Format
instance GHC.Base.Monoid Rainbow.Types.Format
instance GHC.Generics.Generic Rainbow.Types.Format
instance GHC.Classes.Ord Rainbow.Types.Format
instance GHC.Classes.Eq Rainbow.Types.Format
instance GHC.Show.Show Rainbow.Types.Format
instance GHC.Generics.Generic Rainbow.Types.Enum8
instance GHC.Enum.Enum Rainbow.Types.Enum8
instance GHC.Enum.Bounded Rainbow.Types.Enum8
instance GHC.Show.Show Rainbow.Types.Enum8
instance GHC.Classes.Ord Rainbow.Types.Enum8
instance GHC.Classes.Eq Rainbow.Types.Enum8
instance Data.Traversable.Traversable Rainbow.Types.Color
instance Data.Foldable.Foldable Rainbow.Types.Color
instance GHC.Base.Functor Rainbow.Types.Color
instance GHC.Generics.Generic (Rainbow.Types.Color a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Rainbow.Types.Color a)
instance GHC.Show.Show a => GHC.Show.Show (Rainbow.Types.Color a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Rainbow.Types.Color a)
instance GHC.Base.Semigroup (Rainbow.Types.Color a)
instance GHC.Base.Monoid (Rainbow.Types.Color a)
-- | This module contains functions that convert a Chunk into
-- ByteStrings. Ordinarily everything you need from this module is
-- exported from Rainbow.
module Rainbow.Translate
single :: Char -> [ByteString] -> [ByteString]
escape :: [ByteString] -> [ByteString]
csi :: [ByteString] -> [ByteString]
sgr :: ([ByteString] -> [ByteString]) -> [ByteString] -> [ByteString]
params :: Show a => [a] -> [ByteString] -> [ByteString]
sgrSingle :: Word -> [ByteString] -> [ByteString]
sgrDouble :: Word -> Word -> [ByteString] -> [ByteString]
normalDefault :: [ByteString] -> [ByteString]
bold :: [ByteString] -> [ByteString]
faint :: [ByteString] -> [ByteString]
italic :: [ByteString] -> [ByteString]
underline :: [ByteString] -> [ByteString]
blink :: [ByteString] -> [ByteString]
inverse :: [ByteString] -> [ByteString]
invisible :: [ByteString] -> [ByteString]
strikeout :: [ByteString] -> [ByteString]
foreBlack :: [ByteString] -> [ByteString]
foreRed :: [ByteString] -> [ByteString]
foreGreen :: [ByteString] -> [ByteString]
foreYellow :: [ByteString] -> [ByteString]
foreBlue :: [ByteString] -> [ByteString]
foreMagenta :: [ByteString] -> [ByteString]
foreCyan :: [ByteString] -> [ByteString]
foreWhite :: [ByteString] -> [ByteString]
foreDefault :: [ByteString] -> [ByteString]
backBlack :: [ByteString] -> [ByteString]
backRed :: [ByteString] -> [ByteString]
backGreen :: [ByteString] -> [ByteString]
backYellow :: [ByteString] -> [ByteString]
backBlue :: [ByteString] -> [ByteString]
backMagenta :: [ByteString] -> [ByteString]
backCyan :: [ByteString] -> [ByteString]
backWhite :: [ByteString] -> [ByteString]
backDefault :: [ByteString] -> [ByteString]
fore256 :: Word8 -> [ByteString] -> [ByteString]
back256 :: Word8 -> [ByteString] -> [ByteString]
foreColor8 :: Enum8 -> [ByteString] -> [ByteString]
backColor8 :: Enum8 -> [ByteString] -> [ByteString]
renderFormat :: Format -> [ByteString] -> [ByteString]
renderStyle8 :: Style Enum8 -> [ByteString] -> [ByteString]
renderStyle256 :: Style Word8 -> [ByteString] -> [ByteString]
render :: Text -> [ByteString] -> [ByteString]
toByteStringsColors0 :: Chunk -> [ByteString] -> [ByteString]
toByteStringsColors8 :: Chunk -> [ByteString] -> [ByteString]
toByteStringsColors256 :: Chunk -> [ByteString] -> [ByteString]
-- | Uses setupTermFromEnv to obtain the terminal's color
-- capability. If this says there are at least 256 colors are available,
-- returns toByteStringsColors256. Otherwise, if there are at
-- least 8 colors available, returns toByteStringsColors8.
-- Otherwise, returns toByteStringsColors0.
--
-- If the terminfo database could not be read (that is, if
-- SetupTermError is returned), then return
-- toByteStringsColors0.
byteStringMakerFromEnvironment :: IO (Chunk -> [ByteString] -> [ByteString])
-- | Like byteStringMakerFromEnvironment but also consults a
-- provided Handle. If the Handle is not a terminal,
-- toByteStringsColors0 is returned. Otherwise, the value of
-- byteStringMakerFromEnvironment is returned.
byteStringMakerFromHandle :: Handle -> IO (Chunk -> [ByteString] -> [ByteString])
-- | Convert a list of Chunk to a list of ByteString. The
-- length of the returned list may be longer than the length of the input
-- list.
--
-- So, for example, to print a bunch of chunks to standard output using
-- 256 colors:
--
--
-- module PrintMyChunks where
--
-- import qualified Data.ByteString as BS
-- import Rainbow
--
-- myChunks :: [Chunk String]
-- myChunks = [ chunk "Roses" & fore red, chunk "\n",
-- chunk "Violets" & fore blue, chunk "\n" ]
--
-- myPrintedChunks :: IO ()
-- myPrintedChunks = mapM_ BS.putStr
-- . chunksToByteStrings toByteStringsColors256
-- $ myChunks
--
--
-- To use the highest number of colors that this terminal supports:
--
--
-- myPrintedChunks' :: IO ()
-- myPrintedChunks' = do
-- printer <- byteStringMakerFromEnvironment
-- mapM_ BS.putStr
-- . chunksToByteStrings printer
-- $ myChunks
--
chunksToByteStrings :: (Chunk -> [ByteString] -> [ByteString]) -> [Chunk] -> [ByteString]
-- | Writes a list of chunks to the given Handle.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to the given
-- Handle.
hPutChunks :: Handle -> [Chunk] -> IO ()
-- | Writes a list of chunks to the given Handle, followed by a
-- newline character.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to the given
-- Handle.
hPutChunksLn :: Handle -> [Chunk] -> IO ()
-- | Writes a list of chunks to standard output.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to standard output.
putChunks :: [Chunk] -> IO ()
-- | Writes a list of chunks to standard output, followed by a newline.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to standard output.
putChunksLn :: [Chunk] -> IO ()
-- | Writes a Chunk to standard output. Uses
-- byteStringMakerFromEnvironment each time you apply it, so this
-- might be inefficient. You are better off using
-- chunksToByteStrings and the functions in Data.ByteString
-- to print your Chunks if you are printing a lot of them.
putChunk :: Chunk -> IO ()
-- | Writes a Chunk to standard output, and appends a newline. Uses
-- byteStringMakerFromEnvironment each time you apply it, so this
-- might be inefficient. You are better off using
-- chunksToByteStrings and the functions in Data.ByteString
-- to print your Chunks if you are printing a lot of them.
putChunkLn :: Chunk -> IO ()
-- | Rainbow handles colors and special effects for text. The basic
-- building block of Rainbow is the Chunk. The Chunk
-- contains both text and formatting information such as colors, bold,
-- underlining, etc. Chunk is an instance of IsString so
-- you can create a Chunk using the OverloadedStrings
-- extension. Such a chunk has the given text and has no formatting.
--
-- When printed, each Chunk starts off with a clean slate, so if
-- you want special formatting such as any color, bold, etc, then you
-- must specify it for every Chunk. The appearance of one
-- Chunk does not affect the appearance of the next Chunk.
-- This makes it easy to reason about how a particular Chunk will
-- look.
--
-- Rainbow supports 256-color terminals. You have full freedom to specify
-- different attributes and colors for 8 and 256 color terminals; for
-- instance, you can have text appear red on an 8-color terminal but blue
-- on a 256-color terminal.
--
-- Here are some basic examples:
--
--
-- ghci> import Rainbow
-- ghci> import Data.Function ((&))
-- ghci> :set -XOverloadedStrings
-- ghci> putChunkLn $ "Some blue text" & fore blue
-- ghci> putChunkLn $ "Blue on red background"
-- & fore blue & back red
-- ghci> putChunkLn $ "Blue on red, foreground bold"
-- & fore blue & back red & bold
--
--
-- You can also specify output for 256-color terminals. To use these
-- examples, be sure your TERM environment variable is set to something
-- that supports 256 colors (like xterm-256color) before you
-- start GHCi.
--
--
-- ghci> putChunkLn $ "Blue on 8, bright green on 256" &
-- fore (blue <> brightGreen)
--
-- ghci> putChunkLn $ "Blue on 8, red on 256" &
-- fore (blue <> only256 red)
--
--
-- Each Chunk affects the formatting only of that Chunk. So
-- to print things in different colors, make more than one Chunk:
--
--
-- ghci> putChunksLn
-- [ "Roses" & fore red
-- , "Violets" & fore blue ]
--
--
-- Most of the above examples use putChunkLn, but that function
-- may be inefficient if you are printing many Chunks. For greater
-- efficiency use functions under the heading "Converting multiple Chunk
-- to ByteString", including putChunksLn and putChunks.
--
-- The functions in this module, Rainbow, will likely be enough
-- for most uses, but for more flexibility you can use
-- Rainbow.Types. Use of Rainbow.Types will require some
-- familiarity with the lens library.
module Rainbow
-- | A chunk is some textual data coupled with a description of what color
-- the text is, attributes like whether it is bold or underlined, etc.
-- The chunk knows what foreground and background colors and what
-- attributes to use for both an 8 color terminal and a 256 color
-- terminal.
data Chunk
-- | Creates a Chunk with no formatting and with the given text. A
-- Chunk is also an instance of IsString so you can create
-- them with the OverloadedStrings extension. Such a
-- Chunk has the text of the string and no formatting.
chunk :: Text -> Chunk
-- | Bold. What actually happens when you use Bold is going to depend on
-- your terminal. For example, xterm allows you actually use a bold font
-- for bold, if you have one. Otherwise, it might simulate bold by using
-- overstriking. Another possibility is that your terminal might use a
-- different color to indicate bold. For more details (at least for
-- xterm), look at xterm (1) and search for boldColors.
--
-- If your terminal uses a different color for bold, this allows an
-- 8-color terminal to really have 16 colors.
bold :: Chunk -> Chunk
faint :: Chunk -> Chunk
italic :: Chunk -> Chunk
underline :: Chunk -> Chunk
blink :: Chunk -> Chunk
inverse :: Chunk -> Chunk
invisible :: Chunk -> Chunk
strikeout :: Chunk -> Chunk
-- | Stores colors that may affect 8-color terminals, 256-color terminals,
-- both, or neither.
data Radiant
-- | Change the foreground color. Whether this affects 8-color terminals,
-- 256-color terminals, or both depends on the Radiant.
fore :: Radiant -> Chunk -> Chunk
-- | Change the background color. Whether this affects 8-color terminals,
-- 256-color terminals, or both depends on the Radiant.
back :: Radiant -> Chunk -> Chunk
black :: Radiant
red :: Radiant
green :: Radiant
yellow :: Radiant
blue :: Radiant
magenta :: Radiant
cyan :: Radiant
white :: Radiant
grey :: Radiant
brightRed :: Radiant
brightGreen :: Radiant
brightYellow :: Radiant
brightBlue :: Radiant
brightMagenta :: Radiant
brightCyan :: Radiant
brightWhite :: Radiant
-- | A Radiant for any of the 256 colors available. Supply the color
-- number. Exactly which color you'll get for a given number is dependent
-- on the terminal; though there seem to be common defaults, often the
-- user can configure this however she likes. The resulting
-- Radiant will affect 256-color terminals only.
color256 :: Word8 -> Radiant
-- | Ensures that a Radiant affects only a 256-color terminal. For
-- instance, to make text that is blue on an 8-color terminal but red on
-- a 256-color terminal:
--
--
-- putChunkLn $ "Blue on 8, red on 256" &
-- fore (blue <> only256 red)
--
only256 :: Radiant -> Radiant
toByteStringsColors0 :: Chunk -> [ByteString] -> [ByteString]
toByteStringsColors8 :: Chunk -> [ByteString] -> [ByteString]
toByteStringsColors256 :: Chunk -> [ByteString] -> [ByteString]
-- | Uses setupTermFromEnv to obtain the terminal's color
-- capability. If this says there are at least 256 colors are available,
-- returns toByteStringsColors256. Otherwise, if there are at
-- least 8 colors available, returns toByteStringsColors8.
-- Otherwise, returns toByteStringsColors0.
--
-- If the terminfo database could not be read (that is, if
-- SetupTermError is returned), then return
-- toByteStringsColors0.
byteStringMakerFromEnvironment :: IO (Chunk -> [ByteString] -> [ByteString])
-- | Like byteStringMakerFromEnvironment but also consults a
-- provided Handle. If the Handle is not a terminal,
-- toByteStringsColors0 is returned. Otherwise, the value of
-- byteStringMakerFromEnvironment is returned.
byteStringMakerFromHandle :: Handle -> IO (Chunk -> [ByteString] -> [ByteString])
-- | Convert a list of Chunk to a list of ByteString. The
-- length of the returned list may be longer than the length of the input
-- list.
--
-- So, for example, to print a bunch of chunks to standard output using
-- 256 colors:
--
--
-- module PrintMyChunks where
--
-- import qualified Data.ByteString as BS
-- import Rainbow
--
-- myChunks :: [Chunk String]
-- myChunks = [ chunk "Roses" & fore red, chunk "\n",
-- chunk "Violets" & fore blue, chunk "\n" ]
--
-- myPrintedChunks :: IO ()
-- myPrintedChunks = mapM_ BS.putStr
-- . chunksToByteStrings toByteStringsColors256
-- $ myChunks
--
--
-- To use the highest number of colors that this terminal supports:
--
--
-- myPrintedChunks' :: IO ()
-- myPrintedChunks' = do
-- printer <- byteStringMakerFromEnvironment
-- mapM_ BS.putStr
-- . chunksToByteStrings printer
-- $ myChunks
--
chunksToByteStrings :: (Chunk -> [ByteString] -> [ByteString]) -> [Chunk] -> [ByteString]
-- | Writes a list of chunks to standard output.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to standard output.
putChunks :: [Chunk] -> IO ()
-- | Writes a list of chunks to the given Handle.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to the given
-- Handle.
hPutChunks :: Handle -> [Chunk] -> IO ()
-- | Writes a list of chunks to standard output, followed by a newline.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to standard output.
putChunksLn :: [Chunk] -> IO ()
-- | Writes a list of chunks to the given Handle, followed by a
-- newline character.
--
-- First uses byteStringMakerFromEnvironment to determine how many
-- colors to use. Then creates a list of ByteString using
-- chunksToByteStrings and then writes them to the given
-- Handle.
hPutChunksLn :: Handle -> [Chunk] -> IO ()
-- | Writes a Chunk to standard output. Uses
-- byteStringMakerFromEnvironment each time you apply it, so this
-- might be inefficient. You are better off using
-- chunksToByteStrings and the functions in Data.ByteString
-- to print your Chunks if you are printing a lot of them.
putChunk :: Chunk -> IO ()
-- | Writes a Chunk to standard output, and appends a newline. Uses
-- byteStringMakerFromEnvironment each time you apply it, so this
-- might be inefficient. You are better off using
-- chunksToByteStrings and the functions in Data.ByteString
-- to print your Chunks if you are printing a lot of them.
putChunkLn :: Chunk -> IO ()