-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Print text to terminal with colors and effects
--
@package rainbow
@version 0.26.0.4
-- | 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
-- | Takes the last non-Nothing Color. mempty is no color.
-- | 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
-- | For each field, the resulting field is True if either field is True.
-- For mempty, every field is False.
-- | 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 :: Lens' (Style a_aaig) Format
fore :: Lens' (Style a_aaig) (Color a_aaig)
back :: Lens' (Style a_aaig) (Color a_aaig)
-- | Uses the underlying Monoid instances for Color and
-- Format.
-- | 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 a
Chunk :: Scheme -> a -> Chunk a
_scheme :: Chunk a -> Scheme
_yarn :: Chunk a -> a
-- | Uses the underlying Monoid instances for the Style and
-- for the particular _yarn. Therefore mempty will have no
-- formatting and no colors and will generally have no text, though
-- whether or not there is any text depends on the mempty for the
-- type of the _yarn.
-- | Creates a Chunk with no formatting and with the given text.
chunk :: a -> Chunk a
yarn :: Lens (Chunk a_aaQ2) (Chunk a_aaZX) a_aaQ2 a_aaZX
scheme :: Lens' (Chunk a_aaQ2) 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
-- | Uses the underlying Monoid instance for the Colors. Thus
-- the last non-Nothing Color is used. This can be useful
-- to specify one color for 8-color terminals and a different color for
-- 256-color terminals.
color8 :: Lens' Radiant (Color Enum8)
color256 :: Lens' Radiant (Color Word8)
instance Typeable Radiant
instance Eq Radiant
instance Ord Radiant
instance Show Radiant
instance Generic Radiant
instance Datatype D1Radiant
instance Constructor C1_0Radiant
instance Selector S1_0_0Radiant
instance Selector S1_0_1Radiant
instance Monoid Radiant
instance Typeable Chunk
instance Eq a => Eq (Chunk a)
instance Show a => Show (Chunk a)
instance Ord a => Ord (Chunk a)
instance Generic (Chunk a)
instance Functor Chunk
instance Foldable Chunk
instance Traversable Chunk
instance Datatype D1Chunk
instance Constructor C1_0Chunk
instance Selector S1_0_0Chunk
instance Selector S1_0_1Chunk
instance Monoid a => Monoid (Chunk a)
instance Monoid Scheme
instance Typeable Scheme
instance Eq Scheme
instance Ord Scheme
instance Show Scheme
instance Generic Scheme
instance Datatype D1Scheme
instance Constructor C1_0Scheme
instance Selector S1_0_0Scheme
instance Selector S1_0_1Scheme
instance Monoid (Style a)
instance Typeable Style
instance Show a => Show (Style a)
instance Eq a => Eq (Style a)
instance Ord a => Ord (Style a)
instance Generic (Style a)
instance Functor Style
instance Foldable Style
instance Traversable Style
instance Datatype D1Style
instance Constructor C1_0Style
instance Selector S1_0_0Style
instance Selector S1_0_1Style
instance Selector S1_0_2Style
instance Monoid Format
instance Typeable Enum8
instance Typeable Format
instance Eq Enum8
instance Ord Enum8
instance Show Enum8
instance Bounded Enum8
instance Enum Enum8
instance Generic Enum8
instance Show Format
instance Eq Format
instance Ord Format
instance Generic Format
instance Datatype D1Enum8
instance Constructor C1_0Enum8
instance Constructor C1_1Enum8
instance Constructor C1_2Enum8
instance Constructor C1_3Enum8
instance Constructor C1_4Enum8
instance Constructor C1_5Enum8
instance Constructor C1_6Enum8
instance Constructor C1_7Enum8
instance Datatype D1Format
instance Constructor C1_0Format
instance Selector S1_0_0Format
instance Selector S1_0_1Format
instance Selector S1_0_2Format
instance Selector S1_0_3Format
instance Selector S1_0_4Format
instance Selector S1_0_5Format
instance Selector S1_0_6Format
instance Selector S1_0_7Format
instance Monoid (Color a)
instance Wrapped (Color a0)
instance Color a1 ~ t0 => Rewrapped (Color a0) t0
instance Typeable Color
instance Eq a => Eq (Color a)
instance Show a => Show (Color a)
instance Ord a => Ord (Color a)
instance Generic (Color a)
instance Functor Color
instance Foldable Color
instance Traversable Color
instance Datatype D1Color
instance Constructor C1_0Color
-- | This module contains functions that convert a Chunk into
-- ByteStrings. Ordinarily everything you need from this module is
-- exported from Rainbow.
module Rainbow.Translate
-- | Items that can be rendered. render returns a difference list.
class Renderable a
render :: Renderable a => a -> [ByteString] -> [ByteString]
-- | Converts a strict Text to a UTF-8 ByteString.
-- | Converts a lazy Text to UTF-8 ByteStrings.
-- | Strict ByteString is left as-is.
-- | Lazy ByteString is converted to strict chunks.
-- | Strings are converted first to a strict Text and then to a strict
-- ByteString.
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]
toByteStringsColors0 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]
toByteStringsColors8 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]
toByteStringsColors256 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]
-- | Spawns a subprocess to read the output of tput colors. 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 any IO exceptions arise during this process, they are discarded and
-- toByteStringsColors0 is returned.
byteStringMakerFromEnvironment :: Renderable a => IO (Chunk a -> [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 :: Renderable a => Handle -> IO (Chunk a -> [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 a -> [ByteString] -> [ByteString]) -> [Chunk a] -> [ByteString]
-- | Writes a Chunk to standard output. Spawns a child process to
-- read the output of tput colors to determine how many colors
-- to use, for every single chunk. Therefore, this is not going to win
-- any speed awards. 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 :: Renderable a => Chunk a -> IO ()
-- | Writes a Chunk to standard output, and appends a newline.
-- Spawns a child process to read the output of tput colors to
-- determine how many colors to use, for every single chunk. Therefore,
-- this is not going to win any speed awards. 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 :: Renderable a => Chunk a -> IO ()
instance Renderable String
instance Renderable ByteString
instance Renderable ByteString
instance Renderable Text
instance Renderable Text
-- | 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.
--
-- 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:
--
--
-- putChunkLn $ chunk "Some blue text" & fore blue
-- putChunkLn $ chunk "Blue on red background"
-- & fore blue & back red
-- putChunkLn $ chunk "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.
--
--
-- putChunkLn $ chunk "Blue on 8, bright green on 256" &
-- fore (blue <> brightGreen)
--
-- putChunkLn $ chunk "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:
--
--
-- mapM_ putChunkLn
-- [ chunk "Roses" & fore red
-- , chunk "Violets" & fore blue ]
--
--
-- The above examples use putChunkLn, but that function will be
-- inefficient if you are printing many Chunks. For greater
-- efficiency see chunksToByteStrings.
--
-- 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 a
-- | Creates a Chunk with no formatting and with the given text.
chunk :: a -> Chunk a
-- | 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 a -> Chunk a
faint :: Chunk a -> Chunk a
italic :: Chunk a -> Chunk a
underline :: Chunk a -> Chunk a
blink :: Chunk a -> Chunk a
inverse :: Chunk a -> Chunk a
invisible :: Chunk a -> Chunk a
strikeout :: Chunk a -> Chunk a
-- | Stores colors that may affect 8-color terminals, 256-color terminals,
-- both, or neither.
data Radiant
-- | Change the foreground color for both 8- and 256-color terminals.
fore :: Radiant -> Chunk a -> Chunk a
-- | Change the background color for both 8- and 256-color terminals.
back :: Radiant -> Chunk a -> Chunk a
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
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 $ chunk "Blue on 8, red on 256" &
-- fore (blue <> only256 red)
--
only256 :: Radiant -> Radiant
-- | Items that can be rendered. render returns a difference list.
class Renderable a
toByteStringsColors0 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]
toByteStringsColors8 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]
toByteStringsColors256 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]
-- | Spawns a subprocess to read the output of tput colors. 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 any IO exceptions arise during this process, they are discarded and
-- toByteStringsColors0 is returned.
byteStringMakerFromEnvironment :: Renderable a => IO (Chunk a -> [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 :: Renderable a => Handle -> IO (Chunk a -> [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 a -> [ByteString] -> [ByteString]) -> [Chunk a] -> [ByteString]
-- | Writes a Chunk to standard output. Spawns a child process to
-- read the output of tput colors to determine how many colors
-- to use, for every single chunk. Therefore, this is not going to win
-- any speed awards. 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 :: Renderable a => Chunk a -> IO ()
-- | Writes a Chunk to standard output, and appends a newline.
-- Spawns a child process to read the output of tput colors to
-- determine how many colors to use, for every single chunk. Therefore,
-- this is not going to win any speed awards. 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 :: Renderable a => Chunk a -> IO ()