darcs-2.18.5: a distributed, interactive, smart revision control system

Safe Haskell | None
Language | Haskell2010

Darcs.Util.Printer

Contents

- `Doc` type and structural combinators
- Constructing `Doc`s
- Rendering to `String`
- Rendering to `ByteString`
- Printers
- Printables
- Constructing colored `Doc`s
- IO, uses `hPut` for output
- TODO: It is unclear what is unsafe about these constructors

Description

Darcs pretty printing library

The combinator names are taken from `HughesPJ`, although the behaviour of the two libraries is slightly different.

This code was made generic in the element type by Juliusz Chroboczek.

Synopsis

- newtype Doc = Doc {
  - unDoc :: St -> Document
  }
- empty :: Doc
- (<>) :: Semigroup a => a -> a -> a
- (<?>) :: Doc -> Doc -> Doc
- (<+>) :: Doc -> Doc -> Doc
- ($$) :: Doc -> Doc -> Doc
- ($+$) :: Doc -> Doc -> Doc
- vcat :: [Doc] -> Doc
- vsep :: [Doc] -> Doc
- hcat :: [Doc] -> Doc
- hsep :: [Doc] -> Doc
- minus :: Doc
- newline :: Doc
- plus :: Doc
- space :: Doc
- backslash :: Doc
- lparen :: Doc
- rparen :: Doc
- parens :: Doc -> Doc
- sentence :: Doc -> Doc
- text :: String -> Doc
- hiddenText :: String -> Doc
- invisibleText :: String -> Doc
- wrapText :: Int -> String -> Doc
- quoted :: String -> Doc
- formatText :: Int -> [String] -> Doc
- formatWords :: [String] -> Doc
- pathlist :: [FilePath] -> Doc
- userchunk :: String -> Doc
- packedString :: ByteString -> Doc
- prefix :: String -> Doc -> Doc
- hiddenPrefix :: String -> Doc -> Doc
- insertBeforeLastline :: Doc -> Doc -> Doc
- prefixLines :: Doc -> Doc -> Doc
- invisiblePS :: ByteString -> Doc
- userchunkPS :: ByteString -> Doc
- renderString :: Doc -> String
- renderStringWith :: Printers' -> Doc -> String
- renderPS :: Doc -> ByteString
- renderPSWith :: Printers' -> Doc -> ByteString
- renderPSs :: Doc -> [ByteString]
- renderPSsWith :: Printers' -> Doc -> [ByteString]
- type Printers = Handle -> IO Printers'
- data Printers' = Printers {
  - colorP :: !(Color -> Printer)
  - invisibleP :: !Printer
  - hiddenP :: !Printer
  - userchunkP :: !Printer
  - defP :: !Printer
  - lineColorT :: !(Color -> Doc -> Doc)
  - lineColorS :: !([Printable] -> [Printable])
  }
- type Printer = Printable -> St -> Document
- simplePrinters :: Printers
- invisiblePrinter :: Printer
- simplePrinter :: Printer
- data Printable
  - = S !String
  - | PS !ByteString
  - | Both !String !ByteString
- doc :: ([Printable] -> [Printable]) -> Doc
- printable :: Printable -> Doc
- invisiblePrintable :: Printable -> Doc
- hiddenPrintable :: Printable -> Doc
- userchunkPrintable :: Printable -> Doc
- data Color
  - = Blue
  - | Red
  - | Green
  - | Cyan
  - | Magenta
- blueText :: String -> Doc
- redText :: String -> Doc
- greenText :: String -> Doc
- magentaText :: String -> Doc
- cyanText :: String -> Doc
- colorText :: Color -> String -> Doc
- lineColor :: Color -> Doc -> Doc
- hPutDoc :: Handle -> Doc -> IO ()
- hPutDocLn :: Handle -> Doc -> IO ()
- putDoc :: Doc -> IO ()
- putDocLn :: Doc -> IO ()
- hPutDocWith :: Printers -> Handle -> Doc -> IO ()
- hPutDocLnWith :: Printers -> Handle -> Doc -> IO ()
- putDocWith :: Printers -> Doc -> IO ()
- putDocLnWith :: Printers -> Doc -> IO ()
- hPutDocCompr :: Handle -> Doc -> IO ()
- debugDocLn :: Doc -> IO ()
- unsafeText :: String -> Doc
- unsafeBoth :: String -> ByteString -> Doc
- unsafeBothText :: String -> Doc
- unsafeChar :: Char -> Doc
- unsafePackedString :: ByteString -> Doc

# `Doc` type and structural combinators

newtype Doc #

A `Doc` is a bit of enriched text. `Doc`s are concatenated using `<>` from class `Monoid`, which is right-associative.

Constructors

Doc |
Fields unDoc :: St -> Document

#### Instances

Instances details

