System.Console.Rainbow

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.

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 Chunks 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.

Terminal definitions

data Term

Which terminal definition to use.

Constructors

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.

Instances

Eq Term

Show Term

termFromEnv :: IO Term

Gets the terminal definition from the environment. If the environment does not have a TERM veriable, use Dumb.

smartTermFromEnv

Arguments

:: Handle

Check this handle to see if it is a terminal (typically you will use stdout).

-> 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.

Chunks

data Chunk

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.

Constructors

Chunk

Fields

textSpec :: TextSpec

text :: [Text]

Instances

Eq Chunk

Ord Chunk

Show Chunk

IsString Chunk

Monoid Chunk

fromText :: Text -> Chunk

Creates a Chunk from a strict Text with default colors and no special effects.

fromLazyText :: Text -> Chunk

Creates a Chunk from a lazy Text with default colors and no special effects.

Printing chunks

putChunks :: 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.

hPutChunks :: Handle -> 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.

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.

putChunk :: Chunk -> IO ()

Print one chunk at a time, to standard output

putChunkLn :: Chunk -> IO ()

Print one chunk at a time, to standard output, append a newline

hPutChunk :: Handle -> Chunk -> IO ()

Print one chunk at a time, to a handle

hPutChunkLn :: Handle -> Chunk -> IO ()

Print one chunk at a time, to a handle, append a newline

Effects for both 8 and 256 color terminals

These Chunks affect both 8 and 256 color terminals:

 putChunkLn $ "bold on 8 and 256 color terminals" <> bold

There are also Chunks 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 Chunks are here if you need them.

bold :: 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.

boldOff :: Chunk

underline :: Chunk

underlineOff :: Chunk

flash :: Chunk

flashOff :: Chunk

inverse :: Chunk

inverseOff :: Chunk

Effects for 8-color terminals only

These Chunks affect 8-color terminals only.

 putChunkLn $ "Bold on 8 color terminal only" <> bold8

bold8 :: Chunk

bold8off :: Chunk

underline8 :: Chunk

underline8off :: Chunk

flash8 :: Chunk

flash8off :: Chunk

inverse8 :: Chunk

inverse8off :: Chunk

Effects for 256-color terminals only

These Chunks affect 256-color terminals only.

 putChunkLn $ "Underlined on 256-color terminal, "
              <> "bold on 8-color terminal"
              <> underlined256 <> bold8

bold256 :: Chunk

bold256off :: Chunk

underline256 :: Chunk

underline256off :: Chunk

flash256 :: Chunk

flash256off :: Chunk

inverse256 :: Chunk

inverse256off :: Chunk

Color chunks

All colors are within this module.

module System.Console.Rainbow.ColorChunks