Rainbow

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.

Chunk

data Chunk a

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.

Instances

Functor Chunk

Foldable Chunk

Traversable Chunk

Eq a => Eq (Chunk a)

Ord a => Ord (Chunk a)

Show a => Show (Chunk a)

Generic (Chunk a)

Monoid a => Monoid (Chunk 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.

Typeable (* -> *) Chunk

type Rep (Chunk a)

chunk :: a -> Chunk a

Creates a Chunk with no formatting and with the given text.

Formatting, all terminals

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

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

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

Colors

data Radiant

Stores colors that may affect 8-color terminals, 256-color terminals, both, or neither.

Instances

Eq Radiant

Ord Radiant

Show Radiant

Generic Radiant

Monoid Radiant

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.

Typeable * Radiant

type Rep Radiant

fore :: Radiant -> Chunk a -> Chunk a

Change the foreground color for both 8- and 256-color terminals.

back :: Radiant -> Chunk a -> Chunk a

Change the background color for both 8- and 256-color terminals.

Colors, all terminals

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

black :: Radiant

red :: Radiant

green :: Radiant

yellow :: Radiant

blue :: Radiant

magenta :: Radiant

cyan :: Radiant

white :: Radiant

Colors, 256-color terminals only

These Radiant affect 256-color terminals only.

grey :: Radiant

brightRed :: Radiant

brightGreen :: Radiant

brightYellow :: Radiant

brightBlue :: Radiant

brightMagenta :: Radiant

brightCyan :: Radiant

brightWhite :: Radiant

color256 :: Word8 -> Radiant

only256 :: Radiant -> 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)

Converting Chunk to ByteString

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.

class Renderable a

Items that can be rendered. render returns a difference list.

Minimal complete definition

render

Instances

Renderable String

Strings are converted first to a strict Text and then to a strict ByteString.

Renderable ByteString

Lazy ByteString is converted to strict chunks.

Renderable ByteString

Strict ByteString is left as-is.

Renderable Text

Converts a lazy Text to UTF-8 ByteStrings.

Renderable Text

Converts a strict Text to a UTF-8 ByteString.

toByteStringsColors0 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]

toByteStringsColors8 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]

toByteStringsColors256 :: Renderable a => Chunk a -> [ByteString] -> [ByteString]

byteStringMakerFromEnvironment :: Renderable a => IO (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.

byteStringMakerFromHandle :: Renderable a => Handle -> 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.

chunksToByteStrings

Arguments

:: (Chunk a -> [ByteString] -> [ByteString])

Function that converts Chunk to ByteString. This function, when applied to a Chunk, returns a difference list.

-> [Chunk a]

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

Quick and dirty functions for IO

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.

putChunk :: Renderable a => Chunk a -> IO ()

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.

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

Re-exports

• Control.Lens.Operators re-exports &
• Data.Monoid re-exports Monoid, <> and mempty
• Data.ByteString re-exports ByteString
• Data.Word re-exports Word8

module Control.Lens.Operators

module Data.Word

module Data.ByteString

module Data.Monoid

Notes on terminals

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.

Now, to figure out how many colors the terminal supports, Rainbow simply uses the tput program. This removes the dependency on Terminfo altogether.

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