Safe Haskell | None |
---|
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 Chunk
s 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.
Here are some basic examples:
putChunkLn $ "Some blue text" <> f_blue putChunkLn $ "Blue on red background" <> f_blue <> b_red putChunkLn $ "Blue on red, foreground bold" <> f_blue <> b_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" <> c8_f_blue <> c256_f_red
If mappend
multiple chunks that change the same property, the
rightmost one "wins":
putChunkLn $ "This will be blue" <> f_red <> f_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 $ "Pink" <> f_red <> c256_f_201
However, if you use mappend
to add additional Chunk
s that have
text, the text will be appended:
putChunkLn $ f_green <> "You will see this text " <> "and this text too, but it will all be blue" <> f_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.
- data Term
- termFromEnv :: IO Term
- smartTermFromEnv :: Handle -> IO Term
- data Chunk = Chunk {}
- fromText :: Text -> Chunk
- fromLazyText :: Text -> Chunk
- putChunks :: Term -> [Chunk] -> IO ()
- hPutChunks :: Handle -> Term -> [Chunk] -> IO ()
- putChunk :: Chunk -> IO ()
- putChunkLn :: Chunk -> IO ()
- hPutChunk :: Handle -> Chunk -> IO ()
- hPutChunkLn :: Handle -> Chunk -> IO ()
- 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
- module System.Console.Rainbow.ColorChunks
Terminal definitions
Which terminal definition to use.
Dumb | 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. |
TermName String | 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. |
Gets the terminal definition from the environment. If the
environment does not have a TERM veriable, use Dumb
.
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.
Chunks
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
.
fromLazyText :: Text -> ChunkSource
Printing chunks
putChunks :: Term -> [Chunk] -> IO ()Source
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.
hPutChunks :: Handle -> Term -> [Chunk] -> IO ()Source
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.
Printing one chunk at a time
These functions make it easy to print one chunk at a time. Each function initializes the terminal once for each chunk, unlike the list-oriented functions, which only initialize the terminal once. (Initialization does not clear the screen; rather, it is a process that the terminfo library requires.) Thus there might be a performance penalty for using these functions to print large numbers of chunks. Or, there might not be--I have not benchmarked them.
These functions use the default terminal, obtained using
termFromEnv
.
putChunkLn :: Chunk -> IO ()Source
Print one chunk at a time, to standard output, append a newline
hPutChunkLn :: Handle -> Chunk -> IO ()Source
Print one chunk at a time, to a handle, append a newline
Effects for both 8 and 256 color terminals
These Chunk
s affect both 8 and 256 color terminals:
putChunkLn $ "bold on 8 and 256 color terminals" <> bold
There are also Chunk
s to turn an effect off, such as
boldOff
. Ordinarily you will not need these because each chunk
starts with no effects, so you only need to turn on the effects
you want. However the off
Chunk
s are here if you need them.
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.
Effects for 8-color terminals only
These Chunk
s affect 8-color terminals only.
putChunkLn $ "Bold on 8 color terminal only" <> bold8
Effects for 256-color terminals only
These Chunk
s affect 256-color terminals only.
putChunkLn $ "Underlined on 256-color terminal, " <> "bold on 8-color terminal" <> underlined256 <> bold8
Color chunks
All colors are within this module.