Rainbox.Box

Working with Box.

A Box is a rectangular block of text. You can paste Box together to create new rectangles, and you can grow or reduce existing Box to create new Boxes.

There are only six primitive functions that make a Box:

• blank - formats a blank box with nothing but a (possibly) colorful background. Useful to paste to other Box to provide white space.
• chunks - Makes a box out of Rainbow Chunk.
• catH - paste Box together horizontally
• catV - paste Box together vertically
• viewH - view a Box, keeping the same height but possibly trimming the width
• viewV - view a Box, keeping the same width but possibly trimming the height

The other functions use these building blocks to do other useful things.

There are many crude diagrams in the Haddock documentation. A dash means a character with data; a period means a blank character. When you print your Box, the blank characters will have the appropriate background color.

Backgrounds

data Background

Background colors to use when inserting necessary padding.

Constructors

Background

Fields

boxBackground8 :: Color8

boxBackground256 :: Color256

Instances

Eq Background

Show Background

defaultBackground :: Background

Use the default background colors of the current terminal.

backgroundFromChunk :: Chunk -> Background

backgroundToTextSpec :: Background -> TextSpec

same :: Color8 -> Background

Use the same color for 8 and 256-color backgrounds.

Height and columns

newtype Height

A count of rows

Constructors

Height

Fields

unHeight :: Int

Instances

Eq Height

Ord Height

Show Height

height :: Box -> Int

How many Rod are in this Box?

newtype Width

A count of columns

Constructors

Width

Fields

unWidth :: Int

Instances

Eq Width

Ord Width

Show Width

class HasWidth a where

How many columns are in this thing? A column is one character wide. Every Bar in a Box always has the same number of columns.

This is for things that have a single, solitary width, not things like columns that might have different widths at different points.

Methods

width :: a -> Int

Instances

HasWidth Chunk

HasWidth BoxP

HasWidth Rod

HasWidth Box

HasWidth Bar

HasWidth Nibble

HasWidth Spaces

Alignment

data Align a

Alignment.

Instances

Eq a => Eq (Align a)

Show a => Show (Align a)

data Vert

Vertical alignment.

Instances

Eq Vert

Show Vert

data Horiz

Horizontal alignment.

Instances

Eq Horiz

Show Horiz

center :: Align a

top :: Align Vert

bottom :: Align Vert

left :: Align Horiz

right :: Align Horiz

Box properties

newtype Bar

Occupies a single row on screen. The Chunk you place in a Bar should not have any control characters such as newlines or tabs, as rainbox assumes that each character in a Bar takes up one screen column and that each character does not create newlines. Leave newline handling up to rainbox. However, rainbox will not check to make sure that your inputs do not contain newlines, tabs, or other spurious characters. Similarly, use of combining characters will create unexpected results, as Rainbox will see something that takes up (for instance) two characters and think it takes up two screen columns, when in reality it will take up only one screen column. So, if you need accented characters, use a single Unicode code point, not two code points. For example, for é, use U+00E9, not U+0065 and U+0301.

Constructors

Bar

Fields

unBar :: [Chunk]

Instances

Eq Bar

Show Bar

IsString Bar

Monoid Bar

HasWidth Bar

barToBox :: Bar -> Box

barsToBox :: Background -> Align Horiz -> [Bar] -> Box

data Box

A Box has a width in columns and a height in rows. Its height and width both are always at least zero. It can have positive height even if its width is zero, and it can have positive width even if its height is zero.

Each row in a Box always has the same number of characters; a Box with zero height has no characters but still has a certain width.

Instances

Eq Box

Show Box

IsString Box

HasWidth Box

unBox :: Box -> BoxP

Making Boxes

blank :: Background -> Height -> Width -> Box

A blank Box. Useful for aligning other Box.

blankH :: Background -> Int -> Box

A blank horizontal box with a given width and no height.

blankV :: Background -> Int -> Box

A blank vertical box with a given length.

chunks :: [Chunk] -> Box

A Box made of Chunk. Always one Bar tall, and has as many columns as there are characters in the Chunk.

chunk :: Chunk -> Box

A Box made of a single Chunk.

Pasting Boxes together

catH :: Background -> Align Vert -> [Box] -> Box

Merge several Box horizontally into one Box. That is, with alignment set to ATop:

 --- ------- ----
 --- -------
 ---

becomes

 --------------
 ----------....
 ---...........

With alignment set to ABottom, becomes

 ---...........
 ----------....
 --------------

catV :: Background -> Align Horiz -> [Box] -> Box

Merge several Box vertically into one Box. That is, with alignment set to left:

 -------
 -------

 ---
 ---

 ----
 ----

becomes

 -------
 -------
 ---....
 ---....
 ---....
 ----...
 ----...

With alignment set to right, becomes

 -------
 -------
 ....---
 ....---
 ...----
 ...----

sepH :: Background -> Int -> Align Vert -> [Box] -> Box

sepH sep a bs lays out bs horizontally with alignment a, with sep amount of space in between each.

sepV :: Background -> Int -> Align Horiz -> [Box] -> Box

sepV sep a bs lays out bs vertically with alignment a, with sep amount of space in between each.

punctuateH :: Background -> Align Vert -> Box -> [Box] -> Box

punctuateH a p bs horizontally lays out the boxes bs with a copy of p interspersed between each.

punctuateV :: Background -> Align Horiz -> Box -> [Box] -> Box

A vertical version of punctuateH.

Viewing Boxes

view :: Height -> Width -> Align Vert -> Align Horiz -> Box -> Box

viewH :: Int -> Align Horiz -> Box -> Box

viewV :: Int -> Align Vert -> Box -> Box

View a Box, possibly shrinking it. You set the size of your viewport and how it is oriented relative to the Box as a whole. The Box returned may be smaller than the argument Box, but it will never be bigger.

Examples:

>>> :set -XOverloadedStrings
>>> let box = catV defaultBackground top [ "ab", "cd" ]
>>> printBox . view (Height 1) (Width 1) left top $ box
a

>>> printBox . view (Height 1) (Width 1) right bottom $ box
d

Growing Boxes

grow :: Background -> Height -> Width -> Align Vert -> Align Horiz -> Box -> Box

Grow a box. Each dimension of the result Box is never smaller than the corresponding dimension of the input Box. Analogous to view, so you give the resulting dimensions that you want. The alignment is analogous to view; for instance, if you specify that the alignment is top and left, the extra padding is added to the right and bottom sides of the resulting Box.

growH

Arguments

:: Background

-> Int

Resulting width

-> Align Horiz

-> Box

-> Box

Grow a Box horizontally.

growV

Arguments

:: Background

-> Int

Resulting height

-> Align Vert

-> Box

-> Box

Grow a Box vertically.

column :: Background -> Align Horiz -> [Box] -> [Box]

Returns a list of Box, each being exactly as wide as the widest Box in the input list.

Resizing

resize :: Background -> Height -> Width -> Align Vert -> Align Horiz -> Box -> Box

Resize a Box. Will grow or trim it as necessary in order to reach the resulting size. Returns an empty Box if either Height or Width is less than 1.

resizeH

Arguments

:: Background

-> Int

Resulting width

-> Align Horiz

-> Box

-> Box

Resize horizontally.

resizeV

Arguments

:: Background

-> Int

Resulting height

-> Align Vert

-> Box

-> Box

Resize vertically.

Printing Boxes

render :: Box -> [Chunk]

Convert a Box to Rainbow Chunks. You can then print it using putChunks or the like.

printBox :: Box -> IO ()

Prints a Box to standard output. If standard output is not a terminal, no colors are used. Otherwise, colors are used if your TERM environment variable suggests they are available.