Darcs.Util.Printer

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.

Doc type and structural combinators

newtype Doc

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

Constructors

Doc

Fields

• unDoc :: St -> Document

Instances

IsString Doc

Together with the language extension OverloadedStrings, this allows to use string literals where a Doc is expected.

Defined in Darcs.Util.Printer

Methods

fromString :: String -> Doc

Monoid Doc

mappend (<>) is concatenation, mempty is the empty Doc

Defined in Darcs.Util.Printer

Methods

mempty :: Doc

mappend :: Doc -> Doc -> Doc

mconcat :: [Doc] -> Doc

Semigroup Doc

Defined in Darcs.Util.Printer

Methods

(<>) :: Doc -> Doc -> Doc

sconcat :: NonEmpty Doc -> Doc

stimes :: Integral b => b -> Doc -> Doc

empty :: Doc

The empty Doc

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

An associative operation.

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

(<?>) :: 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 Docs vertically

vsep :: [Doc] -> Doc

Pile Docs vertically, with a blank line in between

hcat :: [Doc] -> Doc

Concatenate Docs horizontally

hsep :: [Doc] -> Doc

Concatenate Docs 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 Docs

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 Strings 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 FilePaths 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 Docs

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