Monoid Doc # | `mappend` (`<>`) is concatenation, `mempty` is the `empty` `Doc`
Instance details Defined in Darcs.Util.Printer Methods mempty :: Doc # mappend :: Doc -> Doc -> Doc # mconcat :: [Doc] -> Doc #
Semigroup Doc # |
Instance details Defined in Darcs.Util.Printer Methods (<>) :: Doc -> Doc -> Doc # sconcat :: NonEmpty Doc -> Doc # stimes :: Integral b => b -> Doc -> Doc #
IsString Doc # | Together with the language extension OverloadedStrings, this allows to use string literals where a `Doc` is expected.
Instance details Defined in Darcs.Util.Printer Methods fromString :: String -> Doc #

empty :: Doc #

The empty `Doc`

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

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!

(<?>) :: Doc -> Doc -> Doc #

`a `<?>` b` is `a `<>` b` if `a` is not empty, else empty

(<+>) :: Doc -> Doc -> Doc infixr 6 #

`a `<+>` b` is `a` followed by `b` with a space in between if both are non-empty

($$) :: Doc -> Doc -> Doc infixr 5 #

`a `$$` b` is `a` above `b`

($+$) :: Doc -> Doc -> Doc infixr 5 #

`a `$+$` b` is `a` above `b` with an empty line in between if both are non-empty

vcat :: [Doc] -> Doc #

Pile `Doc`s vertically

vsep :: [Doc] -> Doc #

Pile `Doc`s vertically, with a blank line in between

hcat :: [Doc] -> Doc #

Concatenate `Doc`s horizontally

hsep :: [Doc] -> Doc #

Concatenate `Doc`s horizontally with a space as separator

minus :: Doc #

A `Doc` representing a "-"

newline :: Doc #

A `Doc` representing a newline

plus :: Doc #

A `Doc` representing a "+"

space :: Doc #

A `Doc` representing a space (" ")

backslash :: Doc #

A `Doc` representing a "\"

lparen :: Doc #

A `Doc` that represents `"("`

rparen :: Doc #

A `Doc` that represents `")"`

parens :: Doc -> Doc #

    parens d = lparen <> d <> rparen

sentence :: Doc -> Doc #

Turn a `Doc` into a sentence. This appends a ".".

# Constructing `Doc`s

text :: String -> Doc #

`text` creates a `Doc` from a `String`, using `printable`.

hiddenText :: String -> Doc #

`hiddenText` creates a `Doc` containing hidden text from a `String`

invisibleText :: String -> Doc #

`invisibleText` creates a `Doc` containing invisible text from a `String`

wrapText :: Int -> String -> Doc #

``wrapText` n s` is a `Doc` representing `s` line-wrapped at `n` characters

quoted :: String -> Doc #

Quote a string for screen output

formatText :: Int -> [String] -> Doc #

Given a list of `String`s representing the words of a paragraph, format the paragraphs using `wrapText` and separate them with an empty line.

formatWords :: [String] -> Doc #

A variant of `wrapText` that takes a list of strings as input. Useful when `{-# LANGUAGE CPP #-}` makes it impossible to use multiline string literals.

pathlist :: [FilePath] -> Doc #

Format a list of `FilePath`s as quoted text. It deliberately refuses to use English.andClauses but rather separates the quoted strings only with a space, because this makes it usable for copy and paste e.g. as arguments to another shell command.

userchunk :: String -> Doc #

Create a `Doc` containing a userchunk from a `String`.

Userchunks are used for printing arbitrary bytes stored in prim patches:

- old and new preference values in ChangePref prims
- tokenChars, old token and new token in TokReplace prims
- old and new content lines in Hunk prims

In colored mode they are printed such that trailing whitespace before the end of a line is made visible by marking the actual line ending with a red `$` char (unless DARCS_DONT_ESCAPE_TRAILING_SPACES or even DARCS_DONT_ESCAPE_ANYTHING are set in the environment).

packedString :: ByteString -> Doc #

`packedString` builds a `Doc` from a `ByteString` using `printable`

prefix :: String -> Doc -> Doc #

hiddenPrefix :: String -> Doc -> Doc #

insertBeforeLastline :: Doc -> Doc -> Doc #

prefixLines :: Doc -> Doc -> Doc #

invisiblePS :: ByteString -> Doc #

`invisiblePS` creates a `Doc` with invisible text from a `ByteString`

userchunkPS :: ByteString -> Doc #

Create a `Doc` representing a user chunk from a `ByteString`; see `userchunk` for details.

# Rendering to `String`

renderString :: Doc -> String #

renders a `Doc` into a `String` with control codes for the special features of the `Doc`.

renderStringWith :: Printers' -> Doc -> String #

renders a `Doc` into a `String` using a given set of printers. If content is only available as `ByteString`, decode according to the current locale.

