Safe Haskell | None |
---|---|
Language | Haskell2010 |
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 Chunk
s. 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.
- data Chunk a
- chunk :: a -> Chunk a
- bold :: Chunk a -> Chunk a
- 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
- data Radiant
- fore :: Radiant -> Chunk a -> Chunk a
- back :: Radiant -> Chunk a -> Chunk a
- black :: Radiant
- red :: Radiant
- green :: Radiant
- yellow :: Radiant
- blue :: Radiant
- magenta :: Radiant
- cyan :: Radiant
- white :: Radiant
- grey :: Radiant
- brightRed :: Radiant
- brightGreen :: Radiant
- brightYellow :: Radiant
- brightBlue :: Radiant
- brightMagenta :: Radiant
- brightCyan :: Radiant
- brightWhite :: Radiant
- color256 :: Word8 -> Radiant
- only256 :: Radiant -> Radiant
- class Renderable a
- 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])
- byteStringMakerFromHandle :: Renderable a => Handle -> IO (Chunk a -> [ByteString] -> [ByteString])
- chunksToByteStrings :: (Chunk a -> [ByteString] -> [ByteString]) -> [Chunk a] -> [ByteString]
- putChunk :: Renderable a => Chunk a -> IO ()
- putChunkLn :: Renderable a => Chunk a -> IO ()
- module Control.Lens.Operators
- module Data.Word
- module Data.ByteString
- module Data.Monoid
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.
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 |
Typeable (* -> *) Chunk | |
type Rep (Chunk a) |
Formatting, all terminals
These combinators affect the way a Chunk
is displayed on
both 8- and 256-color terminals.
bold :: Chunk a -> Chunk a Source
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.
Colors
Stores colors that may affect 8-color terminals, 256-color terminals, both, or neither.
Eq Radiant | |
Ord Radiant | |
Show Radiant | |
Generic Radiant | |
Monoid Radiant | Uses the underlying |
Typeable * Radiant | |
type Rep Radiant |
fore :: Radiant -> Chunk a -> Chunk a Source
Change the foreground color for both 8- and 256-color terminals.
back :: Radiant -> Chunk a -> Chunk a Source
Change the background color for both 8- and 256-color terminals.
Colors, all terminals
Colors, 256-color terminals only
These Radiant
affect 256-color terminals only.
Converting Chunk
to ByteString
To print a Chunk
, you need to convert it to some
ByteString
s.
All these functions convert the Text
to UTF-8
ByteString
s. 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 Source
Items that can be rendered. render
returns a difference list.
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] Source
toByteStringsColors8 :: Renderable a => Chunk a -> [ByteString] -> [ByteString] Source
toByteStringsColors256 :: Renderable a => Chunk a -> [ByteString] -> [ByteString] Source
byteStringMakerFromEnvironment :: Renderable a => IO (Chunk a -> [ByteString] -> [ByteString]) Source
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]) Source
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.
:: (Chunk a -> [ByteString] -> [ByteString]) | Function that converts |
-> [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 () Source
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 Chunk
s if
you are printing a lot of them.
putChunkLn :: Renderable a => Chunk a -> IO () Source
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 Chunk
s if you are printing a lot
of them.
Re-exports
- Control.Lens.Operators re-exports
&
- Data.Monoid re-exports
Monoid
,<>
andmempty
- 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.