Text.Pretty

This library was based on The Design of a Pretty-printing Library by Jeuring and Meijer.

Heavily modified by Simon Peyton Jones (December 1996).

Lightly modified by Hans Hoglund (October 2012).

The Pretty typeclass

class Pretty a where

Class of types that can be pretty-printed.

The Pretty class is similar to Show, but converts values to Printers instead of Strings. A printer is essentially a string with some extra structural information such as length and indentation.

Note that the instances for primitive types, lists and tuples all satisfy

 (show . pretty) x == show x

Methods

pretty :: a -> Printer

Return a printer for the given value.

prettyList :: [a] -> Printer

The method prettyList is provided to allow the programmer to give a specialised way of printing lists of values. For example, this is used by the predefined Pretty instance of the Char type, where values of type String should be shown in double quotes, rather than between square brackets.

Instances

Pretty Char

Pretty Double

Pretty Float

Pretty Int

Pretty Integer

Pretty ()

Pretty Printer

Pretty a => Pretty [a]

(Pretty a, Integral a) => Pretty (Ratio a)

Pretty a => Pretty (Maybe a)

(Pretty a, Pretty b) => Pretty (a, b)

The Printer type

data Printer

The abstract type of printers.

Instances

Show Printer

IsString Printer

Monoid Printer

Semigroup Printer

Pretty Printer

Construction

Primitive types

char :: Char -> Printer

A printer of height and width 1, containing a literal character.

string :: String -> Printer

A printer of height 1 containing a literal string. string satisfies the following laws:

• string s <> string t = string (s++t)

• string "" <> x = x, if x non-empty

The side condition on the last law is necessary because string "" has height 1, while empty has no height.

sizedText :: Int -> String -> Printer

Some string with any width. (string s = sizedText (length s) s)

zeroWidthText :: String -> Printer

Some string, but without any width. Use for non-printing string such as a HTML or Latex tags

int :: Int -> Printer

integer :: Integer -> Printer

float :: Float -> Printer

double :: Double -> Printer

rational :: Rational -> Printer

Combinators

empty :: Printer

The empty printer, with no height and no width. empty is the identity for <>, <+>, </> and <//>, and anywhere in the argument list for sep, hcat, hsep, vcat, fcat etc.

(<->) :: Printer -> Printer -> Printer

Beside. <> is associative, with identity empty.

(<+>) :: Printer -> Printer -> Printer

Beside, separated by space, unless one of the arguments is empty. <+> is associative, with identity empty.

hcat :: [Printer] -> Printer

List version of <>.

hsep :: [Printer] -> Printer

List version of <+>.

(</>) :: Printer -> Printer -> Printer

Above, except that if the last line of the first argument stops at least one position before the first line of the second begins, these two lines are overlapped. For example:

    string "hi" </> nest 5 (string "there")

lays out as

    hi   there

rather than

    hi
         there

</> is associative, with identity empty, and also satisfies

• (x </> y) <> z = x </> (y <> z), if y non-empty.

(<//>) :: Printer -> Printer -> Printer

Above, with no overlapping. <//> is associative, with identity empty.

vcat :: [Printer] -> Printer

List version of </>.

sep :: [Printer] -> Printer

Either hsep or vcat.

cat :: [Printer] -> Printer

Either hcat or vcat.

fsep :: [Printer] -> Printer

"Paragraph fill" version of sep.

fcat :: [Printer] -> Printer

"Paragraph fill" version of cat.

Wrapping and punctuation

wrap :: Char -> Char -> Printer -> Printer

Wrap printer in the given characters.

parens :: Printer -> Printer

Wrap printer in (...)

brackets :: Printer -> Printer

Wrap printer in [...]

braces :: Printer -> Printer

Wrap printer in {...}

quotes :: Printer -> Printer

Wrap printer in '...'

doubleQuotes :: Printer -> Printer

Wrap printer in "..."

nest :: Int -> Printer -> Printer

Nest (or indent) a printer by a given number of positions (which may also be negative). nest satisfies the laws:

• nest 0 x = x

• nest k (nest k' x) = nest (k+k') x

• nest k (x <> y) = nest k z <> nest k y

• nest k (x </> y) = nest k x </> nest k y

• nest k empty = empty

• x <> nest k y = x <> y, if x non-empty

The side condition on the last law is needed because empty is a left identity for <>.

hang :: Printer -> Int -> Printer -> Printer

hang d1 n d2 = sep [d1, nest n d2]

sepBy :: Printer -> [Printer] -> Printer

Join with separator.

 sepBy q [x1,x2..xn] = x1 <> q <> x2 <> q .. xn.

initBy :: Printer -> [Printer] -> Printer

Join with initiator.

 initBy q [x1,x2..xn] = q <> x1 <> q <> x2 <> q .. xn.

termBy :: Printer -> [Printer] -> Printer

Join with terminator.

 termBy q [x1,x2..xn] = x1 <> q <> x2 <> q .. xn <> q.

sepByS :: Printer -> [Printer] -> Printer

Join with separator followed by space.

 sepByS q [x1,x2..xn] = x1 <> q <+> x2 <> q <+>.. xn.

initByS :: Printer -> [Printer] -> Printer

Join with initiator followed by space.

 initByS q [x1,x2..xn] = q <+> x1 <> q <+> x2 <> q <+> .. xn.

termByS :: Printer -> [Printer] -> Printer

Join with terminator followed by space.

 termByS q [x1,x2..xn] = x1 <> q <+> x2 <> q <+> .. xn <> q.

Predicates on printers

isEmpty :: Printer -> Bool

Returns True if the printer is empty

Rendering printers

runPrinter :: Printer -> String

Render the Printer to a String using the default Style.

data Mode

Rendering mode.

Constructors

PageMode

Normal

ZigZagMode

With zig-zag cuts

LeftMode

No indentation, infinitely long lines

OneLineMode

All on one line

data Style

A printing style.

Constructors

Style

Fields

mode :: Mode

The printing mode

lineLength :: Int

Length of line, in chars

ribbonsPerLine :: Float

Ratio of ribbon length to line length

style :: Style

The default style (mode=PageMode, lineLength=100, ribbonsPerLine=1.5).

runPrinterStyle :: Style -> Printer -> String

Render the Printer to a String using the given Style.