Text.PrettyPrint.Boxes

boxes-0.1.4: 2D text pretty-printing library

Copyright | (c) Brent Yorgey 2009
License | BSD-style (see LICENSE)
Maintainer | byorgey@cis.upenn.edu
Stability | experimental
Portability | portable
Safe Haskell | Safe
Language | Haskell98

Text.PrettyPrint.Boxes

Contents

- Constructing boxes
- Layout of boxes
- Alignment
- Inspecting boxes
- Rendering boxes

Description

A pretty-printing library for laying out text in two dimensions, using a simple box model.

Synopsis

- data Box
- nullBox :: Box
- emptyBox :: Int -> Int -> Box
- char :: Char -> Box
- text :: String -> Box
- para :: Alignment -> Int -> String -> Box
- columns :: Alignment -> Int -> Int -> String -> [Box]
- (<>) :: Box -> Box -> Box
- (<+>) :: Box -> Box -> Box
- hcat :: Alignment -> [Box] -> Box
- hsep :: Int -> Alignment -> [Box] -> Box
- (//) :: Box -> Box -> Box
- (/+/) :: Box -> Box -> Box
- vcat :: Alignment -> [Box] -> Box
- vsep :: Int -> Alignment -> [Box] -> Box
- punctuateH :: Alignment -> Box -> [Box] -> Box
- punctuateV :: Alignment -> Box -> [Box] -> Box
- data Alignment
- left :: Alignment
- right :: Alignment
- top :: Alignment
- bottom :: Alignment
- center1 :: Alignment
- center2 :: Alignment
- moveLeft :: Int -> Box -> Box
- moveRight :: Int -> Box -> Box
- moveUp :: Int -> Box -> Box
- moveDown :: Int -> Box -> Box
- alignHoriz :: Alignment -> Int -> Box -> Box
- alignVert :: Alignment -> Int -> Box -> Box
- align :: Alignment -> Alignment -> Int -> Int -> Box -> Box
- rows :: Box -> Int
- cols :: Box -> Int
- render :: Box -> String
- printBox :: Box -> IO ()

# Constructing boxes

data Box

The basic data type. A box has a specified size and some sort of contents.

Instances

Show Box |
IsString Box | Convenient ability to use bare string literals as boxes.

nullBox :: Box

The null box, which has no content and no size. It is quite useless.

emptyBox :: Int -> Int -> Box

`emptyBox r c` is an empty box with `r` rows and `c` columns. Useful for effecting more fine-grained positioning of other boxes, by inserting empty boxes of the desired size in between them.

char :: Char -> Box

A `1x1` box containing a single character.

text :: String -> Box

A (`1 x len`) box containing a string of length `len`.

para :: Alignment -> Int -> String -> Box

`para algn w t` is a box of width `w`, containing text `t`, aligned according to `algn`, flowed to fit within the given width.

columns :: Alignment -> Int -> Int -> String -> [Box]

`columns w h t` is a list of boxes, each of width `w` and height at most `h`, containing text `t` flowed into as many columns as necessary.

# Layout of boxes

(<>) :: Box -> Box -> Box

Paste two boxes together horizontally, using a default (top) alignment.

(<+>) :: Box -> Box -> Box

Paste two boxes together horizontally with a single intervening column of space, using a default (top) alignment.

hcat :: Alignment -> [Box] -> Box

Glue a list of boxes together horizontally, with the given alignment.

hsep :: Int -> Alignment -> [Box] -> Box

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

(//) :: Box -> Box -> Box

Paste two boxes together vertically, using a default (left) alignment.

(/+/) :: Box -> Box -> Box

Paste two boxes together vertically with a single intervening row of space, using a default (left) alignment.

vcat :: Alignment -> [Box] -> Box

Glue a list of boxes together vertically, with the given alignment.

vsep :: Int -> Alignment -> [Box] -> Box

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

punctuateH :: Alignment -> Box -> [Box] -> Box

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

punctuateV :: Alignment -> Box -> [Box] -> Box

A vertical version of `punctuateH`.

# Alignment

data Alignment

Data type for specifying the alignment of boxes.

Instances

Eq Alignment |
Read Alignment |
Show Alignment |

left :: Alignment

Align boxes to the left.

right :: Alignment

Align boxes to the right.

top :: Alignment

Align boxes along their tops.

bottom :: Alignment

Align boxes along their bottoms.

center1 :: Alignment

Align boxes centered, but biased to the left/top in case of unequal parities.

center2 :: Alignment

Align boxes centered, but biased to the right/bottom in case of unequal parities.

moveLeft :: Int -> Box -> Box

Move a box left by putting it in a larger box with extra columns, aligned left. Note that the name of this function is something of a white lie, as this will only result in the box being moved left by the specified amount if it is already in a larger right-aligned context.

moveRight :: Int -> Box -> Box

Move a box right by putting it in a larger box with extra columns, aligned right. See the disclaimer for `moveLeft`.

moveUp :: Int -> Box -> Box

Move a box "up" by putting it in a larger box with extra rows, aligned to the top. See the disclaimer for `moveLeft`.

moveDown :: Int -> Box -> Box

Move a box down by putting it in a larger box with extra rows, aligned to the bottom. See the disclaimer for `moveLeft`.

alignHoriz :: Alignment -> Int -> Box -> Box

`alignHoriz algn n bx` creates a box of width `n`, with the contents and height of `bx`, horizontally aligned according to `algn`.

alignVert :: Alignment -> Int -> Box -> Box

`alignVert algn n bx` creates a box of height `n`, with the contents and width of `bx`, vertically aligned according to `algn`.

align :: Alignment -> Alignment -> Int -> Int -> Box -> Box

`align ah av r c bx` creates an `r` x `c` box with the contents of `bx`, aligned horizontally according to `ah` and vertically according to `av`.

# Inspecting boxes

rows :: Box -> Int

cols :: Box -> Int

# Rendering boxes

render :: Box -> String

Render a `Box` as a String, suitable for writing to the screen or a file.

printBox :: Box -> IO ()

A convenience function for rendering a box to stdout.