Copyright	(c) Alec Theriault 2017-2018
License	BSD-style
Maintainer	alec.theriault@gmail.com
Stability	experimental
Portability	portable
Safe Haskell	None
Language	Haskell2010

Language.Rust.Pretty.Util

Description

This module contains a variety of utility functions for pretty printing. Most of these require inspecting the internal structure of Doc.

Wadler's take on pretty printing is super useful because it allows us to print thinks like blocks much more nicely (see this) that Hughes'. Unfortunately, unlike Hughes', Wadler does not have mempty as the identity of + - the space between the arguments of + does not go away even if either argument is empty. The same problem shows up for hsep, #, vsep, /, etc.

My solution has been to redefine my versions of these functions which _do_ treat mempty as a neutral element for +, hsep, #, vsep, and /.

Synopsis

n :: Int
emptyElim :: Doc a -> (Doc a -> Doc a) -> Doc a -> Doc a
(<##>) :: Doc a -> Doc a -> Doc a
flatten :: Doc a -> Doc a
commas :: [a] -> (a -> Doc b) -> Doc b
liftOp :: (Doc a -> Doc a -> Doc a) -> Doc a -> Doc a -> Doc a
(<+>) :: Doc a -> Doc a -> Doc a
hsep :: Foldable f => f (Doc a) -> Doc a
(<#>) :: Doc a -> Doc a -> Doc a
vsep :: Foldable f => f (Doc a) -> Doc a
(</>) :: Doc a -> Doc a -> Doc a
unless :: Bool -> Doc a -> Doc a
when :: Bool -> Doc a -> Doc a
perhaps :: (a -> Doc b) -> Maybe a -> Doc b
indent :: Int -> Doc a -> Doc a
ungroup :: Doc a -> Doc a
noIndent :: Doc a -> Doc a
string :: Doc a -> String -> Doc a
block :: Delim -> Bool -> Doc a -> Doc a -> [Doc a] -> Doc a

Documentation

n :: Int Source #

Indentation level

emptyElim Source #

Arguments

:: Doc a	result if scrutinee is empty
-> (Doc a -> Doc a)	how to process scrutinee if it is not empty
-> Doc a	scrutinee `Doc`
-> Doc a

Similar to maybe, but where the Nothing case is an empty Doc

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

Vertically concatenate two Docs with a collapsible line between them

flatten :: Doc a -> Doc a Source #

Flatten a Doc

commas :: [a] -> (a -> Doc b) -> Doc b Source #

Map the list of items into Docs using the provided function and add comma punctuation

liftOp :: (Doc a -> Doc a -> Doc a) -> Doc a -> Doc a -> Doc a Source #

Take a binary operation on docs and lift it to one that has (left and right) identity mempty

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

Lifted version of Wadler's +

hsep :: Foldable f => f (Doc a) -> Doc a Source #

Lifted version of Wadler's hsep

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

Lifted version of Wadler's #

vsep :: Foldable f => f (Doc a) -> Doc a Source #

Lifted version of Wadler's vsep

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

Lifted version of Wadler's /

unless :: Bool -> Doc a -> Doc a Source #

Unless the condition holds, print the document

when :: Bool -> Doc a -> Doc a Source #

When the condition holds, print the document

perhaps :: (a -> Doc b) -> Maybe a -> Doc b Source #

Apply a printing function to an optional value. If the value is Nothing, perhaps returns the empty Doc.

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

Indent the given Doc, but only if multi-line

ungroup :: Doc a -> Doc a Source #

Undo what group does. This function is pretty dangerous...

noIndent :: Doc a -> Doc a Source #

Remove all indent

string :: Doc a -> String -> Doc a Source #

Translate '\n' in a string using the provided Doc instead of line

block Source #

Arguments

:: Delim	outer delimiters
-> Bool	prefer to be on one line (as opposed to multiline)?
-> Doc a	seperator
-> Doc a	attributes doc, after which no seperator will (use `mempty` to ignore)
-> [Doc a]	entries
-> Doc a

This is the most general function for printing blocks. It operates with any delimiter, any seperator, an optional leading attribute doc (which isn't followed by a seperator), and wraps a list of entries. It has been tweaked to look Just Right (TM) for the usual cases.

Note that this will try to fit things on one line when possible, so if you want a block that is sure not to be condensed on one line (e.g. for a function), you have to construct it manually.