A thing that can be prettyprinted in human-readable (but not necessarily machine-readable) format

A class of things that can be produced from Doc using the default layout engine. Mostly various text types.

Helper intermediary class to define FromDoc. The primary motivation for its existence is being able to override the default layout engine.

>>> :{
layoutNarrow =
  Prettyprinter.layoutPretty $ Prettyprinter.LayoutOptions $
    Prettyprinter.AvailablePerLine 20 1
:}

>>> doc = reflowF "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
>>> fmt doc
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
>>> fmtSimple $ layoutNarrow doc
Lorem ipsum dolor
sit amet,
consectetur
adipiscing elit.

Opaque type for reflowing brackets ++| |++.

build then fmt. Convenience synonym for fmt . build.

A less polymorphic version of pretty for convenience.

Left format bracket. Enclose the value to format in these for concise syntax:

>>> :{
data WorldType = Cruel | Wonderful
  deriving (Generic, Buildable)
:}

>>> sayHello worldType = "Hello, " +| worldType |+ " world!"
>>> sayHello Cruel
Hello, Cruel world!
>>> sayHello Wonderful
Hello, Wonderful world!

Right format bracket

Bracket versions of enumerateF. Note that unlike with |+, both brackets are required.

>>> let splice = "lorem posuere dapibus in ut lorem." :: Doc
>>> let long_splice = splice <> " " <> splice
>>> :{
"Lorem ipsum dolor sit amet, consectetur adipiscing elit." ++| splice
  |++ "Morbi aliquet accumsan libero." ++| long_splice
  |++ "Consectetur adipiscing elit."
:}
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
lorem posuere dapibus in ut lorem. Morbi aliquet accumsan libero.
lorem posuere dapibus in ut lorem. lorem posuere dapibus in ut lorem.
Consectetur adipiscing elit.

>>> let splice = build "lorem\nposuere\ndapibus"
>>> :{
"Lorem ipsum dolor sit amet, consectetur adipiscing elit." ++| splice |++
  "Morbi aliquet accumsan libero."
:}
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
lorem
posuere
dapibus
Morbi aliquet accumsan libero.

A version of the reflowing bracket that always breaks after a splice if there's a break before the splice.

Compare with the similar example for |++, notice the line break after splice. It may be combined with quoteOrIndentF.

>>> let splice = "lorem posuere dapibus in ut lorem." :: Doc
>>> let long_splice = splice <> " " <> splice
>>> :{
"Lorem ipsum dolor sit amet, consectetur adipiscing elit." ++| splice
  |++^ "Morbi aliquet accumsan libero." ++| long_splice
  |++^ "Consectetur adipiscing elit."
:}
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
lorem posuere dapibus in ut lorem.
Morbi aliquet accumsan libero.
lorem posuere dapibus in ut lorem. lorem posuere dapibus in ut lorem.
Consectetur adipiscing elit.

Left formatting bracket.

Join a Foldable with hardlines.

>>> Prettyprinter.group $ unlinesF ["foo", "bar", "baz"]
foo
bar
baz

Join a Foldable with spaces.

>>> unwordsF ["foo", "bar", "baz"]
foo bar baz

If name and content fit into the page width and content doesn't contain hard line breaks, layout as single line with : between. Otherwise, make a multiline layout, appending : to name, and nesting content by 2 spaces.

>>> nameF "Test" "foo"
Test: foo
>>> nameF "Test" $ fillSepF $ replicate 27 "foo"
Test:
  foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo foo
  foo foo foo foo foo foo foo foo

If either name or content is empty, returns only the other one.

>>> nameF "" "foo"
foo
>>> nameF "Test" ""
Test

Indent Doc by a given number of spaces.

>>> indentF 4 "foo"
    foo
>>> indentF 4 "foo\nbar"
    foo
    bar

Print a map-like thing in the style of a YAML map.

>>> blockMapF $ [("foo", "bar"), ("baz", "quux")]
foo: bar
baz: quux
>>> blockMapF ([] :: [(Text, Text)])
{}

Version of blockMapF that allows explicitly passing functions to format key and value.

>>> blockMapF' hexF build $ [(123, "foo"), (456, "bar")]
7b: foo
1c8: bar

Render a list-like thing, YAML style.

>>> blockListF ["foo", "bar", "baz"]
- foo
- bar
- baz
>>> blockListF ([] :: [Text])
[]

Version of blockListF that allows explicitly passing a bullet style and formatter for items

>>> blockListF' "*" hexF [1,11,21]
* 1
* b
* 15

Format a map-like thing, JSON-style.

