ansi-wl-pprint-1.0.2: The Wadler/Leijen Pretty Printer for colored ANSI terminal output

Copyright | Daan Leijen (c) 2000 http://www.cs.uu.nl/~daan Max Bolingbroke (c) 2008 http://blog.omega-prime.co.uk
License | BSD-style (see the file LICENSE)
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | provisional
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

Text.PrettyPrint.ANSI.Leijen

Contents

- The algebra of pretty-printing
- Documents
- Basic combinators
- Alignment combinators
- Operators
- List combinators
- Filler combinators
- Bracketing combinators
- Named character combinators
- ANSI formatting combinators
  - Forecolor combinators
  - Backcolor combinators
  - Emboldening combinators
  - Underlining combinators
  - Formatting elimination combinators
- Pretty class
- Rendering and displaying documents
  - Simple (i.e., rendered) documents
  - Simultaneous rendering and displaying of documents
- Undocumented

Description

Deprecated: Compatibility module for users of ansi-wl-pprint - use Prettyprinter instead

This module is an extended implementation of the functional pretty printer given by Philip Wadler (1997):

         "A prettier printer"
         Draft paper, April 1997, revised March 1998.
         https://homepages.inf.ed.ac.uk/wadler/papers/prettier/prettier.pdf

In their bare essence, the combinators given by Wadler are not expressive enough to describe some commonly occurring layouts. This library adds new primitives to describe these layouts and works well in practice.

The library is based on a single way to concatenate documents, which is associative and has both a left and right unit. This simple design leads to an efficient and short implementation. The simplicity is reflected in the predictable behaviour of the combinators which make them easy to use in practice.

A thorough description of the primitive combinators and their implementation can be found in Philip Wadler's paper. The main differences with his original paper are:

- The nil document is called `empty`.
- The above combinator is called `<$>`. The operator `</>` is used for soft line breaks.
- There are three new primitives: `align`, `fill` and `fillBreak`. These are very useful in practice.
- There are many additional useful combinators, like `fillSep` and `list`.
- There are two renderers: `renderPretty` for pretty printing, and `renderCompact` for quickly rendered, compact output more suitable for generating input to other programs.
- The pretty printing algorithm used by `renderPretty` extends the algorithm given by Wadler to take into account a "ribbon width", i.e., a desired maximum number of non-indentation characters to output on any one line.
- There are two displayers, `displayS` for strings and `displayIO` for file-based output.
- There is a `Pretty` class.
- The implementation uses optimised representations and strictness annotations.
- The library has been extended to allow formatting text for output to ANSI style consoles. New combinators allow control of foreground and background color and the ability to make parts of the text bold or underlined.

Synopsis

