-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Print text to terminal with colors and effects
--
-- rainbow helps you print Text chunks to a terminal with colors and
-- effects such as bold, underlining, etc. You pair each Text with a
-- description of how it should appear. Rainbow works with both 8-color
-- and 256-color terminals.
--
-- rainbow uses the terminfo package which, in turn, needs the full C
-- library for ncurses installed, including the development headers.
-- Before installing terminfo, you may need to install the ncurses
-- headers (for instance, on Debian systems, install the libncurses5-dev
-- package.)
@package rainbow
@version 0.16.2.0
-- | The innards of Rainbow. Ordinarily you should not need this module;
-- instead, just import Rainbow, which re-exports the most useful
-- names from this module.
module Rainbow.Types
-- | Which terminal definition to use.
data Term
-- | Using this terminal should always succeed. This suppresses all colors.
-- Uesful if output is not going to a TTY, or if you just do not like
-- colors.
Dumb :: Term
-- | Use the terminal with this given name. You might get this from the
-- TERM environment variable, or set it explicitly. A runtime error will
-- result if the terminfo database does not have a definition for this
-- terminal. If this terminal supports 256 colors, then 256 colors are
-- used. If this terminal supports less than 256 colors, but at least 8
-- colors, then 8 colors are used. Otherwise, no colors are used.
TermName :: String -> Term
-- | Gets the terminal definition from the environment. If the environment
-- does not have a TERM veriable, use Dumb.
termFromEnv :: IO Term
-- | Gets the terminal definition from the environment and a handle. If the
-- handle is not a terminal, Dumb is returned. Otherwise, the
-- terminal is obtained from the environment.
--
-- Changed in version 0.12.0.0 - the type of this function was
-- different in previous versions.
smartTermFromEnv :: Handle -> IO Term
type Background8 = Last Color8
type Background256 = Last Color256
type Foreground8 = Last Color8
type Foreground256 = Last Color256
-- | A simple enumeration for eight values.
data Enum8
E0 :: Enum8
E1 :: Enum8
E2 :: Enum8
E3 :: Enum8
E4 :: Enum8
E5 :: Enum8
E6 :: Enum8
E7 :: Enum8
enum8toWord8 :: Enum8 -> Word8
-- | Color for an 8-color terminal. Does not affect 256-color terminals.
newtype Color8
Color8 :: Maybe Enum8 -> Color8
-- | Nothing indicates to use the default color for the terminal;
-- otherwise, use the corresponding Terminfo Color.
unColor8 :: Color8 -> Maybe Enum8
color8toTerminfo :: Color8 -> Maybe Color
-- | Color for an 256-color terminal. Does not affect 8-color terminals.
newtype Color256
Color256 :: Maybe Word8 -> Color256
-- | Nothing indicates to use the default color for the terminal;
-- otherwise, use the corresponding Terminfo Color.
unColor256 :: Color256 -> Maybe Word8
color256toTerminfo :: Color256 -> Maybe Color
-- | Any color for an 8-color terminal can also be used in a 256-color
-- terminal.
to256 :: Color8 -> Color256
-- | Style elements that apply in both 8 and 256 color terminals. However,
-- the elements are described separately for 8 and 256 color terminals,
-- so that the text appearance can change depending on how many colors a
-- terminal has.
data StyleCommon
StyleCommon :: Last Bool -> Last Bool -> Last Bool -> Last Bool -> StyleCommon
scBold :: StyleCommon -> Last Bool
scUnderline :: StyleCommon -> Last Bool
scFlash :: StyleCommon -> Last Bool
scInverse :: StyleCommon -> Last Bool
-- | Describes text appearance (foreground and background colors, as well
-- as other attributes such as bold) for an 8 color terminal.
data Style8
Style8 :: Foreground8 -> Background8 -> StyleCommon -> Style8
foreground8 :: Style8 -> Foreground8
background8 :: Style8 -> Background8
common8 :: Style8 -> StyleCommon
-- | Describes text appearance (foreground and background colors, as well
-- as other attributes such as bold) for a 256 color terminal.
data Style256
Style256 :: Foreground256 -> Background256 -> StyleCommon -> Style256
foreground256 :: Style256 -> Foreground256
background256 :: Style256 -> Background256
common256 :: Style256 -> StyleCommon
-- | The TextSpec bundles together the styles for the 8 and 256 color
-- terminals, so that the text can be portrayed on any terminal.
data TextSpec
TextSpec :: Style8 -> Style256 -> TextSpec
style8 :: TextSpec -> Style8
style256 :: TextSpec -> Style256
-- | 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.
--
-- The text is held as a list of strict Text.
data Chunk
Chunk :: TextSpec -> [Text] -> Chunk
textSpec :: Chunk -> TextSpec
text :: Chunk -> [Text]
-- | Creates a Chunk from a strict Text with default colors
-- and no special effects.
fromText :: Text -> Chunk
-- | Creates a Chunk from a lazy Text with default colors and
-- no special effects.
fromLazyText :: Text -> Chunk
defaultColors :: Terminal -> TermOutput
commonAttrs :: Terminal -> StyleCommon -> TermOutput
-- | Gets the right set of terminal codes to apply the desired
-- highlighting, bold, underlining, etc. Be sure to apply the attributes
-- first (bold, underlining, etc) and then the colors. Setting the colors
-- first and then the attributes seems to reset the colors, giving blank
-- output.
getTermCodes :: Terminal -> TextSpec -> TermOutput
hPrintChunk :: Handle -> Terminal -> Chunk -> IO ()
-- | Sends a list of chunks to the given handle for printing. Sets up the
-- terminal (this only needs to be done once.) Lazily processes the list
-- of Chunk. See putChunks for notes on how many colors are used.
hPutChunks :: Handle -> Term -> [Chunk] -> IO ()
-- | Sends a list of chunks to standard output for printing. Sets up the
-- terminal (this only needs to be done once.) Lazily processes the list
-- of Chunk.
--
-- Which colors are used depends upon the Term. If it is
-- Dumb, then no colors are used on output. If the Term is
-- specified with TermName, the UNIX terminfo library is used to
-- determine how many colors the terminal supports. If it supports at
-- least 256 colors, then 256 colors are used. If it supports at least 8
-- colors but less than 256 colors, then 256 colors are used. Otherwise,
-- no colors are used. A runtime error will occur if the TermName
-- is not found in the system terminal database.
putChunks :: Term -> [Chunk] -> IO ()
-- | Print one chunk at a time, to a handle
hPutChunk :: Handle -> Chunk -> IO ()
-- | Print one chunk at a time, to standard output
putChunk :: Chunk -> IO ()
-- | Print one chunk at a time, to a handle, append a newline
hPutChunkLn :: Handle -> Chunk -> IO ()
-- | Print one chunk at a time, to standard output, append a newline
putChunkLn :: Chunk -> IO ()
bold8 :: Chunk
bold8off :: Chunk
underline8 :: Chunk
underline8off :: Chunk
flash8 :: Chunk
flash8off :: Chunk
inverse8 :: Chunk
inverse8off :: Chunk
underline256 :: Chunk
underline256off :: Chunk
bold256 :: Chunk
bold256off :: Chunk
inverse256 :: Chunk
inverse256off :: Chunk
flash256 :: Chunk
flash256off :: 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
boldOff :: Chunk
inverse :: Chunk
inverseOff :: Chunk
flash :: Chunk
flashOff :: Chunk
underline :: Chunk
underlineOff :: Chunk
instance Eq Term
instance Show Term
instance Eq Enum8
instance Ord Enum8
instance Show Enum8
instance Bounded Enum8
instance Enum Enum8
instance Eq Color8
instance Ord Color8
instance Show Color8
instance Eq Color256
instance Ord Color256
instance Show Color256
instance Show StyleCommon
instance Eq StyleCommon
instance Ord StyleCommon
instance Show Style8
instance Eq Style8
instance Ord Style8
instance Show Style256
instance Eq Style256
instance Ord Style256
instance Show TextSpec
instance Eq TextSpec
instance Ord TextSpec
instance Eq Chunk
instance Show Chunk
instance Ord Chunk
instance Monoid Chunk
instance IsString Chunk
instance Monoid TextSpec
instance Monoid Style256
instance Monoid Style8
instance Monoid StyleCommon
-- | Ordinarily you should not need this module; typically you will just
-- import Rainbow, which re-exports the most useful things from
-- this module. This module also contains data constructors that
-- Rainbow does not re-export.
module Rainbow.Colors
-- | Resets the color (foreground or background, as appropriate) to the
-- default for your terminal. Usually you will not need this, as each
-- Chunk starts out with the terminal's default colors.
noColor8 :: Color8
black8 :: Color8
red8 :: Color8
green8 :: Color8
yellow8 :: Color8
blue8 :: Color8
magenta8 :: Color8
cyan8 :: Color8
white8 :: Color8
-- | Resets the color (foreground or background, as appropriate) to the
-- default for your terminal. Usually you will not need this, as each
-- Chunk starts out with the terminal's default colors.
noColor256 :: Color256
grey :: Color256
brightRed :: Color256
brightGreen :: Color256
brightYellow :: Color256
brightBlue :: Color256
brightMagenta :: Color256
brightCyan :: Color256
brightWhite :: Color256
-- | Things of type Both affect both 8- and 256-color terminals.
-- (They do not affect both the foreground and background.)
newtype Both
Both :: Color8 -> Both
both :: Color8 -> Both
black :: Both
red :: Both
green :: Both
yellow :: Both
blue :: Both
magenta :: Both
cyan :: Both
white :: Both
-- | Changing colors. Instances of this class affect the background or the
-- foreground color. For example, to get a Chunk that changes the
-- background to red, use back red; for the
-- foreground, use fore red. Whether 8-color or
-- 256-color terminals (or both) are affected depends on the particular
-- instance.
--
-- Because Word8 is an instance of Color, you can use
-- literals to affect the color of 256-color terminals. For example, if
-- you have a 256 color terminal:
--
--
-- putChunkLn $ "muddy yellow background" <> back (100 :: Word8)
--
--
-- This example would not affect an 8-color terminal, as the Word8
-- instance affects 256-color terminals only.
class Color a
back :: Color a => a -> Chunk
fore :: Color a => a -> Chunk
instance Eq Both
instance Ord Both
instance Show Both
instance Color Word8
instance Color Enum8
instance Color Both
instance Color Color256
instance Color Color8
-- | Handles colors and special effects for text. Internally this module
-- uses the Haskell terminfo library, which links against the UNIX
-- library of the same name, so it should work with a wide variety of
-- UNIX terminals.
--
-- The building block of Rainbow is the Chunk. Each Chunk
-- comes with a TextSpec, which specifies how the text should look
-- on 8-color and on 256-color terminals. The Chunk is a full
-- specification; that is, although Chunks are typically printed
-- one after the other, the appearance of one Chunk does not
-- affect the appearance of the next Chunk.
--
-- 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.
--
-- A Chunk is a Monoid, so you can combine them using the
-- usual monoid functions, including <>. You can create a
-- Chunk with text using fromString, but this library is
-- much more usable if you enable the OverloadedStrings GHC extension:
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
--
-- and all future examples assume you have enabled OverloadedStrings. You
-- will also want the Monoid module in scope:
--
--
-- import Data.Monoid
--
--
-- Here are some basic examples:
--
--
-- putChunkLn $ Some blue text fore blue
-- putChunkLn $ Blue on red background
-- fore blue back red
-- putChunkLn $ Blue on red, foreground bold
-- fore blue back red bold
--
--
-- But what makes Rainbow a little more interesting is that 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 $ Blue on 8-color terminal, red on 256-color terminal
-- fore blue8 back (to256 red)
--
--
-- To get a Color256, which affects only 256-color terminals,
-- there are some definitions in the module such as brightRed. You
-- may also use Word8 literals, like this. You need to specify
-- the type as it can't be inferred:
--
--
-- import Data.Word (Word8)
-- putChunkLn $ Pink on 256-color terminal only
-- (201 :: Word8)
--
--
-- If mappend multiple chunks that change the same property, the
-- rightmost one "wins":
--
--
-- putChunkLn $ This will be blue red blue
--
--
-- This property comes in handy if you want to specify a default color
-- for 8- and 256-color terminals, then a more specific shade for a
-- 256-color terminal:
--
--
-- putChunkLn $ Red on 8-color, pink on 256-color
-- red (201 :: Word8)
--
--
-- However, if you use mappend to add additional Chunks
-- that have text, the text will be appended:
--
--
-- putChunkLn $ green You will see this text
-- and this text too, but it will all be blue
-- blue
--
--
-- Although one chunk can have different colors on 8- and 256-color
-- terminals, it cannot have different colors on the same terminal. That
-- is, if you want to print some text in one color and some text in
-- another color, make two chunks.
module Rainbow
-- | Which terminal definition to use.
data Term
-- | Using this terminal should always succeed. This suppresses all colors.
-- Uesful if output is not going to a TTY, or if you just do not like
-- colors.
Dumb :: Term
-- | Use the terminal with this given name. You might get this from the
-- TERM environment variable, or set it explicitly. A runtime error will
-- result if the terminfo database does not have a definition for this
-- terminal. If this terminal supports 256 colors, then 256 colors are
-- used. If this terminal supports less than 256 colors, but at least 8
-- colors, then 8 colors are used. Otherwise, no colors are used.
TermName :: String -> Term
-- | Gets the terminal definition from the environment. If the environment
-- does not have a TERM veriable, use Dumb.
termFromEnv :: IO Term
-- | Gets the terminal definition from the environment and a handle. If the
-- handle is not a terminal, Dumb is returned. Otherwise, the
-- terminal is obtained from the environment.
--
-- Changed in version 0.12.0.0 - the type of this function was
-- different in previous versions.
smartTermFromEnv :: Handle -> IO Term
-- | 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.
--
-- The text is held as a list of strict Text.
data Chunk
Chunk :: TextSpec -> [Text] -> Chunk
textSpec :: Chunk -> TextSpec
text :: Chunk -> [Text]
-- | Creates a Chunk from a strict Text with default colors
-- and no special effects.
fromText :: Text -> Chunk
-- | Creates a Chunk from a lazy Text with default colors and
-- no special effects.
fromLazyText :: Text -> Chunk
-- | Sends a list of chunks to standard output for printing. Sets up the
-- terminal (this only needs to be done once.) Lazily processes the list
-- of Chunk.
--
-- Which colors are used depends upon the Term. If it is
-- Dumb, then no colors are used on output. If the Term is
-- specified with TermName, the UNIX terminfo library is used to
-- determine how many colors the terminal supports. If it supports at
-- least 256 colors, then 256 colors are used. If it supports at least 8
-- colors but less than 256 colors, then 256 colors are used. Otherwise,
-- no colors are used. A runtime error will occur if the TermName
-- is not found in the system terminal database.
putChunks :: Term -> [Chunk] -> IO ()
-- | Sends a list of chunks to the given handle for printing. Sets up the
-- terminal (this only needs to be done once.) Lazily processes the list
-- of Chunk. See putChunks for notes on how many colors are used.
hPutChunks :: Handle -> Term -> [Chunk] -> IO ()
-- | Print one chunk at a time, to standard output
putChunk :: Chunk -> IO ()
-- | Print one chunk at a time, to standard output, append a newline
putChunkLn :: Chunk -> IO ()
-- | Print one chunk at a time, to a handle
hPutChunk :: Handle -> Chunk -> IO ()
-- | Print one chunk at a time, to a handle, append a newline
hPutChunkLn :: Handle -> Chunk -> IO ()
-- | 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
boldOff :: Chunk
underline :: Chunk
underlineOff :: Chunk
flash :: Chunk
flashOff :: Chunk
inverse :: Chunk
inverseOff :: Chunk
bold8 :: Chunk
bold8off :: Chunk
underline8 :: Chunk
underline8off :: Chunk
flash8 :: Chunk
flash8off :: Chunk
inverse8 :: Chunk
inverse8off :: Chunk
bold256 :: Chunk
bold256off :: Chunk
underline256 :: Chunk
underline256off :: Chunk
flash256 :: Chunk
flash256off :: Chunk
inverse256 :: Chunk
inverse256off :: Chunk
-- | Changing colors. Instances of this class affect the background or the
-- foreground color. For example, to get a Chunk that changes the
-- background to red, use back red; for the
-- foreground, use fore red. Whether 8-color or
-- 256-color terminals (or both) are affected depends on the particular
-- instance.
--
-- Because Word8 is an instance of Color, you can use
-- literals to affect the color of 256-color terminals. For example, if
-- you have a 256 color terminal:
--
--
-- putChunkLn $ "muddy yellow background" <> back (100 :: Word8)
--
--
-- This example would not affect an 8-color terminal, as the Word8
-- instance affects 256-color terminals only.
class Color a
back :: Color a => a -> Chunk
fore :: Color a => a -> Chunk
-- | Things of type Both affect both 8- and 256-color terminals.
-- (They do not affect both the foreground and background.)
data Both
black :: Both
red :: Both
green :: Both
yellow :: Both
blue :: Both
magenta :: Both
cyan :: Both
white :: Both
-- | A simple enumeration for eight values.
data Enum8
E0 :: Enum8
E1 :: Enum8
E2 :: Enum8
E3 :: Enum8
E4 :: Enum8
E5 :: Enum8
E6 :: Enum8
E7 :: Enum8
-- | Color for an 8-color terminal. Does not affect 256-color terminals.
newtype Color8
Color8 :: Maybe Enum8 -> Color8
-- | Nothing indicates to use the default color for the terminal;
-- otherwise, use the corresponding Terminfo Color.
unColor8 :: Color8 -> Maybe Enum8
-- | Resets the color (foreground or background, as appropriate) to the
-- default for your terminal. Usually you will not need this, as each
-- Chunk starts out with the terminal's default colors.
noColor8 :: Color8
black8 :: Color8
red8 :: Color8
green8 :: Color8
yellow8 :: Color8
blue8 :: Color8
magenta8 :: Color8
cyan8 :: Color8
white8 :: Color8
-- | Color for an 256-color terminal. Does not affect 8-color terminals.
newtype Color256
Color256 :: Maybe Word8 -> Color256
-- | Nothing indicates to use the default color for the terminal;
-- otherwise, use the corresponding Terminfo Color.
unColor256 :: Color256 -> Maybe Word8
-- | Resets the color (foreground or background, as appropriate) to the
-- default for your terminal. Usually you will not need this, as each
-- Chunk starts out with the terminal's default colors.
noColor256 :: Color256
grey :: Color256
brightRed :: Color256
brightGreen :: Color256
brightYellow :: Color256
brightBlue :: Color256
brightMagenta :: Color256
brightCyan :: Color256
brightWhite :: Color256
-- | Any color for an 8-color terminal can also be used in a 256-color
-- terminal.
to256 :: Color8 -> Color256