>>> mapF [("foo", "bar"), ("baz", "quux")]
{foo: bar, baz: quux}
>>> mapF ([] :: [(Text, Text)])
{}
>>> mapF $ replicate 9 ("foo", "bar")
{ foo: bar
, foo: bar
...
, foo: bar }
>>> mapF $ [("foo", "bar\nquux"), ("baz", "corge")]
{ foo:
    bar
    quux
, baz: corge }

Version of mapF allowing for custom formatters.

>>> mapF' hexF build [(128, "foo"), (512, "bar")]
{80: foo, 200: bar}

Print a list, JSON-style.

>>> listF [1..3]
[1, 2, 3]
>>> listF [1..100]
[ 1
, 2
...
, 100 ]
>>> listF ["foo", "bar\nbaz"]
[ foo
, bar
  baz ]

Version of listF that allows explicitly specifying a formatter for items.

>>> listF' hexF [1,11,21]
[1, b, 15]

Conditionally print something.

>>> whenF True "foo"
foo
>>> show $ whenF False "foo"
""

Boolean inverse of whenF

>>> unlessF False "foo"
foo
>>> show $ unlessF True "foo"
""

Enumerate pairs of text and Doc, reflowing the content to best-fit line width. This will line-wrap text on whitespace. If Doc is rendered single-line, this will try to fit it inline. Otherwise, it's surrounded by newlines.

>>> :{
long_text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. \
  \ Donec eget diam ac lorem posuere dapibus in ut lorem. Morbi \
  \ aliquet accumsan libero, a tempor nunc egestas ac."
:}

>>> enumerateF [(long_text, mempty)]
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eget diam ac
lorem posuere dapibus in ut lorem. Morbi aliquet accumsan libero, a tempor nunc
egestas ac.

>>> let splice = "SPLICE SPLICE SPLICE" :: Doc
>>> :{
enumerateF
  [ (long_text, splice)
  , (long_text, mempty)
  ]
:}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eget diam ac
lorem posuere dapibus in ut lorem. Morbi aliquet accumsan libero, a tempor nunc
egestas ac. SPLICE SPLICE SPLICE Lorem ipsum dolor sit amet, consectetur
adipiscing elit. Donec eget diam ac lorem posuere dapibus in ut lorem. Morbi
aliquet accumsan libero, a tempor nunc egestas ac.

>>> let splice = build "SPLICE\nSPLICE\nSPLICE"
>>> :{
enumerateF
  [ (long_text, splice)
  , ("Short text", mempty)
  ]
:}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec eget diam ac
lorem posuere dapibus in ut lorem. Morbi aliquet accumsan libero, a tempor nunc
egestas ac.
SPLICE
SPLICE
SPLICE
Short text

Version of enumerateF that allows specifying separator between items.

>>> enumerateF' "," [("Foo", build 1), ("bar", build 2), ("baz", build 3)]
Foo 1, bar 2, baz 3

When the second argument is empty, return mempty, otherwise, return the first argument.

Like fillSep, but skips over empty elements.

Version of fillSepF with punctuation.

Reflow text, line-wrapping on white-space. Any leading and trailing whitespace is stripped.

Force the Doc to be rendered on a single line, regardless of anything, including hard line breaks. Will lead to horrible terrible formatting if overused. In all likelihood, this is not the function you're looking for.

Note that hard line breaks will be removed entirely, not replaced with spaces.

>>> singleLineF ("foo\nbar\nbaz" :: Text)
foobarbaz

Punctuate a foldable with a distinct separator for the last two elements. Useful for enumerations. Does the oxford comma by concatenating first and second arguments. Note that when using a word, a leading space is expected on the pair separator.

>>> fillSepF $ punctuateF "," " and" ([] :: [Doc])

>>> fillSepF $ punctuateF "," " and" ["foo"]
foo
>>> fillSepF $ punctuateF "," " and" ["bar", "baz"]
bar and baz
>>> fillSepF $ punctuateF "," " and" ["foo", "bar", "baz"]
foo, bar, and baz

Version of punctuateF with explicit distinct separators for penultimate element and just two elements.

>>> fillSepF $ punctuateF' "," " and" ", and" ([] :: [Doc])

>>> fillSepF $ punctuateF' "," " and" ", and" ["foo"]
foo
>>> fillSepF $ punctuateF' "," " and" ", and" ["bar", "baz"]
bar and baz
>>> fillSepF $ punctuateF' "," " and" ", and" ["foo", "bar", "baz"]
foo, bar, and baz

Surround a Buildable with the same Doc on both sides.

>>> quoteF "\"" "Foo"
"Foo"

Surround a Buildable with quotes (or anything else really).

quoteF' l r x is equivalent to l <> build x <> r, but it may be more convenient in some cases.

>>> quoteF' "\"" "\"" "Foo"
"Foo"