- type Doc = Doc AnsiStyle
- empty :: Doc
- char :: Char -> Doc
- text :: String -> Doc
- string :: String -> Doc
- int :: Int -> Doc
- integer :: Integer -> Doc
- float :: Float -> Doc
- double :: Double -> Doc
- rational :: Rational -> Doc
- bool :: Bool -> Doc
- (<>) :: Semigroup a => a -> a -> a
- nest :: Int -> Doc -> Doc
- line :: Doc
- linebreak :: Doc
- group :: Doc -> Doc
- softline :: Doc
- softbreak :: Doc
- hardline :: Doc
- flatAlt :: Doc -> Doc -> Doc
- align :: Doc -> Doc
- hang :: Int -> Doc -> Doc
- indent :: Int -> Doc -> Doc
- encloseSep :: Doc -> Doc -> Doc -> [Doc] -> Doc
- list :: [Doc] -> Doc
- tupled :: [Doc] -> Doc
- semiBraces :: [Doc] -> Doc
- (<+>) :: Doc -> Doc -> Doc
- (<$>) :: Doc -> Doc -> Doc
- (</>) :: Doc -> Doc -> Doc
- (<$$>) :: Doc -> Doc -> Doc
- (<//>) :: Doc -> Doc -> Doc
- hsep :: [Doc] -> Doc
- vsep :: [Doc] -> Doc
- fillSep :: [Doc] -> Doc
- sep :: [Doc] -> Doc
- hcat :: [Doc] -> Doc
- vcat :: [Doc] -> Doc
- fillCat :: [Doc] -> Doc
- cat :: [Doc] -> Doc
- punctuate :: Doc -> [Doc] -> [Doc]
- fill :: Int -> Doc -> Doc
- fillBreak :: Int -> Doc -> Doc
- enclose :: Doc -> Doc -> Doc -> Doc
- squotes :: Doc -> Doc
- dquotes :: Doc -> Doc
- parens :: Doc -> Doc
- angles :: Doc -> Doc
- braces :: Doc -> Doc
- brackets :: Doc -> Doc
- lparen :: Doc
- rparen :: Doc
- langle :: Doc
- rangle :: Doc
- lbrace :: Doc
- rbrace :: Doc
- lbracket :: Doc
- rbracket :: Doc
- squote :: Doc
- dquote :: Doc
- semi :: Doc
- colon :: Doc
- comma :: Doc
- space :: Doc
- dot :: Doc
- backslash :: Doc
- equals :: Doc
- black :: Doc -> Doc
- red :: Doc -> Doc
- green :: Doc -> Doc
- yellow :: Doc -> Doc
- blue :: Doc -> Doc
- magenta :: Doc -> Doc
- cyan :: Doc -> Doc
- white :: Doc -> Doc
- dullblack :: Doc -> Doc
- dullred :: Doc -> Doc
- dullgreen :: Doc -> Doc
- dullyellow :: Doc -> Doc
- dullblue :: Doc -> Doc
- dullmagenta :: Doc -> Doc
- dullcyan :: Doc -> Doc
- dullwhite :: Doc -> Doc
- onblack :: Doc -> Doc
- onred :: Doc -> Doc
- ongreen :: Doc -> Doc
- onyellow :: Doc -> Doc
- onblue :: Doc -> Doc
- onmagenta :: Doc -> Doc
- oncyan :: Doc -> Doc
- onwhite :: Doc -> Doc
- ondullblack :: Doc -> Doc
- ondullred :: Doc -> Doc
- ondullgreen :: Doc -> Doc
- ondullyellow :: Doc -> Doc
- ondullblue :: Doc -> Doc
- ondullmagenta :: Doc -> Doc
- ondullcyan :: Doc -> Doc
- ondullwhite :: Doc -> Doc
- bold :: Doc -> Doc
- debold :: Doc -> Doc
- underline :: Doc -> Doc
- deunderline :: Doc -> Doc
- plain :: Doc -> Doc
- class Pretty a where
  - pretty :: a -> Doc ann
  - prettyList :: [a] -> Doc ann
- type SimpleDoc = SimpleDocStream AnsiStyle
- renderPretty :: Float -> Int -> Doc -> SimpleDoc
- renderCompact :: Doc -> SimpleDoc
- renderSmart :: Float -> Int -> Doc -> SimpleDoc
- displayS :: SimpleDoc -> ShowS
- displayIO :: Handle -> SimpleDoc -> IO ()
- putDoc :: Doc -> IO ()
- hPutDoc :: Handle -> Doc -> IO ()
- column :: (Int -> Doc) -> Doc
- columns :: (Maybe Int -> Doc) -> Doc
- nesting :: (Int -> Doc) -> Doc
- width :: Doc -> (Int -> Doc) -> Doc

# The algebra of pretty-printing

The combinators in this library satisfy many algebraic laws.

The concatenation operator `<>` is associative and has `empty` as a left and right unit:

    x <> (y <> z)           = (x <> y) <> z
    x <> empty              = x
    empty <> x              = x

The `text` combinator is a homomorphism from string concatenation to document concatenation:

    text (s ++ t)           = text s <> text t
    text ""                 = empty

The `char` combinator behaves like one-element text:

    char c                  = text [c]

The `nest` combinator is a homomorphism from addition to document composition. `nest` also distributes through document concatenation and is absorbed by `text` and `align`:

    nest (i + j) x          = nest i (nest j x)
    nest 0 x                = x
    nest i (x <> y)         = nest i x <> nest i y
    nest i empty            = empty
    nest i (text s)         = text s
    nest i (align x)        = align x

The `group` combinator is absorbed by `empty`. `group` is commutative with `nest` and `align`:

    group empty             = empty
    group (text s <> x)     = text s <> group x
    group (nest i x)        = nest i (group x)
    group (align x)         = align (group x)

The `align` combinator is absorbed by `empty` and `text`. `align` is idempotent:

    align empty             = empty
    align (text s)          = text s
    align (align x)         = align x

From the laws of the primitive combinators, we can derive many other laws for the derived combinators. For example, the above operator `<$>` is defined as:

    x <$> y                 = x <> line <> y

It follows that `<$>` is associative and that `<$>` and `<>` associate with each other:

    x <$> (y <$> z)         = (x <$> y) <$> z
    x <> (y <$> z)          = (x <> y) <$> z
    x <$> (y <> z)          = (x <$> y) <> z

Similar laws also hold for the other line break operators `</>`, `<$$>`, and `<//>`.

# Documents

type Doc = Doc AnsiStyle Source #

# Basic combinators

empty :: Doc Source #

char :: Char -> Doc Source #

text :: String -> Doc Source #

string :: String -> Doc Source #

int :: Int -> Doc Source #

integer :: Integer -> Doc Source #

float :: Float -> Doc Source #

double :: Double -> Doc Source #

rational :: Rational -> Doc Source #

bool :: Bool -> Doc Source #

(<>) :: Semigroup a => a -> a -> a infixr 6 Source #

An associative operation.

#### Examples

Expand

    >>> [1,2,3] <> [4,5,6]
    [1,2,3,4,5,6]

    >>> Just [1, 2, 3] <> Just [4, 5, 6]
    Just [1,2,3,4,5,6]

    >>> putStr "Hello, " <> putStrLn "World!"
    Hello, World!

nest :: Int -> Doc -> Doc Source #

line :: Doc Source #

linebreak :: Doc Source #

group :: Doc -> Doc Source #

softline :: Doc Source #

softbreak :: Doc Source #

hardline :: Doc Source #

flatAlt :: Doc -> Doc -> Doc Source #

# Alignment combinators

The combinators in this section cannot be described by Wadler's original combinators. They align their output relative to the current output position — in contrast to `nest` which always aligns to the current nesting level. This deprives these combinators from being `optimal'. In practice however they prove to be very useful. The combinators in this section should be used with care, since they are more expensive than the other combinators. For example, `align` shouldn't be used to pretty print all top-level declarations of a language, but using `hang` for let expressions is fine.

align :: Doc -> Doc Source #

hang :: Int -> Doc -> Doc Source #

indent :: Int -> Doc -> Doc Source #

encloseSep :: Doc -> Doc -> Doc -> [Doc] -> Doc Source #

list :: [Doc] -> Doc Source #

tupled :: [Doc] -> Doc Source #

semiBraces :: [Doc] -> Doc Source #

# Operators

(<+>) :: Doc -> Doc -> Doc Source #

(<$>) :: Doc -> Doc -> Doc Source #

(</>) :: Doc -> Doc -> Doc Source #

(<$$>) :: Doc -> Doc -> Doc Source #

(<//>) :: Doc -> Doc -> Doc Source #

# List combinators

hsep :: [Doc] -> Doc Source #

vsep :: [Doc] -> Doc Source #

fillSep :: [Doc] -> Doc Source #

sep :: [Doc] -> Doc Source #

hcat :: [Doc] -> Doc Source #

vcat :: [Doc] -> Doc Source #

fillCat :: [Doc] -> Doc Source #

cat :: [Doc] -> Doc Source #

punctuate :: Doc -> [Doc] -> [Doc] Source #

# Filler combinators

fill :: Int -> Doc -> Doc Source #

fillBreak :: Int -> Doc -> Doc Source #

# Bracketing combinators

enclose :: Doc -> Doc -> Doc -> Doc Source #

squotes :: Doc -> Doc Source #

dquotes :: Doc -> Doc Source #

parens :: Doc -> Doc Source #

angles :: Doc -> Doc Source #

braces :: Doc -> Doc Source #

brackets :: Doc -> Doc Source #

# Named character combinators

lparen :: Doc Source #

rparen :: Doc Source #

langle :: Doc Source #

rangle :: Doc Source #

lbrace :: Doc Source #

rbrace :: Doc Source #

lbracket :: Doc Source #

rbracket :: Doc Source #

squote :: Doc Source #

dquote :: Doc Source #

semi :: Doc Source #

colon :: Doc Source #

comma :: Doc Source #

space :: Doc Source #

dot :: Doc Source #

backslash :: Doc Source #

equals :: Doc Source #

# ANSI formatting combinators

This terminal formatting functionality is, as far as possible, portable across platforms with their varying terminals. However, note that to display ANSI colors and formatting will only be displayed on Windows consoles if the `Doc` value is output using the `putDoc` function or one of its friends. Rendering the `Doc` to a `String` and then outputing that will only work on Unix-style operating systems.

## Forecolor combinators

black :: Doc -> Doc Source #

red :: Doc -> Doc Source #

green :: Doc -> Doc Source #

yellow :: Doc -> Doc Source #

blue :: Doc -> Doc Source #

magenta :: Doc -> Doc Source #

cyan :: Doc -> Doc Source #

white :: Doc -> Doc Source #

dullblack :: Doc -> Doc Source #

dullred :: Doc -> Doc Source #

dullgreen :: Doc -> Doc Source #

dullyellow :: Doc -> Doc Source #

dullblue :: Doc -> Doc Source #

dullmagenta :: Doc -> Doc Source #

dullcyan :: Doc -> Doc Source #

dullwhite :: Doc -> Doc Source #

## Backcolor combinators

onblack :: Doc -> Doc Source #

onred :: Doc -> Doc Source #

ongreen :: Doc -> Doc Source #

onyellow :: Doc -> Doc Source #

onblue :: Doc -> Doc Source #

onmagenta :: Doc -> Doc Source #

oncyan :: Doc -> Doc Source #

onwhite :: Doc -> Doc Source #

ondullblack :: Doc -> Doc Source #

ondullred :: Doc -> Doc Source #

ondullgreen :: Doc -> Doc Source #

ondullyellow :: Doc -> Doc Source #

ondullblue :: Doc -> Doc Source #

ondullmagenta :: Doc -> Doc Source #

ondullcyan :: Doc -> Doc Source #

ondullwhite :: Doc -> Doc Source #

## Emboldening combinators

bold :: Doc -> Doc Source #

debold :: Doc -> Doc Source #

## Underlining combinators

underline :: Doc -> Doc Source #

deunderline :: Doc -> Doc Source #

## Formatting elimination combinators

plain :: Doc -> Doc Source #

# Pretty class

class Pretty a where #

Minimal complete definition

pretty

Methods

pretty :: a -> Doc ann #

prettyList :: [a] -> Doc ann #

#### Instances

Instances details

Pretty Void |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Void -> Doc ann # prettyList :: [Void] -> Doc ann #
Pretty Int16 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Int16 -> Doc ann # prettyList :: [Int16] -> Doc ann #
Pretty Int32 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Int32 -> Doc ann # prettyList :: [Int32] -> Doc ann #
Pretty Int64 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Int64 -> Doc ann # prettyList :: [Int64] -> Doc ann #
Pretty Int8 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Int8 -> Doc ann # prettyList :: [Int8] -> Doc ann #
Pretty Word16 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Word16 -> Doc ann # prettyList :: [Word16] -> Doc ann #
Pretty Word32 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Word32 -> Doc ann # prettyList :: [Word32] -> Doc ann #
Pretty Word64 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Word64 -> Doc ann # prettyList :: [Word64] -> Doc ann #
Pretty Word8 |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Word8 -> Doc ann # prettyList :: [Word8] -> Doc ann #
Pretty Text |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Text -> Doc ann # prettyList :: [Text] -> Doc ann #
Pretty Text |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Text -> Doc ann # prettyList :: [Text] -> Doc ann #
Pretty Integer |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Integer -> Doc ann # prettyList :: [Integer] -> Doc ann #
Pretty Natural |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Natural -> Doc ann # prettyList :: [Natural] -> Doc ann #
Pretty () |
Instance details Defined in Prettyprinter.Internal Methods pretty :: () -> Doc ann # prettyList :: [()] -> Doc ann #
Pretty Bool |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Bool -> Doc ann # prettyList :: [Bool] -> Doc ann #
Pretty Char |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Char -> Doc ann # prettyList :: [Char] -> Doc ann #
Pretty Double |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Double -> Doc ann # prettyList :: [Double] -> Doc ann #
Pretty Float |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Float -> Doc ann # prettyList :: [Float] -> Doc ann #
Pretty Int |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Int -> Doc ann # prettyList :: [Int] -> Doc ann #
Pretty Word |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Word -> Doc ann # prettyList :: [Word] -> Doc ann #
Pretty a => Pretty (Identity a) |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Identity a -> Doc ann # prettyList :: [Identity a] -> Doc ann #
Pretty a => Pretty (NonEmpty a) |
Instance details Defined in Prettyprinter.Internal Methods pretty :: NonEmpty a -> Doc ann # prettyList :: [NonEmpty a] -> Doc ann #
Pretty a => Pretty (Maybe a) |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Maybe a -> Doc ann # prettyList :: [Maybe a] -> Doc ann #
Pretty a => Pretty [a] |
Instance details Defined in Prettyprinter.Internal Methods pretty :: [a] -> Doc ann # prettyList :: [[a]] -> Doc ann #
(Pretty a1, Pretty a2) => Pretty (a1, a2) |
Instance details Defined in Prettyprinter.Internal Methods pretty :: (a1, a2) -> Doc ann # prettyList :: [(a1, a2)] -> Doc ann #
Pretty a => Pretty (Const a b) |
Instance details Defined in Prettyprinter.Internal Methods pretty :: Const a b -> Doc ann # prettyList :: [Const a b] -> Doc ann #
(Pretty a1, Pretty a2, Pretty a3) => Pretty (a1, a2, a3) |
Instance details Defined in Prettyprinter.Internal Methods pretty :: (a1, a2, a3) -> Doc ann # prettyList :: [(a1, a2, a3)] -> Doc ann #

# Rendering and displaying documents

## Simple (i.e., rendered) documents

type SimpleDoc = SimpleDocStream AnsiStyle Source #

renderPretty :: Float -> Int -> Doc -> SimpleDoc Source #

renderCompact :: Doc -> SimpleDoc Source #

renderSmart :: Float -> Int -> Doc -> SimpleDoc Source #

displayS :: SimpleDoc -> ShowS Source #

displayIO :: Handle -> SimpleDoc -> IO () Source #

## Simultaneous rendering and displaying of documents

putDoc :: Doc -> IO () Source #

hPutDoc :: Handle -> Doc -> IO () Source #

# Undocumented

column :: (Int -> Doc) -> Doc Source #

columns :: (Maybe Int -> Doc) -> Doc Source #

nesting :: (Int -> Doc) -> Doc Source #

width :: Doc -> (Int -> Doc) -> Doc Source #