# Rendering to `ByteString`

renderPS :: Doc -> ByteString #

renders a `Doc` into `ByteString` with control codes for the special features of the Doc. See also `readerString`.

renderPSWith :: Printers' -> Doc -> ByteString #

renders a `Doc` into a `ByteString` using a given set of printers.

renderPSs :: Doc -> [ByteString] #

renders a `Doc` into a list of `PackedStrings`, one for each line.

renderPSsWith :: Printers' -> Doc -> [ByteString] #

renders a `Doc` into a list of `PackedStrings`, one for each chunk of text that was added to the `Doc`, using the given set of printers.

# Printers

type Printers = Handle -> IO Printers' #

data Printers' #

A set of printers to print different types of text to a handle.

Constructors

Printers |
Fields colorP :: !(Color -> Printer) invisibleP :: !Printer hiddenP :: !Printer userchunkP :: !Printer defP :: !Printer lineColorT :: !(Color -> Doc -> Doc) lineColorS :: !([Printable] -> [Printable])

type Printer = Printable -> St -> Document #

simplePrinters :: Printers #

`simplePrinters` is a `Printers` which uses the set 'simplePriners'' on any handle.

invisiblePrinter :: Printer #

`invisiblePrinter` is the `Printer` for hidden text. It just replaces the document with `empty`. It's useful to have a printer that doesn't actually do anything because this allows you to have tunable policies, for example, only printing some text if it's to the terminal, but not if it's to a file or vice-versa.

simplePrinter :: Printer #

`simplePrinter` is the simplest `Printer`: it just concatenates together the pieces of the `Doc`

# Printables

data Printable #

A `Printable` is either a String, a packed string, or a chunk of text with both representations.

Constructors

S !String |
PS !ByteString |
Both !String !ByteString |

doc :: ([Printable] -> [Printable]) -> Doc #

printable :: Printable -> Doc #

Creates a `Doc` from any `Printable`.

invisiblePrintable :: Printable -> Doc #

Creates an invisible `Doc` from any `Printable`.

hiddenPrintable :: Printable -> Doc #

Creates a hidden `Doc` from any `Printable`.

userchunkPrintable :: Printable -> Doc #

Creates a userchunk from any `Printable`; see `userchunk` for details.

# Constructing colored `Doc`s

data Color #

Constructors

Blue |
Red |
Green |
Cyan |
Magenta |

blueText :: String -> Doc #

redText :: String -> Doc #

greenText :: String -> Doc #

magentaText :: String -> Doc #

cyanText :: String -> Doc #

colorText :: Color -> String -> Doc #

`colorText` creates a `Doc` containing colored text from a `String`

lineColor :: Color -> Doc -> Doc #

# IO, uses `hPut` for output

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

`hputDoc` puts a `Doc` on the given handle using `simplePrinters`

hPutDocLn :: Handle -> Doc -> IO () #

`hputDocLn` puts a `Doc`, followed by a newline on the given handle using `simplePrinters`.

putDoc :: Doc -> IO () #

`putDoc` puts a `Doc` on stdout using the simple printer `simplePrinters`.

putDocLn :: Doc -> IO () #

`putDocLn` puts a `Doc`, followed by a newline on stdout using `simplePrinters`

hPutDocWith :: Printers -> Handle -> Doc -> IO () #

`hputDocWith` puts a `Doc` on the given handle using the given printer.

hPutDocLnWith :: Printers -> Handle -> Doc -> IO () #

`hputDocLnWith` puts a `Doc`, followed by a newline on the given handle using the given printer.

putDocWith :: Printers -> Doc -> IO () #

`putDocWith` puts a `Doc` on stdout using the given printer.

putDocLnWith :: Printers -> Doc -> IO () #

`putDocLnWith` puts a `Doc`, followed by a newline on stdout using the given printer.

hPutDocCompr :: Handle -> Doc -> IO () #

like `hPutDoc` but with compress data before writing

debugDocLn :: Doc -> IO () #

Write a `Doc` to stderr if debugging is turned on.

# TODO: It is unclear what is unsafe about these constructors

unsafeText :: String -> Doc #

`unsafeText` creates a `Doc` from a `String`, using `simplePrinter` directly

unsafeBoth :: String -> ByteString -> Doc #

`unsafeBoth` builds a Doc from a `String` and a `ByteString` representing the same text, but does not check that they do.

unsafeBothText :: String -> Doc #

`unsafeBothText` builds a `Doc` from a `String`. The string is stored in the Doc as both a String and a `ByteString`.

unsafeChar :: Char -> Doc #

`unsafeChar` creates a Doc containing just one character.

unsafePackedString :: ByteString -> Doc #

`unsafePackedString` builds a `Doc` from a `ByteString` using `simplePrinter`