If buildable fits into the line, wrap it in single quotes. Otherwise, indent it by 2 spaces. This is convenient with enumerateF or reflowing brackets to format a splice that can be long and multiline or short and singleline with about equal probability.

This is a particularly useful specialization of flatAltF.

>>> let splice = "lorem posuere dapibus" :: Doc
>>> let long_splice = unwordsF $ replicate 3 splice
>>> let very_long_splice = unwordsF $ replicate 4 splice

>>> "Foobar" ++| quoteOrIndentF splice |++ "bazbar."
Foobar 'lorem posuere dapibus' bazbar.

>>> "Foobarbazquux" ++| quoteOrIndentF long_splice |++ "bazbar."
Foobarbazquux
'lorem posuere dapibus lorem posuere dapibus lorem posuere dapibus' bazbar.

>>> "Foobarbazquux" ++| quoteOrIndentF long_splice |++^ "bazbar."
Foobarbazquux
  lorem posuere dapibus lorem posuere dapibus lorem posuere dapibus
bazbar.

>>> "Foobar" ++| quoteOrIndentF very_long_splice |++ "bazbar."
Foobar
  lorem posuere dapibus lorem posuere dapibus lorem posuere dapibus
  lorem posuere dapibus
bazbar.

>>> "Foobar" ++| quoteOrIndentF very_long_splice |++^ "bazbar."
Foobar
  lorem posuere dapibus lorem posuere dapibus lorem posuere dapibus
  lorem posuere dapibus
bazbar.

Use different formatters depending on whether the pretty-printed representation fits on the current line or not. The exact meaning of "fits" is determined by the surrounding context. In precise terms, whether multiline or single-line format is chosen is determined by whether the enclosing group is broken or not, respectively. Useful with reflowing brackets, nameF, etc to specify alternate format for short andor single-line and long andor multiline text.

>>> let short = "bar baz" :: Text
>>> let long = unwordsF $ replicate 10 short

>>> nameF "Foo" $ flatAltF (quoteF "\"") (quoteF "'") short
Foo: 'bar baz'

>>> nameF "Foo" $ flatAltF (quoteF "\"") (quoteF "'") long
Foo:
  "bar baz bar baz bar baz bar baz bar baz bar baz bar baz bar baz bar baz
  bar baz"

Class for formatting tuples

>>> tupleF ("foo", "bar", "baz")
(foo, bar, baz)
>>> tupleF ("foo","bar\nbaz")
( foo
, bar
  baz )
>>> :{
tupleF
  ( "foo", "foo", "foo", "foo", "foo"
  , "foo", "foo", "foo", "foo", "foo"
  , "foo", "foo", "foo", "foo", "foo"
  , "foo", "foo", "foo", "foo", "foo"
  )
:}
( foo
, foo
...
, foo )

Wrap an integral type with this if there's no FormatAsHex instance for it yet, or use it with DerivingVia.

>>> hexF $ Hex 128
80

Newtype for use with DerivingVia, e.g.

>>> :{
data Foo = Bar | Baz
  deriving (Generic, Buildable)
:}

>>> build Bar
Bar

Handles infix constructors properly:

>>> data Inf = Text :-> Text deriving (Generic, Buildable)
>>> build $ "foo" :-> "bar"
foo :-> bar
>>> data Inf2 = Text `Con` Text deriving (Generic, Buildable)
>>> build $ Con "foo" "bar"
foo `Con` bar

>>> :{
data LargeTy = LargeTy
  Text Text Text Text Text
  Text Text Text Text Text
  Text Text Text Text Text
  Text Text Text Text Text
  deriving (Generic, Buildable)
:}

>>> :{
build $ LargeTy
  "foo" "foo" "foo" "foo" "foo"
  "foo" "foo" "foo" "foo" "foo"
  "foo" "foo" "foo" "foo" "foo"
  "foo" "foo" "foo" "foo" "foo"
:}
LargeTy;
  foo,  foo,  foo,  foo,  foo,  foo,  foo,  foo,  foo,  foo,  foo,  foo,  foo,
  foo,  foo,  foo,  foo,  foo,  foo,  foo

There is a special case for tuples:

>>> :{
newtype Tup = Tup (Int, Int, Text)
  deriving stock Generic
  deriving anyclass Buildable
:}

>>> build $ Tup (1, 2, "many")
Tup; (1, 2, many)
>>> build $ Tup (1, 2, "many\nlines")
Tup;
  ( 1
  , 2
  , many
    lines )

Renders records as maps

>>> :{
data Rec = Rec
  { foo :: Text
  , bar :: Text
  , baz :: Text
  } deriving (Generic, Buildable)
:}

>>> build $ Rec "quux" "waldo" "corge"
Rec:
  foo: quux
  bar: waldo
  baz: corge

Helper class for GBuildable.