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.

These combinators affect the way a Chunk is displayed on both 8- and 256-color terminals.

These Radiant affect the way a Chunk is displayed on both 8- and 256-color terminals.

These Radiant affect 256-color terminals only.

To print a Chunk, you need to convert it to some ByteStrings.

All these functions convert the Text to UTF-8 ByteStrings. Many of these functions return a difference list. Learn You a Haskell for Great Good has a great explanation of difference lists:

http://learnyouahaskell.com/for-a-few-monads-more

If you don't want to learn about difference lists, just stick with using chunksToByteStrings and use byteStringMakerFromEnvironment if you want to use the highest number of colors possible, or, to manually specify the number of colors, use chunksToByteStrings with toByteStringsColors0, toByteStringsColors8, or toByteStringsColors256 as the first argument. chunksToByteStrings has an example.

For output to handles or to standard output, just use hPutChunks or putChunks.

For efficiency reasons you probably don't want to use these when printing large numbers of Chunk, but they are handy for throwaway uses like experimenting in GHCi.

Earlier versions of Rainbow used the Haskell terminfo library for dealing with the terminal. Terminfo is available at

https://hackage.haskell.org/package/terminfo

Terminfo, in turn, uses the UNIX terminfo library. The biggest advantage of using Terminfo is that it is compatible with a huge variety of terminals. Many of these terminals are hardware models that are gathering dust in an IBM warehouse somewhere, but even modern software terminals might have quirks. Terminfo covers all those.

The disadvantage is that using Terminfo requires you to perform IO whenever you need to format output for the terminal. Your only choice when using Terminfo is to send output directly to the terminal, or to a handle. This goes against typical Haskell practice, where we try to write pure code whenever possible.

Perhaps surprisingly, there are times where you may want to format output, but not immediately send it to the terminal. Maybe you want to send it to a file instead, or maybe you want to use a Haskell library like Pipes and stream it somewhere. Terminfo is a binding to a Unix library that is not designed for this sort of thing. The closest you could get using Terminfo would be to make a Handle that is backed by a in-memory buffer. There is a package for that sort of thing:

http://hackage.haskell.org/package/knob

but it seems like a nasty workaround. Or you can hijack stdout and send that somewhere--again, nasty workaround.

So I decided to stop using Terminfo. That means Rainbow no longer supports a menagerie of bizarre terminals. It instead just uses the standard ISO 6429 / ECMA 48 terminal codes. These are the same codes that are used by xterm, the OS X Terminal, the Linux console, or any other reasonably modern software terminal. Realistically they are the only terminals Rainbow would be used for.

The 256 color capability is not in ISO 6429, but it is widely supported.

Probably the most common so-called terminals in use today that do NOT support the ISO 6429 codes are those that are not really terminals. For instance, you might use an Emacs shell buffer. For those situations just use toByteStringsColors0.

I also decided to standardize on UTF-8 for the Text output. These days that seems reasonable.

Apparently it's difficult to get ISO 6429 support on Microsoft Windows. Oh well.