darcs-2.12.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
- Printers
- Printables
- Constructing colored `Doc`s
- IO
- Unsafe constructors

Description

A `Document` is at heart `ShowS` from the prelude

Essentially, if you give a Doc a string it'll print out whatever it wants followed by that string. So `text "foo"` makes the Doc that prints `"foo"` followed by its argument. The combinator names are taken from `HughesPJ`, although the behaviour of the two libraries is slightly different.

The advantage of Printer over simple string appending/concatenating is that the appends end up associating to the right, e.g.:

      (text "foo" <> text "bar") <> (text "baz" <> text "quux") ""
    = \s -> (text "foo" <> text "bar") ((text "baz" <> text "quux") s) ""
    = (text "foo" <> text "bar") ((text "baz" <> text "quux") "")
    = (\s -> (text "foo") (text "bar" s)) ((text "baz" <> text "quux") "")
    = text "foo" (text "bar" ((text "baz" <> text "quux") ""))
    = (\s -> "foo" ++ s) (text "bar" ((text "baz" <> text "quux") ""))
    = "foo" ++ (text "bar" ((text "baz" <> text "quux") ""))
    = "foo" ++ ("bar" ++ ((text "baz" <> text "quux") ""))
    = "foo" ++ ("bar" ++ ((\s -> text "baz" (text "quux" s)) ""))
    = "foo" ++ ("bar" ++ (text "baz" (text "quux" "")))
    = "foo" ++ ("bar" ++ ("baz" ++ (text "quux" "")))
    = "foo" ++ ("bar" ++ ("baz" ++ ("quux" ++ "")))

The Empty alternative comes in because you want

    text "a" $$ vcat xs $$ text "b"

`$$` means above, `vcat` is the list version of `$$` (to be `"a\nb"` when `xs` is `[]`), but without the concept of an Empty Document each `$$` would add a `'\n'` and you'd end up with `"a\n\nb"`. Note that `Empty /= text ""` (the latter would cause two `'\\n'`).

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

Synopsis

- newtype Doc = Doc {
  - unDoc :: St -> Document
  }
- empty :: Doc
- (<>) :: Monoid m => m -> m -> m
- (<?>) :: 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
- text :: String -> Doc
- hiddenText :: String -> Doc
- invisibleText :: String -> Doc
- wrapText :: Int -> String -> Doc
- quoted :: String -> 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
- data RenderMode
  - = Encode
  - | Standard
- renderString :: RenderMode -> Doc -> String
- renderStringWith :: Printers' -> RenderMode -> Doc -> String
- renderPS :: RenderMode -> Doc -> ByteString
- renderPSWith :: Printers' -> RenderMode -> Doc -> ByteString
- renderPSs :: RenderMode -> Doc -> [ByteString]
- renderPSsWith :: Printers' -> RenderMode -> Doc -> [ByteString]
- type Printers = Handle -> 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 :: RenderMode -> Handle -> Doc -> IO ()
- hPutDocLn :: RenderMode -> Handle -> Doc -> IO ()
- putDoc :: Doc -> IO ()
- putDocLn :: Doc -> IO ()
- hPutDocWith :: Printers -> RenderMode -> Handle -> Doc -> IO ()
- hPutDocLnWith :: Printers -> RenderMode -> Handle -> Doc -> IO ()
- putDocWith :: Printers -> Doc -> IO ()
- putDocLnWith :: Printers -> Doc -> IO ()
- hPutDocCompr :: RenderMode -> Handle -> Doc -> IO ()
- debugDocLn :: Doc -> IO ()
- ePutDocLn :: Doc -> IO ()
- errorDoc :: Doc -> a
- 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

IsString Doc # | Together with the language extension OverloadedStrings, this allows to use string literals where a `Doc` is expected.
Methods fromString :: String -> Doc #
Monoid Doc # | `mappend` (`<>`) is concatenation, `mempty` is the `empty` `Doc`
Methods mempty :: Doc # mappend :: Doc -> Doc -> Doc # mconcat :: [Doc] -> Doc #

empty :: Doc #

The empty `Doc`

(<>) :: Monoid m => m -> m -> m infixr 6 #

An infix synonym for `mappend`.

Since: 4.5.0.0

(<?>) :: 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 a space, then `b`

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

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

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

# 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

userchunk :: String -> Doc #

`userchunk` creates a `Doc` containing a user chunk from a `String`

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 #

`userchunkPS` creates a `Doc` representing a user chunk from a `ByteString`.

Rrrright. And what, please is that supposed to mean?

# Rendering

data RenderMode #

Used when rendering a `Doc` to indicate if the result should be encoded to the current locale or left alone. In practice this only affects output when a relevant DARCS_DONT_ESCAPE_XXX option is set (see Darcs.Util.Printer.Color) If in doubt, choose `Standard`.

Constructors

Encode | Encode Strings with the current locale. At present ByteStrings are assumed to be in UTF8 and are left alone, so will be mis-encoded in non-UTF8 locales.
Standard | Don't encode.

renderString :: RenderMode -> Doc -> String #

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

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

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

renderPS :: RenderMode -> Doc -> ByteString #

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

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

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

renderPSs :: RenderMode -> Doc -> [ByteString] #

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

renderPSsWith :: Printers' -> RenderMode -> 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 -> 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... WTF is a userchunk???

# 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

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

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

hPutDocLn :: RenderMode -> 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 -> RenderMode -> Handle -> Doc -> IO () #

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

hPutDocLnWith :: Printers -> RenderMode -> 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 :: RenderMode -> Handle -> Doc -> IO () #

like `hPutDoc` but with compress data before writing

debugDocLn :: Doc -> IO () #

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

ePutDocLn :: Doc -> IO () #

`eputDocLn` puts a doc, followed by a newline to stderr using `simplePrinters`. Like putDocLn, it encodes with the user's locale. This function is the recommended way to output messages that should be visible to users on the console, but cannot (or should not) be silenced even when --quiet is in effect.

errorDoc :: Doc -> a #

Fail with a stack trace and the given `Doc` as error message.

# Unsafe 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`