-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A modern, easy to use, well-documented, extensible pretty-printer.
--   
--   A modern, easy to use, well-documented, extensible pretty-printer. For
--   more see README.md
@package prettyprinter
@version 1.7.1

module Prettyprinter.Render.Util.Panic

-- | Raise a hard <a>error</a> if there is a <a>SFail</a> in a
--   <a>SimpleDocStream</a>.
panicUncaughtFail :: void

-- | Raise a hard <a>error</a> when an annotation terminator is encountered
--   in an unannotated region.
panicUnpairedPop :: void

-- | Raise a hard generic <a>error</a> when the <a>SimpleDocStream</a> to
--   <a>SimpleDocTree</a> conversion fails.
panicSimpleDocTreeConversionFailed :: void

-- | Raise a hard <a>error</a> when the »to <a>SimpleDocTree</a>« parser
--   finishes without consuming the full input.
panicInputNotFullyConsumed :: void
panicPeekedEmpty :: void
panicPoppedEmpty :: void


-- | <b>Warning: internal module!</b> This means that the API may change
--   arbitrarily between versions without notice. Depending on this module
--   may lead to unexpected breakages, so proceed with caution!
--   
--   For a stable API, use the non-internal modules. For the special case
--   of writing adaptors to this library’s <tt><a>Doc</a></tt> type, see
--   <a>Prettyprinter.Internal.Type</a>.
module Prettyprinter.Internal

-- | The abstract data type <tt><a>Doc</a> ann</tt> represents pretty
--   documents that have been annotated with data of type <tt>ann</tt>.
--   
--   More specifically, a value of type <tt><a>Doc</a></tt> represents a
--   non-empty set of possible layouts of a document. The layout functions
--   select one of these possibilities, taking into account things like the
--   width of the output document.
--   
--   The annotation is an arbitrary piece of data associated with (part of)
--   a document. Annotations may be used by the rendering backends in order
--   to display output differently, such as
--   
--   <ul>
--   <li>color information (e.g. when rendering to the terminal)</li>
--   <li>mouseover text (e.g. when rendering to rich HTML)</li>
--   <li>whether to show something or not (to allow simple or detailed
--   versions)</li>
--   </ul>
--   
--   The simplest way to display a <a>Doc</a> is via the <a>Show</a> class.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn (show (vsep ["hello", "world"]))
--   hello
--   world
--   </pre>
data Doc ann

-- | Occurs when flattening a line. The layouter will reject this document,
--   choosing a more suitable rendering.
Fail :: Doc ann

-- | The empty document; conceptually the unit of <a>Cat</a>
Empty :: Doc ann

-- | invariant: not 'n'
Char :: !Char -> Doc ann

-- | Invariants: at least two characters long, does not contain 'n'. For
--   empty documents, there is <tt>Empty</tt>; for singleton documents,
--   there is <tt>Char</tt>; newlines should be replaced by e.g.
--   <tt>Line</tt>.
--   
--   Since the frequently used <a>length</a> of <a>Text</a> is
--   <i>O(length)</i>, we cache it in this constructor.
Text :: !Int -> !Text -> Doc ann

-- | Hard line break
Line :: Doc ann

-- | Lay out the first <a>Doc</a>, but when flattened (via <a>group</a>),
--   prefer the second.
--   
--   The layout algorithms work under the assumption that the first
--   alternative is less wide than the flattened second alternative.
FlatAlt :: Doc ann -> Doc ann -> Doc ann

-- | Concatenation of two documents
Cat :: Doc ann -> Doc ann -> Doc ann

-- | Document indented by a number of columns
Nest :: !Int -> Doc ann -> Doc ann

-- | Invariant: The first lines of first document should be longer than the
--   first lines of the second one, so the layout algorithm can pick the
--   one that fits best. Used to implement layout alternatives for
--   <a>group</a>.
Union :: Doc ann -> Doc ann -> Doc ann

-- | React on the current cursor position, see <a>column</a>
Column :: (Int -> Doc ann) -> Doc ann

-- | React on the document's width, see <a>pageWidth</a>
WithPageWidth :: (PageWidth -> Doc ann) -> Doc ann

-- | React on the current nesting level, see <a>nesting</a>
Nesting :: (Int -> Doc ann) -> Doc ann

-- | Add an annotation to the enclosed <a>Doc</a>. Can be used for example
--   to add styling directives or alt texts that can then be used by the
--   renderer.
Annotated :: ann -> Doc ann -> Doc ann

-- | Overloaded conversion to <a>Doc</a>.
--   
--   Laws:
--   
--   <ol>
--   <li>output should be pretty. :-)</li>
--   </ol>
class Pretty a

-- | <pre>
--   &gt;&gt;&gt; pretty 1 &lt;+&gt; pretty "hello" &lt;+&gt; pretty 1.234
--   1 hello 1.234
--   </pre>
pretty :: Pretty a => a -> Doc ann
($dmpretty) :: (Pretty a, Show a) => a -> Doc ann

-- | <tt><a>prettyList</a></tt> is only used to define the <tt>instance
--   <a>Pretty</a> a =&gt; <a>Pretty</a> [a]</tt>. In normal circumstances
--   only the <tt><a>pretty</a></tt> function is used.
--   
--   <pre>
--   &gt;&gt;&gt; prettyList [1, 23, 456]
--   [1, 23, 456]
--   </pre>
prettyList :: Pretty a => [a] -> Doc ann

-- | Convenience function to convert a <a>Show</a>able value to a
--   <a>Doc</a>. If the <a>String</a> does not contain newlines, consider
--   using the more performant <a>unsafeViaShow</a>.
viaShow :: Show a => a -> Doc ann

-- | Convenience function to convert a <a>Show</a>able value /that must not
--   contain newlines/ to a <a>Doc</a>. If there may be newlines, use
--   <a>viaShow</a> instead.
unsafeViaShow :: Show a => a -> Doc ann

-- | <tt>(unsafeTextWithoutNewlines s)</tt> contains the literal string
--   <tt>s</tt>.
--   
--   The string must not contain any newline characters, since this is an
--   invariant of the <a>Text</a> constructor.
unsafeTextWithoutNewlines :: Text -> Doc ann

-- | The empty document behaves like <tt>(<a>pretty</a> "")</tt>, so it has
--   a height of 1. This may lead to surprising behaviour if we expect it
--   to bear no weight inside e.g. <a>vcat</a>, where we get an empty line
--   of output from it (<tt>parens</tt> for visibility only):
--   
--   <pre>
--   &gt;&gt;&gt; vsep ["hello", parens emptyDoc, "world"]
--   hello
--   ()
--   world
--   </pre>
--   
--   Together with <a>&lt;&gt;</a>, <a>emptyDoc</a> forms the <a>Monoid</a>
--   <a>Doc</a>.
emptyDoc :: Doc ann

-- | <tt>(<a>nest</a> i x)</tt> lays out the document <tt>x</tt> with the
--   current nesting level (indentation of the following lines) increased
--   by <tt>i</tt>. Negative values are allowed, and decrease the nesting
--   level accordingly.
--   
--   <pre>
--   &gt;&gt;&gt; vsep [nest 4 (vsep ["lorem", "ipsum", "dolor"]), "sit", "amet"]
--   lorem
--       ipsum
--       dolor
--   sit
--   amet
--   </pre>
--   
--   See also
--   
--   <ul>
--   <li><a>hang</a> (<a>nest</a> relative to current cursor position
--   instead of current nesting level)</li>
--   <li><a>align</a> (set nesting level to current cursor position)</li>
--   <li><a>indent</a> (increase indentation on the spot, padding with
--   spaces).</li>
--   </ul>
nest :: Int -> Doc ann -> Doc ann

-- | The <tt><a>line</a></tt> document advances to the next line and
--   indents to the current nesting level.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; line &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
--   
--   <tt><a>line</a></tt> behaves like <tt><tt>space</tt></tt> if the line
--   break is undone by <a>group</a>:
--   
--   <pre>
--   &gt;&gt;&gt; group doc
--   lorem ipsum dolor sit amet
--   </pre>
line :: Doc ann

-- | <tt><a>line'</a></tt> is like <tt><a>line</a></tt>, but behaves like
--   <tt><a>mempty</a></tt> if the line break is undone by <a>group</a>
--   (instead of <tt><tt>space</tt></tt>).
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; line' &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; doc
--   lorem ipsum
--   dolor sit amet
--   
--   &gt;&gt;&gt; group doc
--   lorem ipsumdolor sit amet
--   </pre>
line' :: Doc ann

-- | <tt>softline</tt> behaves like <tt><tt>space</tt></tt> if the
--   resulting output fits the page, otherwise like <tt><a>line</a></tt>.
--   
--   Here, we have enough space to put everything in one line:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; softline &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   lorem ipsum dolor sit amet
--   </pre>
--   
--   If we narrow the page to width 10, the layouter produces a line break:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
--   
--   <pre>
--   <a>softline</a> = <a>group</a> <a>line</a>
--   </pre>
softline :: Doc ann

-- | <tt><a>softline'</a></tt> is like <tt><a>softline</a></tt>, but
--   behaves like <tt><a>mempty</a></tt> if the resulting output does not
--   fit on the page (instead of <tt><tt>space</tt></tt>). In other words,
--   <tt><a>line</a></tt> is to <tt><a>line'</a></tt> how
--   <tt><a>softline</a></tt> is to <tt><a>softline'</a></tt>.
--   
--   With enough space, we get direct concatenation:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "ThisWord" &lt;&gt; softline' &lt;&gt; "IsWayTooLong"
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   ThisWordIsWayTooLong
--   </pre>
--   
--   If we narrow the page to width 10, the layouter produces a line break:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   ThisWord
--   IsWayTooLong
--   </pre>
--   
--   <pre>
--   <a>softline'</a> = <a>group</a> <a>line'</a>
--   </pre>
softline' :: Doc ann

-- | A <tt><a>hardline</a></tt> is <i>always</i> laid out as a line break,
--   even when <a>group</a>ed or when there is plenty of space. Note that
--   it might still be simply discarded if it is part of a <a>flatAlt</a>
--   inside a <a>group</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; hardline &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; putDocW 1000 doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; group doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
hardline :: Doc ann

-- | <tt>(<a>group</a> x)</tt> tries laying out <tt>x</tt> into a single
--   line by removing the contained line breaks; if this does not fit the
--   page, or when a <a>hardline</a> within <tt>x</tt> prevents it from
--   being flattened, <tt>x</tt> is laid out without any changes.
--   
--   The <a>group</a> function is key to layouts that adapt to available
--   space nicely.
--   
--   See <a>vcat</a>, <a>line</a>, or <a>flatAlt</a> for examples that are
--   related, or make good use of it.
group :: Doc ann -> Doc ann

-- | By default, <tt>(<a>flatAlt</a> x y)</tt> renders as <tt>x</tt>.
--   However when <a>group</a>ed, <tt>y</tt> will be preferred, with
--   <tt>x</tt> as the fallback for the case when <tt>y</tt> doesn't fit.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = flatAlt "a" "b"
--   
--   &gt;&gt;&gt; putDoc doc
--   a
--   
--   &gt;&gt;&gt; putDoc (group doc)
--   b
--   
--   &gt;&gt;&gt; putDocW 0 (group doc)
--   a
--   </pre>
--   
--   <a>flatAlt</a> is particularly useful for defining conditional
--   separators such as
--   
--   <pre>
--   softline = <a>group</a> (<a>flatAlt</a> <a>hardline</a> " ")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let hello = "Hello" &lt;&gt; softline &lt;&gt; "world!"
--   
--   &gt;&gt;&gt; putDocW 12 hello
--   Hello world!
--   
--   &gt;&gt;&gt; putDocW 11 hello
--   Hello
--   world!
--   </pre>
--   
--   <h3><b>Example: Haskell's do-notation</b></h3>
--   
--   We can use this to render Haskell's do-notation nicely:
--   
--   <pre>
--   &gt;&gt;&gt; let open        = flatAlt "" "{ "
--   
--   &gt;&gt;&gt; let close       = flatAlt "" " }"
--   
--   &gt;&gt;&gt; let separator   = flatAlt "" "; "
--   
--   &gt;&gt;&gt; let prettyDo xs = group ("do" &lt;+&gt; align (encloseSep open close separator xs))
--   
--   &gt;&gt;&gt; let statements  = ["name:_ &lt;- getArgs", "let greet = \"Hello, \" &lt;&gt; name", "putStrLn greet"]
--   </pre>
--   
--   This is put into a single line with <tt>{;}</tt> style if it fits:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 80 (prettyDo statements)
--   do { name:_ &lt;- getArgs; let greet = "Hello, " &lt;&gt; name; putStrLn greet }
--   </pre>
--   
--   When there is not enough space the statements are broken up into lines
--   nicely:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 (prettyDo statements)
--   do name:_ &lt;- getArgs
--      let greet = "Hello, " &lt;&gt; name
--      putStrLn greet
--   </pre>
--   
--   <h3>Notes</h3>
--   
--   Users should be careful to choose <tt>x</tt> to be less wide than
--   <tt>y</tt>. Otherwise, if <tt>y</tt> turns out not to fit the page, we
--   fall back on an even wider layout:
--   
--   <pre>
--   &gt;&gt;&gt; let ugly = group (flatAlt "even wider" "too wide")
--   
--   &gt;&gt;&gt; putDocW 7 ugly
--   even wider
--   </pre>
--   
--   Also note that <a>group</a> will flatten <tt>y</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (group (flatAlt "x" ("y" &lt;&gt; line &lt;&gt; "y")))
--   y y
--   </pre>
--   
--   This also means that an "unflattenable" <tt>y</tt> which contains a
--   hard linebreak will <i>never</i> be rendered:
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (group (flatAlt "x" ("y" &lt;&gt; hardline &lt;&gt; "y")))
--   x
--   </pre>
flatAlt :: Doc ann -> Doc ann -> Doc ann

-- | <tt>(<a>align</a> x)</tt> lays out the document <tt>x</tt> with the
--   nesting level set to the current column. It is used for example to
--   implement <a>hang</a>.
--   
--   As an example, we will put a document right above another one,
--   regardless of the current nesting level. Without <a>align</a>ment, the
--   second line is put simply below everything we've had so far:
--   
--   <pre>
--   &gt;&gt;&gt; "lorem" &lt;+&gt; vsep ["ipsum", "dolor"]
--   lorem ipsum
--   dolor
--   </pre>
--   
--   If we add an <a>align</a> to the mix, the <tt><a>vsep</a></tt>'s
--   contents all start in the same column:
--   
--   <pre>
--   &gt;&gt;&gt; "lorem" &lt;+&gt; align (vsep ["ipsum", "dolor"])
--   lorem ipsum
--         dolor
--   </pre>
align :: Doc ann -> Doc ann

-- | <tt>(<a>hang</a> i x)</tt> lays out the document <tt>x</tt> with a
--   nesting level set to the <i>current column</i> plus <tt>i</tt>.
--   Negative values are allowed, and decrease the nesting level
--   accordingly.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = reflow "Indenting these words with hang"
--   
--   &gt;&gt;&gt; putDocW 24 ("prefix" &lt;+&gt; hang 4 doc)
--   prefix Indenting these
--              words with
--              hang
--   </pre>
--   
--   This differs from <a>nest</a>, which is based on the <i>current
--   nesting level</i> plus <tt>i</tt>. When you're not sure, try the more
--   efficient <a>nest</a> first. In our example, this would yield
--   
--   <pre>
--   &gt;&gt;&gt; let doc = reflow "Indenting these words with nest"
--   
--   &gt;&gt;&gt; putDocW 24 ("prefix" &lt;+&gt; nest 4 doc)
--   prefix Indenting these
--       words with nest
--   </pre>
--   
--   <pre>
--   <a>hang</a> i doc = <a>align</a> (<a>nest</a> i doc)
--   </pre>
hang :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>indent</a> i x)</tt> indents document <tt>x</tt> by <tt>i</tt>
--   columns, starting from the current cursor position.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = reflow "The indent function indents these words!"
--   
--   &gt;&gt;&gt; putDocW 24 ("prefix" &lt;&gt; indent 4 doc)
--   prefix    The indent
--             function
--             indents these
--             words!
--   </pre>
--   
--   <pre>
--   <a>indent</a> i d = <a>hang</a> i ({i spaces} &lt;&gt; d)
--   </pre>
indent :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>encloseSep</a> l r sep xs)</tt> concatenates the documents
--   <tt>xs</tt> separated by <tt>sep</tt>, and encloses the resulting
--   document by <tt>l</tt> and <tt>r</tt>.
--   
--   The documents are laid out horizontally if that fits the page:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "list" &lt;+&gt; align (encloseSep lbracket rbracket comma (map pretty [1,20,300,4000]))
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   list [1,20,300,4000]
--   </pre>
--   
--   If there is not enough space, then the input is split into lines
--   entry-wise therwise they are laid out vertically, with separators put
--   in the front:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   list [1
--        ,20
--        ,300
--        ,4000]
--   </pre>
--   
--   Note that <tt>doc</tt> contains an explicit call to <a>align</a> so
--   that the list items are aligned vertically.
--   
--   For putting separators at the end of entries instead, have a look at
--   <a>punctuate</a>.
encloseSep :: Doc ann -> Doc ann -> Doc ann -> [Doc ann] -> Doc ann

-- | Haskell-inspired variant of <a>encloseSep</a> with braces and comma as
--   separator.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = list (map pretty [1,20,300,4000])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 80 doc
--   [1, 20, 300, 4000]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   [ 1
--   , 20
--   , 300
--   , 4000 ]
--   </pre>
list :: [Doc ann] -> Doc ann

-- | Haskell-inspired variant of <a>encloseSep</a> with parentheses and
--   comma as separator.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = tupled (map pretty [1,20,300,4000])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 80 doc
--   (1, 20, 300, 4000)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   ( 1
--   , 20
--   , 300
--   , 4000 )
--   </pre>
tupled :: [Doc ann] -> Doc ann

-- | <tt>(x <a>&lt;+&gt;</a> y)</tt> concatenates document <tt>x</tt> and
--   <tt>y</tt> with a <tt><tt>space</tt></tt> in between.
--   
--   <pre>
--   &gt;&gt;&gt; "hello" &lt;+&gt; "world"
--   hello world
--   </pre>
--   
--   <pre>
--   x <a>&lt;+&gt;</a> y = x <a>&lt;&gt;</a> <tt>space</tt> <a>&lt;&gt;</a> y
--   </pre>
(<+>) :: Doc ann -> Doc ann -> Doc ann
infixr 6 <+>

-- | Concatenate all documents element-wise with a binary function.
--   
--   <pre>
--   <a>concatWith</a> _ [] = <a>mempty</a>
--   <a>concatWith</a> (**) [x,y,z] = x ** y ** z
--   </pre>
--   
--   Multiple convenience definitions based on <a>concatWith</a> are
--   already predefined, for example:
--   
--   <pre>
--   <a>hsep</a>    = <a>concatWith</a> (<a>&lt;+&gt;</a>)
--   <a>fillSep</a> = <a>concatWith</a> (\x y -&gt; x <a>&lt;&gt;</a> <a>softline</a> <a>&lt;&gt;</a> y)
--   </pre>
--   
--   This is also useful to define customized joiners:
--   
--   <pre>
--   &gt;&gt;&gt; concatWith (surround dot) ["Prettyprinter", "Render", "Text"]
--   Prettyprinter.Render.Text
--   </pre>
concatWith :: Foldable t => (Doc ann -> Doc ann -> Doc ann) -> t (Doc ann) -> Doc ann

-- | <tt>(<a>hsep</a> xs)</tt> concatenates all documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;+&gt;</a></tt>, i.e. it puts a space
--   between all entries.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor sit amet"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hsep docs
--   lorem ipsum dolor sit amet
--   </pre>
--   
--   <tt><a>hsep</a></tt> does not introduce line breaks on its own, even
--   when the page is too narrow:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 5 (hsep docs)
--   lorem ipsum dolor sit amet
--   </pre>
--   
--   For automatic line breaks, consider using <a>fillSep</a> instead.
hsep :: [Doc ann] -> Doc ann

-- | <tt>(<a>vsep</a> xs)</tt> concatenates all documents <tt>xs</tt> above
--   each other. If a <a>group</a> undoes the line breaks inserted by
--   <tt>vsep</tt>, the documents are separated with a <tt>space</tt>
--   instead.
--   
--   Using <a>vsep</a> alone yields
--   
--   <pre>
--   &gt;&gt;&gt; "prefix" &lt;+&gt; vsep ["text", "to", "lay", "out"]
--   prefix text
--   to
--   lay
--   out
--   </pre>
--   
--   <a>group</a>ing a <a>vsep</a> separates the documents with a
--   <tt>space</tt> if it fits the page (and does nothing otherwise). See
--   the <tt><a>sep</a></tt> convenience function for this use case.
--   
--   The <a>align</a> function can be used to align the documents under
--   their first element:
--   
--   <pre>
--   &gt;&gt;&gt; "prefix" &lt;+&gt; align (vsep ["text", "to", "lay", "out"])
--   prefix text
--          to
--          lay
--          out
--   </pre>
--   
--   Since <a>group</a>ing a <a>vsep</a> is rather common, <a>sep</a> is a
--   built-in for doing that.
vsep :: [Doc ann] -> Doc ann

-- | <tt>(<a>fillSep</a> xs)</tt> concatenates the documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;+&gt;</a></tt> as long as it fits the
--   page, then inserts a <tt><a>line</a></tt> and continues doing that for
--   all documents in <tt>xs</tt>. (<tt><a>line</a></tt> means that if
--   <a>group</a>ed, the documents are separated with a <tt>space</tt>
--   instead of newlines. Use <a>fillCat</a> if you do not want a
--   <tt>space</tt>.)
--   
--   Let's print some words to fill the line:
--   
--   <pre>
--   &gt;&gt;&gt; let docs = take 20 (cycle ["lorem", "ipsum", "dolor", "sit", "amet"])
--   
--   &gt;&gt;&gt; putDocW 80 ("Docs:" &lt;+&gt; fillSep docs)
--   Docs: lorem ipsum dolor sit amet lorem ipsum dolor sit amet lorem ipsum dolor
--   sit amet lorem ipsum dolor sit amet
--   </pre>
--   
--   The same document, printed at a width of only 40, yields
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 40 ("Docs:" &lt;+&gt; fillSep docs)
--   Docs: lorem ipsum dolor sit amet lorem
--   ipsum dolor sit amet lorem ipsum dolor
--   sit amet lorem ipsum dolor sit amet
--   </pre>
fillSep :: [Doc ann] -> Doc ann

-- | <tt>(<a>sep</a> xs)</tt> tries laying out the documents <tt>xs</tt>
--   separated with <tt>space</tt>s, and if this does not fit the page,
--   separates them with newlines. This is what differentiates it from
--   <a>vsep</a>, which always lays out its contents beneath each other.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; sep ["text", "to", "lay", "out"]
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   prefix text to lay out
--   </pre>
--   
--   With a narrower layout, the entries are separated by newlines:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 20 doc
--   prefix text
--   to
--   lay
--   out
--   </pre>
--   
--   <pre>
--   <a>sep</a> = <a>group</a> . <a>vsep</a>
--   </pre>
sep :: [Doc ann] -> Doc ann

-- | <tt>(<a>hcat</a> xs)</tt> concatenates all documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;&gt;</a></tt> (i.e. without any spacing).
--   
--   It is provided only for consistency, since it is identical to
--   <a>mconcat</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor"
--   
--   &gt;&gt;&gt; hcat docs
--   loremipsumdolor
--   </pre>
hcat :: [Doc ann] -> Doc ann

-- | <tt>(<a>vcat</a> xs)</tt> vertically concatenates the documents
--   <tt>xs</tt>. If it is <a>group</a>ed, the line breaks are removed.
--   
--   In other words <tt><a>vcat</a></tt> is like <tt><a>vsep</a></tt>, with
--   newlines removed instead of replaced by <tt>space</tt>s.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor"
--   
--   &gt;&gt;&gt; vcat docs
--   lorem
--   ipsum
--   dolor
--   
--   &gt;&gt;&gt; group (vcat docs)
--   loremipsumdolor
--   </pre>
--   
--   Since <a>group</a>ing a <a>vcat</a> is rather common, <a>cat</a> is a
--   built-in shortcut for it.
vcat :: [Doc ann] -> Doc ann

-- | <tt>(<a>fillCat</a> xs)</tt> concatenates documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;&gt;</a></tt> as long as it fits the
--   page, then inserts a <tt><a>line'</a></tt> and continues doing that
--   for all documents in <tt>xs</tt>. This is similar to how an ordinary
--   word processor lays out the text if you just keep typing after you hit
--   the maximum line length.
--   
--   (<tt><a>line'</a></tt> means that if <a>group</a>ed, the documents are
--   separated with nothing instead of newlines. See <a>fillSep</a> if you
--   want a <tt>space</tt> instead.)
--   
--   Observe the difference between <a>fillSep</a> and <a>fillCat</a>.
--   <a>fillSep</a> concatenates the entries <tt>space</tt>d when
--   <a>group</a>ed:
--   
--   <pre>
--   &gt;&gt;&gt; let docs = take 20 (cycle (["lorem", "ipsum", "dolor", "sit", "amet"]))
--   
--   &gt;&gt;&gt; putDocW 40 ("Grouped:" &lt;+&gt; group (fillSep docs))
--   Grouped: lorem ipsum dolor sit amet
--   lorem ipsum dolor sit amet lorem ipsum
--   dolor sit amet lorem ipsum dolor sit
--   amet
--   </pre>
--   
--   On the other hand, <a>fillCat</a> concatenates the entries directly
--   when <a>group</a>ed:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 40 ("Grouped:" &lt;+&gt; group (fillCat docs))
--   Grouped: loremipsumdolorsitametlorem
--   ipsumdolorsitametloremipsumdolorsitamet
--   loremipsumdolorsitamet
--   </pre>
fillCat :: [Doc ann] -> Doc ann

-- | <tt>(<a>cat</a> xs)</tt> tries laying out the documents <tt>xs</tt>
--   separated with nothing, and if this does not fit the page, separates
--   them with newlines. This is what differentiates it from <a>vcat</a>,
--   which always lays out its contents beneath each other.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor"
--   
--   &gt;&gt;&gt; putDocW 80 ("Docs:" &lt;+&gt; cat docs)
--   Docs: loremipsumdolor
--   </pre>
--   
--   When there is enough space, the documents are put above one another:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 ("Docs:" &lt;+&gt; cat docs)
--   Docs: lorem
--   ipsum
--   dolor
--   </pre>
--   
--   <pre>
--   <a>cat</a> = <a>group</a> . <a>vcat</a>
--   </pre>
cat :: [Doc ann] -> Doc ann

-- | <tt>(<a>punctuate</a> p xs)</tt> appends <tt>p</tt> to all but the
--   last document in <tt>xs</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = punctuate comma (Util.words "lorem ipsum dolor sit amet")
--   
--   &gt;&gt;&gt; putDocW 80 (hsep docs)
--   lorem, ipsum, dolor, sit, amet
--   </pre>
--   
--   The separators are put at the end of the entries, which we can see if
--   we position the result vertically:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 20 (vsep docs)
--   lorem,
--   ipsum,
--   dolor,
--   sit,
--   amet
--   </pre>
--   
--   If you want put the commas in front of their elements instead of at
--   the end, you should use <a>tupled</a> or, in general,
--   <a>encloseSep</a>.
punctuate :: Doc ann -> [Doc ann] -> [Doc ann]

-- | Layout a document depending on which column it starts at. <a>align</a>
--   is implemented in terms of <a>column</a>.
--   
--   <pre>
--   &gt;&gt;&gt; column (\l -&gt; "Columns are" &lt;+&gt; pretty l &lt;&gt; "-based.")
--   Columns are 0-based.
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; column (\l -&gt; "| &lt;- column" &lt;+&gt; pretty l)
--   
--   &gt;&gt;&gt; vsep [indent n doc | n &lt;- [0,4,8]]
--   prefix | &lt;- column 7
--       prefix | &lt;- column 11
--           prefix | &lt;- column 15
--   </pre>
column :: (Int -> Doc ann) -> Doc ann

-- | Layout a document depending on the current <a>nest</a>ing level.
--   <a>align</a> is implemented in terms of <a>nesting</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; nesting (\l -&gt; brackets ("Nested:" &lt;+&gt; pretty l))
--   
--   &gt;&gt;&gt; vsep [indent n doc | n &lt;- [0,4,8]]
--   prefix [Nested: 0]
--       prefix [Nested: 4]
--           prefix [Nested: 8]
--   </pre>
nesting :: (Int -> Doc ann) -> Doc ann

-- | <tt>(<a>width</a> doc f)</tt> lays out the document <tt>doc</tt>, and
--   makes the column width of it available to a function.
--   
--   <pre>
--   &gt;&gt;&gt; let annotate doc = width (brackets doc) (\w -&gt; " &lt;- width:" &lt;+&gt; pretty w)
--   
--   &gt;&gt;&gt; align (vsep (map annotate ["---", "------", indent 3 "---", vsep ["---", indent 4 "---"]]))
--   [---] &lt;- width: 5
--   [------] &lt;- width: 8
--   [   ---] &lt;- width: 8
--   [---
--       ---] &lt;- width: 8
--   </pre>
width :: Doc ann -> (Int -> Doc ann) -> Doc ann

-- | Layout a document depending on the page width, if one has been
--   specified.
--   
--   <pre>
--   &gt;&gt;&gt; let prettyPageWidth (AvailablePerLine l r) = "Width:" &lt;+&gt; pretty l &lt;&gt; ", ribbon fraction:" &lt;+&gt; pretty r
--   
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; pageWidth (brackets . prettyPageWidth)
--   
--   &gt;&gt;&gt; putDocW 32 (vsep [indent n doc | n &lt;- [0,4,8]])
--   prefix [Width: 32, ribbon fraction: 1.0]
--       prefix [Width: 32, ribbon fraction: 1.0]
--           prefix [Width: 32, ribbon fraction: 1.0]
--   </pre>
pageWidth :: (PageWidth -> Doc ann) -> Doc ann

-- | <tt>(<a>fill</a> i x)</tt> lays out the document <tt>x</tt>. It then
--   appends <tt>space</tt>s until the width is equal to <tt>i</tt>. If the
--   width of <tt>x</tt> is already larger, nothing is appended.
--   
--   This function is quite useful in practice to output a list of
--   bindings:
--   
--   <pre>
--   &gt;&gt;&gt; let types = [("empty","Doc"), ("nest","Int -&gt; Doc -&gt; Doc"), ("fillSep","[Doc] -&gt; Doc")]
--   
--   &gt;&gt;&gt; let ptype (name, tp) = fill 5 (pretty name) &lt;+&gt; "::" &lt;+&gt; pretty tp
--   
--   &gt;&gt;&gt; "let" &lt;+&gt; align (vcat (map ptype types))
--   let empty :: Doc
--       nest  :: Int -&gt; Doc -&gt; Doc
--       fillSep :: [Doc] -&gt; Doc
--   </pre>
fill :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>fillBreak</a> i x)</tt> first lays out the document
--   <tt>x</tt>. It then appends <tt>space</tt>s until the width is equal
--   to <tt>i</tt>. If the width of <tt>x</tt> is already larger than
--   <tt>i</tt>, the nesting level is increased by <tt>i</tt> and a
--   <tt>line</tt> is appended. When we redefine <tt>ptype</tt> in the
--   example given in <a>fill</a> to use <tt><a>fillBreak</a></tt>, we get
--   a useful variation of the output:
--   
--   <pre>
--   &gt;&gt;&gt; let types = [("empty","Doc"), ("nest","Int -&gt; Doc -&gt; Doc"), ("fillSep","[Doc] -&gt; Doc")]
--   
--   &gt;&gt;&gt; let ptype (name, tp) = fillBreak 5 (pretty name) &lt;+&gt; "::" &lt;+&gt; pretty tp
--   
--   &gt;&gt;&gt; "let" &lt;+&gt; align (vcat (map ptype types))
--   let empty :: Doc
--       nest  :: Int -&gt; Doc -&gt; Doc
--       fillSep
--             :: [Doc] -&gt; Doc
--   </pre>
fillBreak :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>plural</a> n one many)</tt> is <tt>one</tt> if <tt>n</tt> is
--   <tt>1</tt>, and <tt>many</tt> otherwise. A typical use case is adding
--   a plural "s".
--   
--   <pre>
--   &gt;&gt;&gt; let things = [True]
--   
--   &gt;&gt;&gt; let amount = length things
--   
--   &gt;&gt;&gt; pretty things &lt;+&gt; "has" &lt;+&gt; pretty amount &lt;+&gt; plural "entry" "entries" amount
--   [True] has 1 entry
--   </pre>
plural :: (Num amount, Eq amount) => doc -> doc -> amount -> doc

-- | <tt>(<a>enclose</a> l r x)</tt> encloses document <tt>x</tt> between
--   documents <tt>l</tt> and <tt>r</tt> using <tt><a>&lt;&gt;</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; enclose "A" "Z" "·"
--   A·Z
--   </pre>
--   
--   <pre>
--   <a>enclose</a> l r x = l <a>&lt;&gt;</a> x <a>&lt;&gt;</a> r
--   </pre>
enclose :: Doc ann -> Doc ann -> Doc ann -> Doc ann

-- | <tt>(<a>surround</a> x l r)</tt> surrounds document <tt>x</tt> with
--   <tt>l</tt> and <tt>r</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; surround "·" "A" "Z"
--   A·Z
--   </pre>
--   
--   This is merely an argument reordering of <tt><a>enclose</a></tt>, but
--   allows for definitions like
--   
--   <pre>
--   &gt;&gt;&gt; concatWith (surround dot) ["Prettyprinter", "Render", "Text"]
--   Prettyprinter.Render.Text
--   </pre>
surround :: Doc ann -> Doc ann -> Doc ann -> Doc ann

-- | Add an annotation to a <tt><a>Doc</a></tt>. This annotation can then
--   be used by the renderer to e.g. add color to certain parts of the
--   output. For a full tutorial example on how to use it, see the
--   <a>Prettyprinter.Render.Tutorials.StackMachineTutorial</a> or
--   <a>Prettyprinter.Render.Tutorials.TreeRenderingTutorial</a> modules.
--   
--   This function is only relevant for custom formats with their own
--   annotations, and not relevant for basic prettyprinting. The predefined
--   renderers, e.g. <a>Prettyprinter.Render.Text</a>, should be enough for
--   the most common needs.
annotate :: ann -> Doc ann -> Doc ann

-- | Remove all annotations.
--   
--   Although <a>unAnnotate</a> is idempotent with respect to rendering,
--   
--   <pre>
--   <a>unAnnotate</a> . <a>unAnnotate</a> = <a>unAnnotate</a>
--   </pre>
--   
--   it should not be used without caution, for each invocation traverses
--   the entire contained document. If possible, it is preferrable to
--   unannotate after producing the layout by using <a>unAnnotateS</a>.
unAnnotate :: Doc ann -> Doc xxx

-- | Change the annotation of a <a>Doc</a>ument.
--   
--   Useful in particular to embed documents with one form of annotation in
--   a more generally annotated document.
--   
--   Since this traverses the entire <tt><a>Doc</a></tt> tree, including
--   parts that are not rendered due to other layouts fitting better, it is
--   preferrable to reannotate after producing the layout by using
--   <tt><a>reAnnotateS</a></tt>.
--   
--   Since <tt><a>reAnnotate</a></tt> has the right type and satisfies
--   <tt>'reAnnotate id = id'</tt>, it is used to define the
--   <tt><a>Functor</a></tt> instance of <tt><a>Doc</a></tt>.
reAnnotate :: (ann -> ann') -> Doc ann -> Doc ann'

-- | Change the annotations of a <a>Doc</a>ument. Individual annotations
--   can be removed, changed, or replaced by multiple ones.
--   
--   This is a general function that combines <a>unAnnotate</a> and
--   <a>reAnnotate</a>, and it is useful for mapping semantic annotations
--   (such as »this is a keyword«) to display annotations (such as »this is
--   red and underlined«), because some backends may not care about certain
--   annotations, while others may.
--   
--   Annotations earlier in the new list will be applied earlier, i.e.
--   returning <tt>[Bold, Green]</tt> will result in a bold document that
--   contains green text, and not vice-versa.
--   
--   Since this traverses the entire <tt><a>Doc</a></tt> tree, including
--   parts that are not rendered due to other layouts fitting better, it is
--   preferrable to reannotate after producing the layout by using
--   <tt><a>alterAnnotationsS</a></tt>.
alterAnnotations :: (ann -> [ann']) -> Doc ann -> Doc ann'

-- | Remove all annotations. <a>unAnnotate</a> for <a>SimpleDocStream</a>.
unAnnotateS :: SimpleDocStream ann -> SimpleDocStream xxx

-- | Change the annotation of a document. <a>reAnnotate</a> for
--   <a>SimpleDocStream</a>.
reAnnotateS :: (ann -> ann') -> SimpleDocStream ann -> SimpleDocStream ann'

-- | Change the annotation of a document to a different annotation, or none
--   at all. <a>alterAnnotations</a> for <a>SimpleDocStream</a>.
--   
--   Note that the <a>Doc</a> version is more flexible, since it allows
--   changing a single annotation to multiple ones. (<a>SimpleDocTree</a>
--   restores this flexibility again.)
alterAnnotationsS :: (ann -> Maybe ann') -> SimpleDocStream ann -> SimpleDocStream ann'

-- | <tt>(<a>fuse</a> depth doc)</tt> combines text nodes so they can be
--   rendered more efficiently. A fused document is always laid out
--   identical to its unfused version.
--   
--   When laying a <a>Doc</a>ument out to a <a>SimpleDocStream</a>, every
--   component of the input is translated directly to the simpler output
--   format. This sometimes yields undesirable chunking when many pieces
--   have been concatenated together.
--   
--   For example
--   
--   <pre>
--   &gt;&gt;&gt; "a" &lt;&gt; "b" &lt;&gt; pretty 'c' &lt;&gt; "d"
--   abcd
--   </pre>
--   
--   results in a chain of four entries in a <a>SimpleDocStream</a>,
--   although this is fully equivalent to the tightly packed
--   
--   <pre>
--   &gt;&gt;&gt; "abcd" :: Doc ann
--   abcd
--   </pre>
--   
--   which is only a single <a>SimpleDocStream</a> entry, and can be
--   processed faster.
--   
--   It is therefore a good idea to run <a>fuse</a> on concatenations of
--   lots of small strings that are used many times:
--   
--   <pre>
--   &gt;&gt;&gt; let oftenUsed = fuse Shallow ("a" &lt;&gt; "b" &lt;&gt; pretty 'c' &lt;&gt; "d")
--   
--   &gt;&gt;&gt; hsep (replicate 5 oftenUsed)
--   abcd abcd abcd abcd abcd
--   </pre>
fuse :: FusionDepth -> Doc ann -> Doc ann

-- | Fusion depth parameter, used by <a>fuse</a>.
data FusionDepth

-- | Do not dive deep into nested documents, fusing mostly concatenations
--   of text nodes together.
Shallow :: FusionDepth

-- | Recurse into all parts of the <a>Doc</a>, including different layout
--   alternatives, and location-sensitive values such as created by
--   <a>nesting</a> which cannot be fused before, but only during, the
--   layout process. As a result, the performance cost of using deep fusion
--   is often hard to predict, and depends on the interplay between page
--   layout and document to prettyprint.
--   
--   This value should only be used if profiling shows it is significantly
--   faster than using <a>Shallow</a>.
Deep :: FusionDepth

-- | The data type <tt>SimpleDocStream</tt> represents laid out documents
--   and is used by the display functions.
--   
--   A simplified view is that <tt><a>Doc</a> =
--   [<a>SimpleDocStream</a>]</tt>, and the layout functions pick one of
--   the <a>SimpleDocStream</a>s based on which one fits the layout
--   constraints best. This means that <a>SimpleDocStream</a> has all
--   complexity contained in <a>Doc</a> resolved, making it very easy to
--   convert it to other formats, such as plain text or terminal output.
--   
--   To write your own <tt><a>Doc</a></tt> to X converter, it is therefore
--   sufficient to convert from <tt><a>SimpleDocStream</a></tt>. The
--   »Render« submodules provide some built-in converters to do so, and
--   helpers to create own ones.
data SimpleDocStream ann
SFail :: SimpleDocStream ann
SEmpty :: SimpleDocStream ann
SChar :: !Char -> SimpleDocStream ann -> SimpleDocStream ann

-- | <a>length</a> is <i>O(n)</i>, so we cache it in the <a>Int</a> field.
SText :: !Int -> !Text -> SimpleDocStream ann -> SimpleDocStream ann

-- | <tt>Int</tt> = indentation level for the (next) line
SLine :: !Int -> SimpleDocStream ann -> SimpleDocStream ann

-- | Add an annotation to the remaining document.
SAnnPush :: ann -> SimpleDocStream ann -> SimpleDocStream ann

-- | Remove a previously pushed annotation.
SAnnPop :: SimpleDocStream ann -> SimpleDocStream ann

-- | Maximum number of characters that fit in one line. The layout
--   algorithms will try not to exceed the set limit by inserting line
--   breaks when applicable (e.g. via <a>softline'</a>).
data PageWidth

-- | Layouters should not exceed the specified space per line.
--   
--   <ul>
--   <li>The <a>Int</a> is the number of characters, including whitespace,
--   that fit in a line. A typical value is 80.</li>
--   <li>The <a>Double</a> is the ribbon with, i.e. the fraction of the
--   total page width that can be printed on. This allows limiting the
--   length of printable text per line. Values must be between 0 and 1, and
--   0.4 to 1 is typical.</li>
--   </ul>
AvailablePerLine :: !Int -> !Double -> PageWidth

-- | Layouters should not introduce line breaks on their own.
Unbounded :: PageWidth
defaultPageWidth :: PageWidth

-- | Options to influence the layout algorithms.
newtype LayoutOptions
LayoutOptions :: PageWidth -> LayoutOptions
[layoutPageWidth] :: LayoutOptions -> PageWidth

-- | The default layout options, suitable when you just want some output,
--   and don’t particularly care about the details. Used by the <a>Show</a>
--   instance, for example.
--   
--   <pre>
--   &gt;&gt;&gt; defaultLayoutOptions
--   LayoutOptions {layoutPageWidth = AvailablePerLine 80 1.0}
--   </pre>
defaultLayoutOptions :: LayoutOptions

-- | This is the default layout algorithm, and it is used by <a>show</a>,
--   <tt>putDoc</tt> and <tt>hPutDoc</tt>.
--   
--   <tt><a>layoutPretty</a></tt> commits to rendering something in a
--   certain way if the next element fits the layout constraints; in other
--   words, it has one <a>SimpleDocStream</a> element lookahead when
--   rendering. Consider using the smarter, but a bit less performant,
--   <tt><a>layoutSmart</a></tt> algorithm if the results seem to run off
--   to the right before having lots of line breaks.
layoutPretty :: LayoutOptions -> Doc ann -> SimpleDocStream ann

-- | <tt>(layoutCompact x)</tt> lays out the document <tt>x</tt> without
--   adding any indentation and without preserving annotations. Since no
--   'pretty' printing is involved, this layouter is very fast. The
--   resulting output contains fewer characters than a prettyprinted
--   version and can be used for output that is read by other programs.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = hang 4 (vsep ["lorem", "ipsum", hang 4 (vsep ["dolor", "sit"])])
--   
--   &gt;&gt;&gt; doc
--   lorem
--       ipsum
--       dolor
--           sit
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let putDocCompact = renderIO System.IO.stdout . layoutCompact
--   
--   &gt;&gt;&gt; putDocCompact doc
--   lorem
--   ipsum
--   dolor
--   sit
--   </pre>
layoutCompact :: Doc ann1 -> SimpleDocStream ann2

-- | A layout algorithm with more lookahead than <a>layoutPretty</a>, that
--   introduces line breaks earlier if the content does not (or will not,
--   rather) fit into one line.
--   
--   Consider the following python-ish document,
--   
--   <pre>
--   &gt;&gt;&gt; let fun x = hang 2 ("fun(" &lt;&gt; softline' &lt;&gt; x) &lt;&gt; ")"
--   
--   &gt;&gt;&gt; let doc = (fun . fun . fun . fun . fun) (align (list ["abcdef", "ghijklm"]))
--   </pre>
--   
--   which we’ll be rendering using the following pipeline (where the
--   layout algorithm has been left open):
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Text.IO as T
--   
--   &gt;&gt;&gt; import Prettyprinter.Render.Text
--   
--   &gt;&gt;&gt; let hr = pipe &lt;&gt; pretty (replicate (26-2) '-') &lt;&gt; pipe
--   
--   &gt;&gt;&gt; let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
--   </pre>
--   
--   If we render this using <a>layoutPretty</a> with a page width of 26
--   characters per line, all the <tt>fun</tt> calls fit into the first
--   line so they will be put there:
--   
--   <pre>
--   &gt;&gt;&gt; go layoutPretty doc
--   |------------------------|
--   fun(fun(fun(fun(fun(
--                     [ abcdef
--                     , ghijklm ])))))
--   |------------------------|
--   </pre>
--   
--   Note that this exceeds the desired 26 character page width. The same
--   document, rendered with <tt><a>layoutSmart</a></tt>, fits the layout
--   contstraints:
--   
--   <pre>
--   &gt;&gt;&gt; go layoutSmart doc
--   |------------------------|
--   fun(
--     fun(
--       fun(
--         fun(
--           fun(
--             [ abcdef
--             , ghijklm ])))))
--   |------------------------|
--   </pre>
--   
--   The key difference between <a>layoutPretty</a> and <a>layoutSmart</a>
--   is that the latter will check the potential document until it
--   encounters a line with the same indentation or less than the start of
--   the document. Any line encountered earlier is assumed to belong to the
--   same syntactic structure. <a>layoutPretty</a> checks only the first
--   line.
--   
--   Consider for example the question of whether the <tt>A</tt>s fit into
--   the document below:
--   
--   <pre>
--   1 A
--   2   A
--   3  A
--   4 B
--   5   B
--   </pre>
--   
--   <a>layoutPretty</a> will check only line 1, ignoring whether e.g. line
--   2 might already be too wide. By contrast, <a>layoutSmart</a> stops
--   only once it reaches line 4, where the <tt>B</tt> has the same
--   indentation as the first <tt>A</tt>.
layoutSmart :: LayoutOptions -> Doc ann -> SimpleDocStream ann

-- | Remove all trailing space characters.
--   
--   This has some performance impact, because it does an entire additional
--   pass over the <a>SimpleDocStream</a>.
--   
--   No trimming will be done inside annotations, which are considered to
--   contain no (trimmable) whitespace, since the annotation might actually
--   be <i>about</i> the whitespace, for example a renderer that colors the
--   background of trailing whitespace, as e.g. <tt>git diff</tt> can be
--   configured to do.
--   
--   <i>Historical note:</i> Since v1.7.0, <a>layoutPretty</a> and
--   <a>layoutSmart</a> avoid producing the trailing whitespace that was
--   the original motivation for creating <a>removeTrailingWhitespace</a>.
--   See <a>https://github.com/quchen/prettyprinter/pull/139</a> for some
--   background info.
removeTrailingWhitespace :: SimpleDocStream ann -> SimpleDocStream ann

-- | Render a <a>SimpleDocStream</a> to a <a>ShowS</a>, useful to write
--   <a>Show</a> instances based on the prettyprinter.
--   
--   <pre>
--   instance <a>Show</a> MyType where
--       <a>showsPrec</a> _ = <a>renderShowS</a> . <a>layoutPretty</a> <a>defaultLayoutOptions</a> . <a>pretty</a>
--   </pre>
renderShowS :: SimpleDocStream ann -> ShowS

-- | A utility for producing indentation etc.
--   
--   <pre>
--   &gt;&gt;&gt; textSpaces 3
--   "   "
--   </pre>
--   
--   This produces much better Core than the equivalent
--   
--   <pre>
--   T.replicate n " "
--   </pre>
--   
--   (See <a>https://github.com/quchen/prettyprinter/issues/131</a>.)
textSpaces :: Int -> Text
instance GHC.Classes.Eq Prettyprinter.Internal.FusionDepth
instance GHC.Classes.Eq Prettyprinter.Internal.LayoutOptions
instance GHC.Classes.Eq Prettyprinter.Internal.PageWidth
instance GHC.Classes.Eq ann => GHC.Classes.Eq (Prettyprinter.Internal.SimpleDocStream ann)
instance GHC.Internal.Data.Foldable.Foldable Prettyprinter.Internal.SimpleDocStream
instance GHC.Internal.Base.Functor Prettyprinter.Internal.Doc
instance GHC.Internal.Base.Functor Prettyprinter.Internal.FlattenResult
instance GHC.Internal.Base.Functor Prettyprinter.Internal.SimpleDocStream
instance GHC.Internal.Generics.Generic (Prettyprinter.Internal.Doc ann)
instance GHC.Internal.Generics.Generic (Prettyprinter.Internal.SimpleDocStream ann)
instance GHC.Internal.Data.String.IsString (Prettyprinter.Internal.Doc ann)
instance GHC.Internal.Base.Monoid (Prettyprinter.Internal.Doc ann)
instance GHC.Classes.Ord Prettyprinter.Internal.FusionDepth
instance GHC.Classes.Ord Prettyprinter.Internal.LayoutOptions
instance GHC.Classes.Ord Prettyprinter.Internal.PageWidth
instance GHC.Classes.Ord ann => GHC.Classes.Ord (Prettyprinter.Internal.SimpleDocStream ann)
instance Prettyprinter.Internal.Pretty GHC.Types.Bool
instance Prettyprinter.Internal.Pretty GHC.Types.Char
instance Prettyprinter.Internal.Pretty a => Prettyprinter.Internal.Pretty (GHC.Internal.Data.Functor.Const.Const a b)
instance Prettyprinter.Internal.Pretty GHC.Types.Double
instance Prettyprinter.Internal.Pretty GHC.Types.Float
instance Prettyprinter.Internal.Pretty a => Prettyprinter.Internal.Pretty (GHC.Internal.Data.Functor.Identity.Identity a)
instance Prettyprinter.Internal.Pretty GHC.Types.Int
instance Prettyprinter.Internal.Pretty GHC.Internal.Int.Int16
instance Prettyprinter.Internal.Pretty GHC.Internal.Int.Int32
instance Prettyprinter.Internal.Pretty GHC.Internal.Int.Int64
instance Prettyprinter.Internal.Pretty GHC.Internal.Int.Int8
instance Prettyprinter.Internal.Pretty GHC.Num.Integer.Integer
instance Prettyprinter.Internal.Pretty a => Prettyprinter.Internal.Pretty [a]
instance Prettyprinter.Internal.Pretty a => Prettyprinter.Internal.Pretty (GHC.Internal.Maybe.Maybe a)
instance Prettyprinter.Internal.Pretty GHC.Num.Natural.Natural
instance Prettyprinter.Internal.Pretty a => Prettyprinter.Internal.Pretty (GHC.Internal.Base.NonEmpty a)
instance Prettyprinter.Internal.Pretty Data.Text.Internal.Lazy.Text
instance Prettyprinter.Internal.Pretty Data.Text.Internal.Text
instance (Prettyprinter.Internal.Pretty a1, Prettyprinter.Internal.Pretty a2) => Prettyprinter.Internal.Pretty (a1, a2)
instance (Prettyprinter.Internal.Pretty a1, Prettyprinter.Internal.Pretty a2, Prettyprinter.Internal.Pretty a3) => Prettyprinter.Internal.Pretty (a1, a2, a3)
instance Prettyprinter.Internal.Pretty ()
instance Prettyprinter.Internal.Pretty GHC.Internal.Base.Void
instance Prettyprinter.Internal.Pretty GHC.Types.Word
instance Prettyprinter.Internal.Pretty GHC.Internal.Word.Word16
instance Prettyprinter.Internal.Pretty GHC.Internal.Word.Word32
instance Prettyprinter.Internal.Pretty GHC.Internal.Word.Word64
instance Prettyprinter.Internal.Pretty GHC.Internal.Word.Word8
instance GHC.Internal.Base.Semigroup (Prettyprinter.Internal.Doc ann)
instance GHC.Internal.Show.Show (Prettyprinter.Internal.Doc ann)
instance GHC.Internal.Show.Show Prettyprinter.Internal.FusionDepth
instance GHC.Internal.Show.Show Prettyprinter.Internal.LayoutOptions
instance GHC.Internal.Show.Show Prettyprinter.Internal.PageWidth
instance GHC.Internal.Show.Show ann => GHC.Internal.Show.Show (Prettyprinter.Internal.SimpleDocStream ann)
instance GHC.Internal.Data.Traversable.Traversable Prettyprinter.Internal.SimpleDocStream

module Prettyprinter.Render.String

-- | Render a <a>SimpleDocStream</a> to a <a>String</a>.
renderString :: SimpleDocStream ann -> String

-- | Render a <a>SimpleDocStream</a> to a <a>ShowS</a>, useful to write
--   <a>Show</a> instances based on the prettyprinter.
--   
--   <pre>
--   instance <a>Show</a> MyType where
--       <a>showsPrec</a> _ = <a>renderShowS</a> . <a>layoutPretty</a> <a>defaultLayoutOptions</a> . <a>pretty</a>
--   </pre>
renderShowS :: SimpleDocStream ann -> ShowS


-- | <i>Deprecated: Use <a>Prettyprinter.Render.String</a> instead.</i>
module Data.Text.Prettyprint.Doc.Render.String


-- | <b>Internal module with stability guarantees</b>
--   
--   This module exposes the internals of the <tt><a>Doc</a></tt> type so
--   other libraries can write adaptors to/from it. For all other uses,
--   please use only the API provided by non-internal modules.
--   
--   Although this module is internal, it follows the usual package
--   versioning policy, AKA Haskell’s version of semantic versioning. In
--   other words, this module is as stable as the public API.
module Prettyprinter.Internal.Type

-- | The abstract data type <tt><a>Doc</a> ann</tt> represents pretty
--   documents that have been annotated with data of type <tt>ann</tt>.
--   
--   More specifically, a value of type <tt><a>Doc</a></tt> represents a
--   non-empty set of possible layouts of a document. The layout functions
--   select one of these possibilities, taking into account things like the
--   width of the output document.
--   
--   The annotation is an arbitrary piece of data associated with (part of)
--   a document. Annotations may be used by the rendering backends in order
--   to display output differently, such as
--   
--   <ul>
--   <li>color information (e.g. when rendering to the terminal)</li>
--   <li>mouseover text (e.g. when rendering to rich HTML)</li>
--   <li>whether to show something or not (to allow simple or detailed
--   versions)</li>
--   </ul>
--   
--   The simplest way to display a <a>Doc</a> is via the <a>Show</a> class.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn (show (vsep ["hello", "world"]))
--   hello
--   world
--   </pre>
data Doc ann

-- | Occurs when flattening a line. The layouter will reject this document,
--   choosing a more suitable rendering.
Fail :: Doc ann

-- | The empty document; conceptually the unit of <a>Cat</a>
Empty :: Doc ann

-- | invariant: not 'n'
Char :: !Char -> Doc ann

-- | Invariants: at least two characters long, does not contain 'n'. For
--   empty documents, there is <tt>Empty</tt>; for singleton documents,
--   there is <tt>Char</tt>; newlines should be replaced by e.g.
--   <tt>Line</tt>.
--   
--   Since the frequently used <a>length</a> of <a>Text</a> is
--   <i>O(length)</i>, we cache it in this constructor.
Text :: !Int -> !Text -> Doc ann

-- | Hard line break
Line :: Doc ann

-- | Lay out the first <a>Doc</a>, but when flattened (via <a>group</a>),
--   prefer the second.
--   
--   The layout algorithms work under the assumption that the first
--   alternative is less wide than the flattened second alternative.
FlatAlt :: Doc ann -> Doc ann -> Doc ann

-- | Concatenation of two documents
Cat :: Doc ann -> Doc ann -> Doc ann

-- | Document indented by a number of columns
Nest :: !Int -> Doc ann -> Doc ann

-- | Invariant: The first lines of first document should be longer than the
--   first lines of the second one, so the layout algorithm can pick the
--   one that fits best. Used to implement layout alternatives for
--   <a>group</a>.
Union :: Doc ann -> Doc ann -> Doc ann

-- | React on the current cursor position, see <a>column</a>
Column :: (Int -> Doc ann) -> Doc ann

-- | React on the document's width, see <a>pageWidth</a>
WithPageWidth :: (PageWidth -> Doc ann) -> Doc ann

-- | React on the current nesting level, see <a>nesting</a>
Nesting :: (Int -> Doc ann) -> Doc ann

-- | Add an annotation to the enclosed <a>Doc</a>. Can be used for example
--   to add styling directives or alt texts that can then be used by the
--   renderer.
Annotated :: ann -> Doc ann -> Doc ann


-- | <i>Deprecated: Use <a>Prettyprinter.Internal.Type</a> instead.</i>
module Data.Text.Prettyprint.Doc.Internal.Type


-- | <b>Warning: internal module!</b> This means that the API may change
--   arbitrarily between versions without notice. Depending on this module
--   may lead to unexpected breakages, so proceed with caution!
--   
--   This module provides debugging helpers for inspecting <a>Doc</a>s.
--   
--   Use the <tt>pretty-simple</tt> package to get a nicer layout for
--   <a>show</a>n <a>Diag</a>s:
--   
--   <pre>
--   &gt; Text.Pretty.Simple.pPrintNoColor . diag $ align (vcat ["foo", "bar"])
--   Column
--      [
--          ( 10
--          , Nesting
--              [
--                  ( 10
--                  , Cat ( Text 3 "foo" )
--                      ( Cat ( FlatAlt Line Empty ) ( Text 3 "bar" ) )
--                  )
--              ]
--          )
--      ]
--   </pre>
module Prettyprinter.Internal.Debug

-- | A variant of <a>Doc</a> for debugging.
--   
--   Unlike in the <a>Doc</a> type, the <a>Column</a>, <a>WithPageWidth</a>
--   and <a>Nesting</a> constructors don't contain functions but are
--   "sampled" to allow simple inspection with <a>show</a>.
data Diag ann
Fail :: Diag ann
Empty :: Diag ann
Char :: !Char -> Diag ann
Text :: !Int -> !Text -> Diag ann
Line :: Diag ann
FlatAlt :: Diag ann -> Diag ann -> Diag ann
Cat :: Diag ann -> Diag ann -> Diag ann
Nest :: !Int -> Diag ann -> Diag ann
Union :: Diag ann -> Diag ann -> Diag ann

-- | <a>Doc</a>: <tt>(Int -&gt; Diag ann)</tt>
Column :: [(Int, Diag ann)] -> Diag ann

-- | <a>Doc</a>: <tt>(PageWidth -&gt; Diag ann)</tt>
WithPageWidth :: [(PageWidth, Diag ann)] -> Diag ann

-- | <a>Doc</a>: <tt>(Int -&gt; Diag ann)</tt>
Nesting :: [(Int, Diag ann)] -> Diag ann
Annotated :: ann -> Diag ann -> Diag ann

-- | Convert a <a>Doc</a> to its diagnostic representation.
--   
--   The functions in the <a>Column</a>, <a>WithPageWidth</a> and
--   <a>Nesting</a> constructors are sampled with some default values.
--   
--   Use <a>diag'</a> to control the function inputs yourself.
--   
--   <pre>
--   &gt;&gt;&gt; diag $ Doc.align (Doc.vcat ["foo", "bar"])
--   Column [(10,Nesting [(10,Cat (Text 3 "foo") (Cat (FlatAlt Line Empty) (Text 3 "bar")))])]
--   </pre>
diag :: Doc ann -> Diag ann
diag' :: [Int] -> [PageWidth] -> [Int] -> Doc ann -> Diag ann
instance GHC.Internal.Show.Show ann => GHC.Internal.Show.Show (Prettyprinter.Internal.Debug.Diag ann)


-- | <i>Deprecated: Use <a>Prettyprinter.Internal.Debug</a> instead.</i>
module Data.Text.Prettyprint.Doc.Internal.Debug


-- | <i>Deprecated: Use <a>Prettyprinter.Internal</a> instead.</i>
module Data.Text.Prettyprint.Doc.Internal


-- | <i>Deprecated: Use <a>Prettyprinter.Render.Util.Panic</a> instead.</i>
module Data.Text.Prettyprint.Doc.Render.Util.Panic


-- | Definitions to write renderers based on looking at a
--   <a>SimpleDocStream</a> as an instruction tape for a stack machine:
--   text is written, annotations are added (pushed) and later removed
--   (popped).
module Prettyprinter.Render.Util.StackMachine

-- | Simplest possible stack-based renderer.
--   
--   For example, here is a document annotated with <tt>()</tt>, and the
--   behaviour is to write »&gt;&gt;&gt;« at the beginning, and
--   »&lt;&lt;&lt;« at the end of the annotated region:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "hello" &lt;+&gt; annotate () "world" &lt;&gt; "!"
--   
--   &gt;&gt;&gt; let sdoc = layoutPretty defaultLayoutOptions doc
--   
--   &gt;&gt;&gt; T.putStrLn (renderSimplyDecorated id (\() -&gt; "&gt;&gt;&gt;") (\() -&gt; "&lt;&lt;&lt;") sdoc)
--   hello &gt;&gt;&gt;world&lt;&lt;&lt;!
--   </pre>
--   
--   The monoid will be concatenated in a <i>right associative</i> fashion.
renderSimplyDecorated :: Monoid out => (Text -> out) -> (ann -> out) -> (ann -> out) -> SimpleDocStream ann -> out

-- | Version of <a>renderSimplyDecoratedA</a> that allows for
--   <a>Applicative</a> effects.
renderSimplyDecoratedA :: (Applicative f, Monoid out) => (Text -> f out) -> (ann -> f out) -> (ann -> f out) -> SimpleDocStream ann -> f out

-- | <tt>WriterT output StateT [style] a</tt>, but with a strict Writer
--   value.
--   
--   The <tt>output</tt> type is used to append data chunks to, the
--   <tt>style</tt> is the member of a stack of styles to model nested
--   styles with.

-- | <i>Deprecated: Writing your own stack machine is probably more
--   efficient and customizable; also consider using
--   »renderSimplyDecorated(A)« instead</i>
data StackMachine output style a

-- | Run the renderer and retrive the writing end
execStackMachine :: [styles] -> StackMachine output styles a -> (output, [styles])

-- | Add a new style to the style stack.
pushStyle :: Monoid output => style -> StackMachine output style ()

-- | Get the topmost style.
--   
--   If the stack is empty, this raises an <a>error</a>.
unsafePopStyle :: Monoid output => StackMachine output style style

-- | View the topmost style, but do not modify the stack.
--   
--   If the stack is empty, this raises an <a>error</a>.
unsafePeekStyle :: Monoid output => StackMachine output style style

-- | Append a value to the output end.
writeOutput :: output -> StackMachine output style ()
instance GHC.Internal.Base.Monoid output => GHC.Internal.Base.Applicative (Prettyprinter.Render.Util.StackMachine.StackMachine output style)
instance GHC.Internal.Base.Functor (Prettyprinter.Render.Util.StackMachine.StackMachine output style)
instance GHC.Internal.Base.Monoid output => GHC.Internal.Base.Monad (Prettyprinter.Render.Util.StackMachine.StackMachine output style)


-- | <i>Deprecated: Use <a>Prettyprinter.Render.Util.StackMachine</a>
--   instead.</i>
module Data.Text.Prettyprint.Doc.Render.Util.StackMachine


-- | Common symbols composed out of the ASCII subset of Unicode. For
--   non-ASCII symbols, see <a>Prettyprinter.Symbols.Unicode</a>.
module Prettyprinter.Symbols.Ascii

-- | <pre>
--   &gt;&gt;&gt; squotes "·"
--   '·'
--   </pre>
squotes :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; dquotes "·"
--   "·"
--   </pre>
dquotes :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; parens "·"
--   (·)
--   </pre>
parens :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; angles "·"
--   &lt;·&gt;
--   </pre>
angles :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; brackets "·"
--   [·]
--   </pre>
brackets :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; braces "·"
--   {·}
--   </pre>
braces :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; squote
--   '
--   </pre>
squote :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; dquote
--   "
--   </pre>
dquote :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; lparen
--   (
--   </pre>
lparen :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rparen
--   )
--   </pre>
rparen :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; langle
--   &lt;
--   </pre>
langle :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rangle
--   &gt;
--   </pre>
rangle :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; lbracket
--   [
--   </pre>
lbracket :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rbracket
--   ]
--   </pre>
rbracket :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; lbrace
--   {
--   </pre>
lbrace :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rbrace
--   }
--   </pre>
rbrace :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; semi
--   ;
--   </pre>
semi :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; colon
--   :
--   </pre>
colon :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; comma
--   ,
--   </pre>
comma :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; "a" &lt;&gt; space &lt;&gt; "b"
--   a b
--   </pre>
--   
--   This is mostly used via <tt><a>&lt;+&gt;</a></tt>,
--   
--   <pre>
--   &gt;&gt;&gt; "a" &lt;+&gt; "b"
--   a b
--   </pre>
space :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; dot
--   .
--   </pre>
dot :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; slash
--   /
--   </pre>
slash :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; backslash
--   \
--   </pre>
backslash :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; equals
--   =
--   </pre>
equals :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; pipe
--   |
--   </pre>
pipe :: Doc ann


-- | <h1>Overview</h1>
--   
--   This module defines a prettyprinter to format text in a flexible and
--   convenient way. The idea is to combine a <a>Doc</a>ument out of many
--   small components, then using a layouter to convert it to an easily
--   renderable <a>SimpleDocStream</a>, which can then be rendered to a
--   variety of formats, for example plain <a>Text</a>.
--   
--   The documentation consists of several parts:
--   
--   <ol>
--   <li>Just below is some general information about the library.</li>
--   <li>The actual library with extensive documentation and examples</li>
--   <li>Migration guide for users familiar with (ansi-)wl-pprint</li>
--   </ol>
--   
--   <h2>Starting out</h2>
--   
--   As a reading list for starters, some of the most commonly used
--   functions in this module include <a>&lt;&gt;</a>, <a>hsep</a>,
--   <a>&lt;+&gt;</a>, <a>vsep</a>, <a>align</a>, <a>hang</a>. These cover
--   many use cases already, and many other functions are variations or
--   combinations of these.
--   
--   <h1>Simple example</h1>
--   
--   Let’s prettyprint a simple Haskell type definition. First, intersperse
--   <tt>-&gt;</tt> and add a leading <tt>::</tt>,
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   
--   &gt;&gt;&gt; prettyprintType :: [Doc x] -&gt; Doc x
--   
--   &gt;&gt;&gt; prettyprintType = align . sep . zipWith (&lt;+&gt;) ("::" : repeat "-&gt;")
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The <a>sep</a> function is one way of concatenating documents, there
--   are multiple others, e.g. <a>vsep</a>, <a>cat</a> and <a>fillSep</a>.
--   In our case, <a>sep</a> space-separates all entries if there is space,
--   and newlines if the remaining line is too short.
--   
--   Second, prepend the name to the type,
--   
--   <pre>
--   &gt;&gt;&gt; let prettyprintDeclaration n tys = pretty n &lt;+&gt; prettyprintType tys
--   </pre>
--   
--   Now we can define a document that contains some type signature:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = prettyprintDeclaration "example" ["Int", "Bool", "Char", "IO ()"]
--   </pre>
--   
--   This document can now be printed, and it automatically adapts to
--   available space. If the page is wide enough (80 characters in this
--   case), the definitions are space-separated,
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 80 doc
--   example :: Int -&gt; Bool -&gt; Char -&gt; IO ()
--   </pre>
--   
--   If we narrow the page width to only 20 characters, the <i>same
--   document</i> renders vertically aligned:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 20 doc
--   example :: Int
--           -&gt; Bool
--           -&gt; Char
--           -&gt; IO ()
--   </pre>
--   
--   Speaking of alignment, had we not used <a>align</a>, the
--   <tt>-&gt;</tt> would be at the beginning of each line, and not beneath
--   the <tt>::</tt>.
--   
--   The <a>putDocW</a> renderer used here is from
--   <a>Prettyprinter.Util</a>.
--   
--   <h1>General workflow</h1>
--   
--   <pre>
--   ╔══════════╗
--   ║          ║                         ╭────────────────────╮
--   ║          ║                         │ <a>vsep</a>, <a>pretty</a>, <a>&lt;+&gt;</a>, │
--   ║          ║                         │ <a>nest</a>, <a>align</a>, …     │
--   ║          ║                         ╰─────────┬──────────╯
--   ║          ║                                   │
--   ║  Create  ║                                   │
--   ║          ║                                   │
--   ║          ║                                   ▽
--   ║          ║                         ╭───────────────────╮
--   ║          ║                         │        <a>Doc</a>        │
--   ╠══════════╣                         │  (rich document)  │
--   ║          ║                         ╰─────────┬─────────╯
--   ║          ║                                   │
--   ║          ║                                   │ Layout algorithms
--   ║  Layout  ║                                   │ e.g. <a>layoutPretty</a>
--   ║          ║                                   ▽
--   ║          ║                         ╭───────────────────╮
--   ║          ║                         │  <a>SimpleDocStream</a>  │
--   ╠══════════╣                         │ (simple document) │
--   ║          ║                         ╰─────────┬─────────╯
--   ║          ║                                   │
--   ║          ║                                   ├─────────────────────────────╮
--   ║          ║                                   │                             │ <a>treeForm</a>
--   ║          ║                                   │                             ▽
--   ║          ║                                   │                     ╭───────────────╮
--   ║          ║                                   │                     │ <a>SimpleDocTree</a> │
--   ║  Render  ║                                   │                     ╰───────┬───────╯
--   ║          ║                                   │                             │
--   ║          ║               ╭───────────────────┼─────────────────╮  ╭────────┴────────╮
--   ║          ║               │                   │                 │  │                 │
--   ║          ║               ▽                   ▽                 ▽  ▽                 ▽
--   ║          ║       ╭───────────────╮   ╭───────────────╮   ╭───────────────╮   ╭───────────────╮
--   ║          ║       │ ANSI terminal │   │  Plain <a>Text</a>   │   │ other/custom  │   │     HTML      │
--   ║          ║       ╰───────────────╯   ╰───────────────╯   ╰───────────────╯   ╰───────────────╯
--   ║          ║
--   ╚══════════╝
--   </pre>
--   
--   <h1>How the layout works</h1>
--   
--   There are two key concepts to laying a document out: the available
--   width, and <a>group</a>ing.
--   
--   <h2>Available width</h2>
--   
--   The page has a certain maximum width, which the layouter tries to not
--   exceed, by inserting line breaks where possible. The functions given
--   in this module make it fairly straightforward to specify where, and
--   under what circumstances, such a line break may be inserted by the
--   layouter, for example via the <a>sep</a> function.
--   
--   There is also the concept of <i>ribbon width</i>. The ribbon is the
--   part of a line that is printed, i.e. the line length without the
--   leading indentation. The layouters take a ribbon fraction argument,
--   which specifies how much of a line should be filled before trying to
--   break it up. A ribbon width of 0.5 in a document of width 80 will
--   result in the layouter to try to not exceed <tt>0.5*80 = 40</tt>
--   (ignoring current indentation depth).
--   
--   <h2>Grouping</h2>
--   
--   A document can be <a>group</a>ed, which tells the layouter that it
--   should attempt to collapse it to a single line. If the result does not
--   fit within the constraints (given by page and ribbon widths), the
--   document is rendered unaltered. This allows fallback definitions, so
--   that we get nice results even when the original document would exceed
--   the layout constraints.
--   
--   <h1>Things the prettyprinter <i>cannot</i> do</h1>
--   
--   Due to how the Wadler/Leijen algorithm is designed, a couple of things
--   are unsupported right now, with a high possibility of having no
--   sensible implementation without significantly changing the layout
--   algorithm. In particular, this includes
--   
--   <ul>
--   <li>Leading symbols instead of just spaces for indentation, as used by
--   the Linux <tt>tree</tt> tool for example</li>
--   <li>Multi-column layouts, in particular tables with multiple cells of
--   equal width adjacent to each other</li>
--   </ul>
--   
--   <h1>Some helpful tips</h1>
--   
--   <h2>Which kind of annotation should I use?</h2>
--   
--   <b>Summary:</b> Use semantic annotations for <tt><a>Doc</a></tt>, and
--   after layouting map to backend-specific ones.
--   
--   For example, suppose you want to prettyprint some programming language
--   code. If you want keywords to be red, you should annotate the
--   <tt><a>Doc</a></tt> with a type that has a <tt>Keyword</tt> field
--   (without any notion of color), and then after layouting convert the
--   annotations to map <tt><tt>Keyword</tt></tt> to e.g.
--   <tt><tt>Red</tt></tt> (using <tt><a>reAnnotateS</a></tt>). The
--   alternative that I <i>do not</i> recommend is directly annotating the
--   <tt><a>Doc</a></tt> with <tt>Red</tt>.
--   
--   While both versions would superficially work equally well and would
--   create identical output, the recommended way has two significant
--   advantages: modularity and extensibility.
--   
--   <i>Modularity:</i> To change the color of keywords later, you have to
--   touch one point, namely the mapping in <tt><a>reAnnotateS</a></tt>,
--   where <tt><tt>Keyword</tt></tt> is mapped to <tt>Red</tt>. If you have
--   <tt>'annotate Red …'</tt> everywher, you’ll have to do a full text
--   replacement, producing a large diff and touching lots of places for a
--   very small change.
--   
--   <i>Extensibility:</i> Adding a different backend in the recommended
--   version is simply adding another <tt><a>reAnnotateS</a></tt> to
--   convert the <tt><a>Doc</a></tt> annotation to something else. On the
--   other hand, if you have <tt><tt>Red</tt></tt> as an annotation in the
--   <tt><a>Doc</a></tt> already and the other backend does not support
--   anything red (think of plain text or a website where red doesn’t work
--   well with the rest of the style), you’ll have to worry about what to
--   map »redness« to, which has no canonical answer. Should it be omitted?
--   What does »red« mean anyway – maybe keywords and variables are red,
--   and you want to change only the color of variables?
module Prettyprinter

-- | The abstract data type <tt><a>Doc</a> ann</tt> represents pretty
--   documents that have been annotated with data of type <tt>ann</tt>.
--   
--   More specifically, a value of type <tt><a>Doc</a></tt> represents a
--   non-empty set of possible layouts of a document. The layout functions
--   select one of these possibilities, taking into account things like the
--   width of the output document.
--   
--   The annotation is an arbitrary piece of data associated with (part of)
--   a document. Annotations may be used by the rendering backends in order
--   to display output differently, such as
--   
--   <ul>
--   <li>color information (e.g. when rendering to the terminal)</li>
--   <li>mouseover text (e.g. when rendering to rich HTML)</li>
--   <li>whether to show something or not (to allow simple or detailed
--   versions)</li>
--   </ul>
--   
--   The simplest way to display a <a>Doc</a> is via the <a>Show</a> class.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn (show (vsep ["hello", "world"]))
--   hello
--   world
--   </pre>
data Doc ann

-- | Overloaded conversion to <a>Doc</a>.
--   
--   Laws:
--   
--   <ol>
--   <li>output should be pretty. :-)</li>
--   </ol>
class Pretty a

-- | <pre>
--   &gt;&gt;&gt; pretty 1 &lt;+&gt; pretty "hello" &lt;+&gt; pretty 1.234
--   1 hello 1.234
--   </pre>
pretty :: Pretty a => a -> Doc ann
($dmpretty) :: (Pretty a, Show a) => a -> Doc ann

-- | <tt><a>prettyList</a></tt> is only used to define the <tt>instance
--   <a>Pretty</a> a =&gt; <a>Pretty</a> [a]</tt>. In normal circumstances
--   only the <tt><a>pretty</a></tt> function is used.
--   
--   <pre>
--   &gt;&gt;&gt; prettyList [1, 23, 456]
--   [1, 23, 456]
--   </pre>
prettyList :: Pretty a => [a] -> Doc ann

-- | Convenience function to convert a <a>Show</a>able value to a
--   <a>Doc</a>. If the <a>String</a> does not contain newlines, consider
--   using the more performant <a>unsafeViaShow</a>.
viaShow :: Show a => a -> Doc ann

-- | Convenience function to convert a <a>Show</a>able value /that must not
--   contain newlines/ to a <a>Doc</a>. If there may be newlines, use
--   <a>viaShow</a> instead.
unsafeViaShow :: Show a => a -> Doc ann

-- | The empty document behaves like <tt>(<a>pretty</a> "")</tt>, so it has
--   a height of 1. This may lead to surprising behaviour if we expect it
--   to bear no weight inside e.g. <a>vcat</a>, where we get an empty line
--   of output from it (<tt>parens</tt> for visibility only):
--   
--   <pre>
--   &gt;&gt;&gt; vsep ["hello", parens emptyDoc, "world"]
--   hello
--   ()
--   world
--   </pre>
--   
--   Together with <a>&lt;&gt;</a>, <a>emptyDoc</a> forms the <a>Monoid</a>
--   <a>Doc</a>.
emptyDoc :: Doc ann

-- | <tt>(<a>nest</a> i x)</tt> lays out the document <tt>x</tt> with the
--   current nesting level (indentation of the following lines) increased
--   by <tt>i</tt>. Negative values are allowed, and decrease the nesting
--   level accordingly.
--   
--   <pre>
--   &gt;&gt;&gt; vsep [nest 4 (vsep ["lorem", "ipsum", "dolor"]), "sit", "amet"]
--   lorem
--       ipsum
--       dolor
--   sit
--   amet
--   </pre>
--   
--   See also
--   
--   <ul>
--   <li><a>hang</a> (<a>nest</a> relative to current cursor position
--   instead of current nesting level)</li>
--   <li><a>align</a> (set nesting level to current cursor position)</li>
--   <li><a>indent</a> (increase indentation on the spot, padding with
--   spaces).</li>
--   </ul>
nest :: Int -> Doc ann -> Doc ann

-- | The <tt><a>line</a></tt> document advances to the next line and
--   indents to the current nesting level.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; line &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
--   
--   <tt><a>line</a></tt> behaves like <tt><tt>space</tt></tt> if the line
--   break is undone by <a>group</a>:
--   
--   <pre>
--   &gt;&gt;&gt; group doc
--   lorem ipsum dolor sit amet
--   </pre>
line :: Doc ann

-- | <tt><a>line'</a></tt> is like <tt><a>line</a></tt>, but behaves like
--   <tt><a>mempty</a></tt> if the line break is undone by <a>group</a>
--   (instead of <tt><tt>space</tt></tt>).
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; line' &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; doc
--   lorem ipsum
--   dolor sit amet
--   
--   &gt;&gt;&gt; group doc
--   lorem ipsumdolor sit amet
--   </pre>
line' :: Doc ann

-- | <tt>softline</tt> behaves like <tt><tt>space</tt></tt> if the
--   resulting output fits the page, otherwise like <tt><a>line</a></tt>.
--   
--   Here, we have enough space to put everything in one line:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; softline &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   lorem ipsum dolor sit amet
--   </pre>
--   
--   If we narrow the page to width 10, the layouter produces a line break:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
--   
--   <pre>
--   <a>softline</a> = <a>group</a> <a>line</a>
--   </pre>
softline :: Doc ann

-- | <tt><a>softline'</a></tt> is like <tt><a>softline</a></tt>, but
--   behaves like <tt><a>mempty</a></tt> if the resulting output does not
--   fit on the page (instead of <tt><tt>space</tt></tt>). In other words,
--   <tt><a>line</a></tt> is to <tt><a>line'</a></tt> how
--   <tt><a>softline</a></tt> is to <tt><a>softline'</a></tt>.
--   
--   With enough space, we get direct concatenation:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "ThisWord" &lt;&gt; softline' &lt;&gt; "IsWayTooLong"
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   ThisWordIsWayTooLong
--   </pre>
--   
--   If we narrow the page to width 10, the layouter produces a line break:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   ThisWord
--   IsWayTooLong
--   </pre>
--   
--   <pre>
--   <a>softline'</a> = <a>group</a> <a>line'</a>
--   </pre>
softline' :: Doc ann

-- | A <tt><a>hardline</a></tt> is <i>always</i> laid out as a line break,
--   even when <a>group</a>ed or when there is plenty of space. Note that
--   it might still be simply discarded if it is part of a <a>flatAlt</a>
--   inside a <a>group</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "lorem ipsum" &lt;&gt; hardline &lt;&gt; "dolor sit amet"
--   
--   &gt;&gt;&gt; putDocW 1000 doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; group doc
--   lorem ipsum
--   dolor sit amet
--   </pre>
hardline :: Doc ann

-- | <tt>(<a>group</a> x)</tt> tries laying out <tt>x</tt> into a single
--   line by removing the contained line breaks; if this does not fit the
--   page, or when a <a>hardline</a> within <tt>x</tt> prevents it from
--   being flattened, <tt>x</tt> is laid out without any changes.
--   
--   The <a>group</a> function is key to layouts that adapt to available
--   space nicely.
--   
--   See <a>vcat</a>, <a>line</a>, or <a>flatAlt</a> for examples that are
--   related, or make good use of it.
group :: Doc ann -> Doc ann

-- | By default, <tt>(<a>flatAlt</a> x y)</tt> renders as <tt>x</tt>.
--   However when <a>group</a>ed, <tt>y</tt> will be preferred, with
--   <tt>x</tt> as the fallback for the case when <tt>y</tt> doesn't fit.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = flatAlt "a" "b"
--   
--   &gt;&gt;&gt; putDoc doc
--   a
--   
--   &gt;&gt;&gt; putDoc (group doc)
--   b
--   
--   &gt;&gt;&gt; putDocW 0 (group doc)
--   a
--   </pre>
--   
--   <a>flatAlt</a> is particularly useful for defining conditional
--   separators such as
--   
--   <pre>
--   softline = <a>group</a> (<a>flatAlt</a> <a>hardline</a> " ")
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let hello = "Hello" &lt;&gt; softline &lt;&gt; "world!"
--   
--   &gt;&gt;&gt; putDocW 12 hello
--   Hello world!
--   
--   &gt;&gt;&gt; putDocW 11 hello
--   Hello
--   world!
--   </pre>
--   
--   <h3><b>Example: Haskell's do-notation</b></h3>
--   
--   We can use this to render Haskell's do-notation nicely:
--   
--   <pre>
--   &gt;&gt;&gt; let open        = flatAlt "" "{ "
--   
--   &gt;&gt;&gt; let close       = flatAlt "" " }"
--   
--   &gt;&gt;&gt; let separator   = flatAlt "" "; "
--   
--   &gt;&gt;&gt; let prettyDo xs = group ("do" &lt;+&gt; align (encloseSep open close separator xs))
--   
--   &gt;&gt;&gt; let statements  = ["name:_ &lt;- getArgs", "let greet = \"Hello, \" &lt;&gt; name", "putStrLn greet"]
--   </pre>
--   
--   This is put into a single line with <tt>{;}</tt> style if it fits:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 80 (prettyDo statements)
--   do { name:_ &lt;- getArgs; let greet = "Hello, " &lt;&gt; name; putStrLn greet }
--   </pre>
--   
--   When there is not enough space the statements are broken up into lines
--   nicely:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 (prettyDo statements)
--   do name:_ &lt;- getArgs
--      let greet = "Hello, " &lt;&gt; name
--      putStrLn greet
--   </pre>
--   
--   <h3>Notes</h3>
--   
--   Users should be careful to choose <tt>x</tt> to be less wide than
--   <tt>y</tt>. Otherwise, if <tt>y</tt> turns out not to fit the page, we
--   fall back on an even wider layout:
--   
--   <pre>
--   &gt;&gt;&gt; let ugly = group (flatAlt "even wider" "too wide")
--   
--   &gt;&gt;&gt; putDocW 7 ugly
--   even wider
--   </pre>
--   
--   Also note that <a>group</a> will flatten <tt>y</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (group (flatAlt "x" ("y" &lt;&gt; line &lt;&gt; "y")))
--   y y
--   </pre>
--   
--   This also means that an "unflattenable" <tt>y</tt> which contains a
--   hard linebreak will <i>never</i> be rendered:
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (group (flatAlt "x" ("y" &lt;&gt; hardline &lt;&gt; "y")))
--   x
--   </pre>
flatAlt :: Doc ann -> Doc ann -> Doc ann

-- | <tt>(<a>align</a> x)</tt> lays out the document <tt>x</tt> with the
--   nesting level set to the current column. It is used for example to
--   implement <a>hang</a>.
--   
--   As an example, we will put a document right above another one,
--   regardless of the current nesting level. Without <a>align</a>ment, the
--   second line is put simply below everything we've had so far:
--   
--   <pre>
--   &gt;&gt;&gt; "lorem" &lt;+&gt; vsep ["ipsum", "dolor"]
--   lorem ipsum
--   dolor
--   </pre>
--   
--   If we add an <a>align</a> to the mix, the <tt><a>vsep</a></tt>'s
--   contents all start in the same column:
--   
--   <pre>
--   &gt;&gt;&gt; "lorem" &lt;+&gt; align (vsep ["ipsum", "dolor"])
--   lorem ipsum
--         dolor
--   </pre>
align :: Doc ann -> Doc ann

-- | <tt>(<a>hang</a> i x)</tt> lays out the document <tt>x</tt> with a
--   nesting level set to the <i>current column</i> plus <tt>i</tt>.
--   Negative values are allowed, and decrease the nesting level
--   accordingly.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = reflow "Indenting these words with hang"
--   
--   &gt;&gt;&gt; putDocW 24 ("prefix" &lt;+&gt; hang 4 doc)
--   prefix Indenting these
--              words with
--              hang
--   </pre>
--   
--   This differs from <a>nest</a>, which is based on the <i>current
--   nesting level</i> plus <tt>i</tt>. When you're not sure, try the more
--   efficient <a>nest</a> first. In our example, this would yield
--   
--   <pre>
--   &gt;&gt;&gt; let doc = reflow "Indenting these words with nest"
--   
--   &gt;&gt;&gt; putDocW 24 ("prefix" &lt;+&gt; nest 4 doc)
--   prefix Indenting these
--       words with nest
--   </pre>
--   
--   <pre>
--   <a>hang</a> i doc = <a>align</a> (<a>nest</a> i doc)
--   </pre>
hang :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>indent</a> i x)</tt> indents document <tt>x</tt> by <tt>i</tt>
--   columns, starting from the current cursor position.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = reflow "The indent function indents these words!"
--   
--   &gt;&gt;&gt; putDocW 24 ("prefix" &lt;&gt; indent 4 doc)
--   prefix    The indent
--             function
--             indents these
--             words!
--   </pre>
--   
--   <pre>
--   <a>indent</a> i d = <a>hang</a> i ({i spaces} &lt;&gt; d)
--   </pre>
indent :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>encloseSep</a> l r sep xs)</tt> concatenates the documents
--   <tt>xs</tt> separated by <tt>sep</tt>, and encloses the resulting
--   document by <tt>l</tt> and <tt>r</tt>.
--   
--   The documents are laid out horizontally if that fits the page:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "list" &lt;+&gt; align (encloseSep lbracket rbracket comma (map pretty [1,20,300,4000]))
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   list [1,20,300,4000]
--   </pre>
--   
--   If there is not enough space, then the input is split into lines
--   entry-wise therwise they are laid out vertically, with separators put
--   in the front:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   list [1
--        ,20
--        ,300
--        ,4000]
--   </pre>
--   
--   Note that <tt>doc</tt> contains an explicit call to <a>align</a> so
--   that the list items are aligned vertically.
--   
--   For putting separators at the end of entries instead, have a look at
--   <a>punctuate</a>.
encloseSep :: Doc ann -> Doc ann -> Doc ann -> [Doc ann] -> Doc ann

-- | Haskell-inspired variant of <a>encloseSep</a> with braces and comma as
--   separator.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = list (map pretty [1,20,300,4000])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 80 doc
--   [1, 20, 300, 4000]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   [ 1
--   , 20
--   , 300
--   , 4000 ]
--   </pre>
list :: [Doc ann] -> Doc ann

-- | Haskell-inspired variant of <a>encloseSep</a> with parentheses and
--   comma as separator.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = tupled (map pretty [1,20,300,4000])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 80 doc
--   (1, 20, 300, 4000)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 doc
--   ( 1
--   , 20
--   , 300
--   , 4000 )
--   </pre>
tupled :: [Doc ann] -> Doc ann
(<>) :: Semigroup a => a -> a -> a

-- | <tt>(x <a>&lt;+&gt;</a> y)</tt> concatenates document <tt>x</tt> and
--   <tt>y</tt> with a <tt><tt>space</tt></tt> in between.
--   
--   <pre>
--   &gt;&gt;&gt; "hello" &lt;+&gt; "world"
--   hello world
--   </pre>
--   
--   <pre>
--   x <a>&lt;+&gt;</a> y = x <a>&lt;&gt;</a> <tt>space</tt> <a>&lt;&gt;</a> y
--   </pre>
(<+>) :: Doc ann -> Doc ann -> Doc ann
infixr 6 <+>

-- | Concatenate all documents element-wise with a binary function.
--   
--   <pre>
--   <a>concatWith</a> _ [] = <a>mempty</a>
--   <a>concatWith</a> (**) [x,y,z] = x ** y ** z
--   </pre>
--   
--   Multiple convenience definitions based on <a>concatWith</a> are
--   already predefined, for example:
--   
--   <pre>
--   <a>hsep</a>    = <a>concatWith</a> (<a>&lt;+&gt;</a>)
--   <a>fillSep</a> = <a>concatWith</a> (\x y -&gt; x <a>&lt;&gt;</a> <a>softline</a> <a>&lt;&gt;</a> y)
--   </pre>
--   
--   This is also useful to define customized joiners:
--   
--   <pre>
--   &gt;&gt;&gt; concatWith (surround dot) ["Prettyprinter", "Render", "Text"]
--   Prettyprinter.Render.Text
--   </pre>
concatWith :: Foldable t => (Doc ann -> Doc ann -> Doc ann) -> t (Doc ann) -> Doc ann

-- | <tt>(<a>hsep</a> xs)</tt> concatenates all documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;+&gt;</a></tt>, i.e. it puts a space
--   between all entries.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor sit amet"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; hsep docs
--   lorem ipsum dolor sit amet
--   </pre>
--   
--   <tt><a>hsep</a></tt> does not introduce line breaks on its own, even
--   when the page is too narrow:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 5 (hsep docs)
--   lorem ipsum dolor sit amet
--   </pre>
--   
--   For automatic line breaks, consider using <a>fillSep</a> instead.
hsep :: [Doc ann] -> Doc ann

-- | <tt>(<a>vsep</a> xs)</tt> concatenates all documents <tt>xs</tt> above
--   each other. If a <a>group</a> undoes the line breaks inserted by
--   <tt>vsep</tt>, the documents are separated with a <tt>space</tt>
--   instead.
--   
--   Using <a>vsep</a> alone yields
--   
--   <pre>
--   &gt;&gt;&gt; "prefix" &lt;+&gt; vsep ["text", "to", "lay", "out"]
--   prefix text
--   to
--   lay
--   out
--   </pre>
--   
--   <a>group</a>ing a <a>vsep</a> separates the documents with a
--   <tt>space</tt> if it fits the page (and does nothing otherwise). See
--   the <tt><a>sep</a></tt> convenience function for this use case.
--   
--   The <a>align</a> function can be used to align the documents under
--   their first element:
--   
--   <pre>
--   &gt;&gt;&gt; "prefix" &lt;+&gt; align (vsep ["text", "to", "lay", "out"])
--   prefix text
--          to
--          lay
--          out
--   </pre>
--   
--   Since <a>group</a>ing a <a>vsep</a> is rather common, <a>sep</a> is a
--   built-in for doing that.
vsep :: [Doc ann] -> Doc ann

-- | <tt>(<a>fillSep</a> xs)</tt> concatenates the documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;+&gt;</a></tt> as long as it fits the
--   page, then inserts a <tt><a>line</a></tt> and continues doing that for
--   all documents in <tt>xs</tt>. (<tt><a>line</a></tt> means that if
--   <a>group</a>ed, the documents are separated with a <tt>space</tt>
--   instead of newlines. Use <a>fillCat</a> if you do not want a
--   <tt>space</tt>.)
--   
--   Let's print some words to fill the line:
--   
--   <pre>
--   &gt;&gt;&gt; let docs = take 20 (cycle ["lorem", "ipsum", "dolor", "sit", "amet"])
--   
--   &gt;&gt;&gt; putDocW 80 ("Docs:" &lt;+&gt; fillSep docs)
--   Docs: lorem ipsum dolor sit amet lorem ipsum dolor sit amet lorem ipsum dolor
--   sit amet lorem ipsum dolor sit amet
--   </pre>
--   
--   The same document, printed at a width of only 40, yields
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 40 ("Docs:" &lt;+&gt; fillSep docs)
--   Docs: lorem ipsum dolor sit amet lorem
--   ipsum dolor sit amet lorem ipsum dolor
--   sit amet lorem ipsum dolor sit amet
--   </pre>
fillSep :: [Doc ann] -> Doc ann

-- | <tt>(<a>sep</a> xs)</tt> tries laying out the documents <tt>xs</tt>
--   separated with <tt>space</tt>s, and if this does not fit the page,
--   separates them with newlines. This is what differentiates it from
--   <a>vsep</a>, which always lays out its contents beneath each other.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; sep ["text", "to", "lay", "out"]
--   
--   &gt;&gt;&gt; putDocW 80 doc
--   prefix text to lay out
--   </pre>
--   
--   With a narrower layout, the entries are separated by newlines:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 20 doc
--   prefix text
--   to
--   lay
--   out
--   </pre>
--   
--   <pre>
--   <a>sep</a> = <a>group</a> . <a>vsep</a>
--   </pre>
sep :: [Doc ann] -> Doc ann

-- | <tt>(<a>hcat</a> xs)</tt> concatenates all documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;&gt;</a></tt> (i.e. without any spacing).
--   
--   It is provided only for consistency, since it is identical to
--   <a>mconcat</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor"
--   
--   &gt;&gt;&gt; hcat docs
--   loremipsumdolor
--   </pre>
hcat :: [Doc ann] -> Doc ann

-- | <tt>(<a>vcat</a> xs)</tt> vertically concatenates the documents
--   <tt>xs</tt>. If it is <a>group</a>ed, the line breaks are removed.
--   
--   In other words <tt><a>vcat</a></tt> is like <tt><a>vsep</a></tt>, with
--   newlines removed instead of replaced by <tt>space</tt>s.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor"
--   
--   &gt;&gt;&gt; vcat docs
--   lorem
--   ipsum
--   dolor
--   
--   &gt;&gt;&gt; group (vcat docs)
--   loremipsumdolor
--   </pre>
--   
--   Since <a>group</a>ing a <a>vcat</a> is rather common, <a>cat</a> is a
--   built-in shortcut for it.
vcat :: [Doc ann] -> Doc ann

-- | <tt>(<a>fillCat</a> xs)</tt> concatenates documents <tt>xs</tt>
--   horizontally with <tt><a>&lt;&gt;</a></tt> as long as it fits the
--   page, then inserts a <tt><a>line'</a></tt> and continues doing that
--   for all documents in <tt>xs</tt>. This is similar to how an ordinary
--   word processor lays out the text if you just keep typing after you hit
--   the maximum line length.
--   
--   (<tt><a>line'</a></tt> means that if <a>group</a>ed, the documents are
--   separated with nothing instead of newlines. See <a>fillSep</a> if you
--   want a <tt>space</tt> instead.)
--   
--   Observe the difference between <a>fillSep</a> and <a>fillCat</a>.
--   <a>fillSep</a> concatenates the entries <tt>space</tt>d when
--   <a>group</a>ed:
--   
--   <pre>
--   &gt;&gt;&gt; let docs = take 20 (cycle (["lorem", "ipsum", "dolor", "sit", "amet"]))
--   
--   &gt;&gt;&gt; putDocW 40 ("Grouped:" &lt;+&gt; group (fillSep docs))
--   Grouped: lorem ipsum dolor sit amet
--   lorem ipsum dolor sit amet lorem ipsum
--   dolor sit amet lorem ipsum dolor sit
--   amet
--   </pre>
--   
--   On the other hand, <a>fillCat</a> concatenates the entries directly
--   when <a>group</a>ed:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 40 ("Grouped:" &lt;+&gt; group (fillCat docs))
--   Grouped: loremipsumdolorsitametlorem
--   ipsumdolorsitametloremipsumdolorsitamet
--   loremipsumdolorsitamet
--   </pre>
fillCat :: [Doc ann] -> Doc ann

-- | <tt>(<a>cat</a> xs)</tt> tries laying out the documents <tt>xs</tt>
--   separated with nothing, and if this does not fit the page, separates
--   them with newlines. This is what differentiates it from <a>vcat</a>,
--   which always lays out its contents beneath each other.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = Util.words "lorem ipsum dolor"
--   
--   &gt;&gt;&gt; putDocW 80 ("Docs:" &lt;+&gt; cat docs)
--   Docs: loremipsumdolor
--   </pre>
--   
--   When there is enough space, the documents are put above one another:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 10 ("Docs:" &lt;+&gt; cat docs)
--   Docs: lorem
--   ipsum
--   dolor
--   </pre>
--   
--   <pre>
--   <a>cat</a> = <a>group</a> . <a>vcat</a>
--   </pre>
cat :: [Doc ann] -> Doc ann

-- | <tt>(<a>punctuate</a> p xs)</tt> appends <tt>p</tt> to all but the
--   last document in <tt>xs</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; let docs = punctuate comma (Util.words "lorem ipsum dolor sit amet")
--   
--   &gt;&gt;&gt; putDocW 80 (hsep docs)
--   lorem, ipsum, dolor, sit, amet
--   </pre>
--   
--   The separators are put at the end of the entries, which we can see if
--   we position the result vertically:
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 20 (vsep docs)
--   lorem,
--   ipsum,
--   dolor,
--   sit,
--   amet
--   </pre>
--   
--   If you want put the commas in front of their elements instead of at
--   the end, you should use <a>tupled</a> or, in general,
--   <a>encloseSep</a>.
punctuate :: Doc ann -> [Doc ann] -> [Doc ann]

-- | Layout a document depending on which column it starts at. <a>align</a>
--   is implemented in terms of <a>column</a>.
--   
--   <pre>
--   &gt;&gt;&gt; column (\l -&gt; "Columns are" &lt;+&gt; pretty l &lt;&gt; "-based.")
--   Columns are 0-based.
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; column (\l -&gt; "| &lt;- column" &lt;+&gt; pretty l)
--   
--   &gt;&gt;&gt; vsep [indent n doc | n &lt;- [0,4,8]]
--   prefix | &lt;- column 7
--       prefix | &lt;- column 11
--           prefix | &lt;- column 15
--   </pre>
column :: (Int -> Doc ann) -> Doc ann

-- | Layout a document depending on the current <a>nest</a>ing level.
--   <a>align</a> is implemented in terms of <a>nesting</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; nesting (\l -&gt; brackets ("Nested:" &lt;+&gt; pretty l))
--   
--   &gt;&gt;&gt; vsep [indent n doc | n &lt;- [0,4,8]]
--   prefix [Nested: 0]
--       prefix [Nested: 4]
--           prefix [Nested: 8]
--   </pre>
nesting :: (Int -> Doc ann) -> Doc ann

-- | <tt>(<a>width</a> doc f)</tt> lays out the document <tt>doc</tt>, and
--   makes the column width of it available to a function.
--   
--   <pre>
--   &gt;&gt;&gt; let annotate doc = width (brackets doc) (\w -&gt; " &lt;- width:" &lt;+&gt; pretty w)
--   
--   &gt;&gt;&gt; align (vsep (map annotate ["---", "------", indent 3 "---", vsep ["---", indent 4 "---"]]))
--   [---] &lt;- width: 5
--   [------] &lt;- width: 8
--   [   ---] &lt;- width: 8
--   [---
--       ---] &lt;- width: 8
--   </pre>
width :: Doc ann -> (Int -> Doc ann) -> Doc ann

-- | Layout a document depending on the page width, if one has been
--   specified.
--   
--   <pre>
--   &gt;&gt;&gt; let prettyPageWidth (AvailablePerLine l r) = "Width:" &lt;+&gt; pretty l &lt;&gt; ", ribbon fraction:" &lt;+&gt; pretty r
--   
--   &gt;&gt;&gt; let doc = "prefix" &lt;+&gt; pageWidth (brackets . prettyPageWidth)
--   
--   &gt;&gt;&gt; putDocW 32 (vsep [indent n doc | n &lt;- [0,4,8]])
--   prefix [Width: 32, ribbon fraction: 1.0]
--       prefix [Width: 32, ribbon fraction: 1.0]
--           prefix [Width: 32, ribbon fraction: 1.0]
--   </pre>
pageWidth :: (PageWidth -> Doc ann) -> Doc ann

-- | <tt>(<a>fill</a> i x)</tt> lays out the document <tt>x</tt>. It then
--   appends <tt>space</tt>s until the width is equal to <tt>i</tt>. If the
--   width of <tt>x</tt> is already larger, nothing is appended.
--   
--   This function is quite useful in practice to output a list of
--   bindings:
--   
--   <pre>
--   &gt;&gt;&gt; let types = [("empty","Doc"), ("nest","Int -&gt; Doc -&gt; Doc"), ("fillSep","[Doc] -&gt; Doc")]
--   
--   &gt;&gt;&gt; let ptype (name, tp) = fill 5 (pretty name) &lt;+&gt; "::" &lt;+&gt; pretty tp
--   
--   &gt;&gt;&gt; "let" &lt;+&gt; align (vcat (map ptype types))
--   let empty :: Doc
--       nest  :: Int -&gt; Doc -&gt; Doc
--       fillSep :: [Doc] -&gt; Doc
--   </pre>
fill :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>fillBreak</a> i x)</tt> first lays out the document
--   <tt>x</tt>. It then appends <tt>space</tt>s until the width is equal
--   to <tt>i</tt>. If the width of <tt>x</tt> is already larger than
--   <tt>i</tt>, the nesting level is increased by <tt>i</tt> and a
--   <tt>line</tt> is appended. When we redefine <tt>ptype</tt> in the
--   example given in <a>fill</a> to use <tt><a>fillBreak</a></tt>, we get
--   a useful variation of the output:
--   
--   <pre>
--   &gt;&gt;&gt; let types = [("empty","Doc"), ("nest","Int -&gt; Doc -&gt; Doc"), ("fillSep","[Doc] -&gt; Doc")]
--   
--   &gt;&gt;&gt; let ptype (name, tp) = fillBreak 5 (pretty name) &lt;+&gt; "::" &lt;+&gt; pretty tp
--   
--   &gt;&gt;&gt; "let" &lt;+&gt; align (vcat (map ptype types))
--   let empty :: Doc
--       nest  :: Int -&gt; Doc -&gt; Doc
--       fillSep
--             :: [Doc] -&gt; Doc
--   </pre>
fillBreak :: Int -> Doc ann -> Doc ann

-- | <tt>(<a>plural</a> n one many)</tt> is <tt>one</tt> if <tt>n</tt> is
--   <tt>1</tt>, and <tt>many</tt> otherwise. A typical use case is adding
--   a plural "s".
--   
--   <pre>
--   &gt;&gt;&gt; let things = [True]
--   
--   &gt;&gt;&gt; let amount = length things
--   
--   &gt;&gt;&gt; pretty things &lt;+&gt; "has" &lt;+&gt; pretty amount &lt;+&gt; plural "entry" "entries" amount
--   [True] has 1 entry
--   </pre>
plural :: (Num amount, Eq amount) => doc -> doc -> amount -> doc

-- | <tt>(<a>enclose</a> l r x)</tt> encloses document <tt>x</tt> between
--   documents <tt>l</tt> and <tt>r</tt> using <tt><a>&lt;&gt;</a></tt>.
--   
--   <pre>
--   &gt;&gt;&gt; enclose "A" "Z" "·"
--   A·Z
--   </pre>
--   
--   <pre>
--   <a>enclose</a> l r x = l <a>&lt;&gt;</a> x <a>&lt;&gt;</a> r
--   </pre>
enclose :: Doc ann -> Doc ann -> Doc ann -> Doc ann

-- | <tt>(<a>surround</a> x l r)</tt> surrounds document <tt>x</tt> with
--   <tt>l</tt> and <tt>r</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; surround "·" "A" "Z"
--   A·Z
--   </pre>
--   
--   This is merely an argument reordering of <tt><a>enclose</a></tt>, but
--   allows for definitions like
--   
--   <pre>
--   &gt;&gt;&gt; concatWith (surround dot) ["Prettyprinter", "Render", "Text"]
--   Prettyprinter.Render.Text
--   </pre>
surround :: Doc ann -> Doc ann -> Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; squotes "·"
--   '·'
--   </pre>
squotes :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; dquotes "·"
--   "·"
--   </pre>
dquotes :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; parens "·"
--   (·)
--   </pre>
parens :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; angles "·"
--   &lt;·&gt;
--   </pre>
angles :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; brackets "·"
--   [·]
--   </pre>
brackets :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; braces "·"
--   {·}
--   </pre>
braces :: Doc ann -> Doc ann

-- | <pre>
--   &gt;&gt;&gt; lparen
--   (
--   </pre>
lparen :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rparen
--   )
--   </pre>
rparen :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; langle
--   &lt;
--   </pre>
langle :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rangle
--   &gt;
--   </pre>
rangle :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; lbrace
--   {
--   </pre>
lbrace :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rbrace
--   }
--   </pre>
rbrace :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; lbracket
--   [
--   </pre>
lbracket :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; rbracket
--   ]
--   </pre>
rbracket :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; squote
--   '
--   </pre>
squote :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; dquote
--   "
--   </pre>
dquote :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; semi
--   ;
--   </pre>
semi :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; colon
--   :
--   </pre>
colon :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; comma
--   ,
--   </pre>
comma :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; "a" &lt;&gt; space &lt;&gt; "b"
--   a b
--   </pre>
--   
--   This is mostly used via <tt><a>&lt;+&gt;</a></tt>,
--   
--   <pre>
--   &gt;&gt;&gt; "a" &lt;+&gt; "b"
--   a b
--   </pre>
space :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; dot
--   .
--   </pre>
dot :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; slash
--   /
--   </pre>
slash :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; backslash
--   \
--   </pre>
backslash :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; equals
--   =
--   </pre>
equals :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; pipe
--   |
--   </pre>
pipe :: Doc ann

-- | Add an annotation to a <tt><a>Doc</a></tt>. This annotation can then
--   be used by the renderer to e.g. add color to certain parts of the
--   output. For a full tutorial example on how to use it, see the
--   <a>Prettyprinter.Render.Tutorials.StackMachineTutorial</a> or
--   <a>Prettyprinter.Render.Tutorials.TreeRenderingTutorial</a> modules.
--   
--   This function is only relevant for custom formats with their own
--   annotations, and not relevant for basic prettyprinting. The predefined
--   renderers, e.g. <a>Prettyprinter.Render.Text</a>, should be enough for
--   the most common needs.
annotate :: ann -> Doc ann -> Doc ann

-- | Remove all annotations.
--   
--   Although <a>unAnnotate</a> is idempotent with respect to rendering,
--   
--   <pre>
--   <a>unAnnotate</a> . <a>unAnnotate</a> = <a>unAnnotate</a>
--   </pre>
--   
--   it should not be used without caution, for each invocation traverses
--   the entire contained document. If possible, it is preferrable to
--   unannotate after producing the layout by using <a>unAnnotateS</a>.
unAnnotate :: Doc ann -> Doc xxx

-- | Change the annotation of a <a>Doc</a>ument.
--   
--   Useful in particular to embed documents with one form of annotation in
--   a more generally annotated document.
--   
--   Since this traverses the entire <tt><a>Doc</a></tt> tree, including
--   parts that are not rendered due to other layouts fitting better, it is
--   preferrable to reannotate after producing the layout by using
--   <tt><a>reAnnotateS</a></tt>.
--   
--   Since <tt><a>reAnnotate</a></tt> has the right type and satisfies
--   <tt>'reAnnotate id = id'</tt>, it is used to define the
--   <tt><a>Functor</a></tt> instance of <tt><a>Doc</a></tt>.
reAnnotate :: (ann -> ann') -> Doc ann -> Doc ann'

-- | Change the annotations of a <a>Doc</a>ument. Individual annotations
--   can be removed, changed, or replaced by multiple ones.
--   
--   This is a general function that combines <a>unAnnotate</a> and
--   <a>reAnnotate</a>, and it is useful for mapping semantic annotations
--   (such as »this is a keyword«) to display annotations (such as »this is
--   red and underlined«), because some backends may not care about certain
--   annotations, while others may.
--   
--   Annotations earlier in the new list will be applied earlier, i.e.
--   returning <tt>[Bold, Green]</tt> will result in a bold document that
--   contains green text, and not vice-versa.
--   
--   Since this traverses the entire <tt><a>Doc</a></tt> tree, including
--   parts that are not rendered due to other layouts fitting better, it is
--   preferrable to reannotate after producing the layout by using
--   <tt><a>alterAnnotationsS</a></tt>.
alterAnnotations :: (ann -> [ann']) -> Doc ann -> Doc ann'

-- | Remove all annotations. <a>unAnnotate</a> for <a>SimpleDocStream</a>.
unAnnotateS :: SimpleDocStream ann -> SimpleDocStream xxx

-- | Change the annotation of a document. <a>reAnnotate</a> for
--   <a>SimpleDocStream</a>.
reAnnotateS :: (ann -> ann') -> SimpleDocStream ann -> SimpleDocStream ann'

-- | Change the annotation of a document to a different annotation, or none
--   at all. <a>alterAnnotations</a> for <a>SimpleDocStream</a>.
--   
--   Note that the <a>Doc</a> version is more flexible, since it allows
--   changing a single annotation to multiple ones. (<a>SimpleDocTree</a>
--   restores this flexibility again.)
alterAnnotationsS :: (ann -> Maybe ann') -> SimpleDocStream ann -> SimpleDocStream ann'

-- | <tt>(<a>fuse</a> depth doc)</tt> combines text nodes so they can be
--   rendered more efficiently. A fused document is always laid out
--   identical to its unfused version.
--   
--   When laying a <a>Doc</a>ument out to a <a>SimpleDocStream</a>, every
--   component of the input is translated directly to the simpler output
--   format. This sometimes yields undesirable chunking when many pieces
--   have been concatenated together.
--   
--   For example
--   
--   <pre>
--   &gt;&gt;&gt; "a" &lt;&gt; "b" &lt;&gt; pretty 'c' &lt;&gt; "d"
--   abcd
--   </pre>
--   
--   results in a chain of four entries in a <a>SimpleDocStream</a>,
--   although this is fully equivalent to the tightly packed
--   
--   <pre>
--   &gt;&gt;&gt; "abcd" :: Doc ann
--   abcd
--   </pre>
--   
--   which is only a single <a>SimpleDocStream</a> entry, and can be
--   processed faster.
--   
--   It is therefore a good idea to run <a>fuse</a> on concatenations of
--   lots of small strings that are used many times:
--   
--   <pre>
--   &gt;&gt;&gt; let oftenUsed = fuse Shallow ("a" &lt;&gt; "b" &lt;&gt; pretty 'c' &lt;&gt; "d")
--   
--   &gt;&gt;&gt; hsep (replicate 5 oftenUsed)
--   abcd abcd abcd abcd abcd
--   </pre>
fuse :: FusionDepth -> Doc ann -> Doc ann

-- | Fusion depth parameter, used by <a>fuse</a>.
data FusionDepth

-- | Do not dive deep into nested documents, fusing mostly concatenations
--   of text nodes together.
Shallow :: FusionDepth

-- | Recurse into all parts of the <a>Doc</a>, including different layout
--   alternatives, and location-sensitive values such as created by
--   <a>nesting</a> which cannot be fused before, but only during, the
--   layout process. As a result, the performance cost of using deep fusion
--   is often hard to predict, and depends on the interplay between page
--   layout and document to prettyprint.
--   
--   This value should only be used if profiling shows it is significantly
--   faster than using <a>Shallow</a>.
Deep :: FusionDepth

-- | The data type <tt>SimpleDocStream</tt> represents laid out documents
--   and is used by the display functions.
--   
--   A simplified view is that <tt><a>Doc</a> =
--   [<a>SimpleDocStream</a>]</tt>, and the layout functions pick one of
--   the <a>SimpleDocStream</a>s based on which one fits the layout
--   constraints best. This means that <a>SimpleDocStream</a> has all
--   complexity contained in <a>Doc</a> resolved, making it very easy to
--   convert it to other formats, such as plain text or terminal output.
--   
--   To write your own <tt><a>Doc</a></tt> to X converter, it is therefore
--   sufficient to convert from <tt><a>SimpleDocStream</a></tt>. The
--   »Render« submodules provide some built-in converters to do so, and
--   helpers to create own ones.
data SimpleDocStream ann
SFail :: SimpleDocStream ann
SEmpty :: SimpleDocStream ann
SChar :: !Char -> SimpleDocStream ann -> SimpleDocStream ann

-- | <a>length</a> is <i>O(n)</i>, so we cache it in the <a>Int</a> field.
SText :: !Int -> !Text -> SimpleDocStream ann -> SimpleDocStream ann

-- | <tt>Int</tt> = indentation level for the (next) line
SLine :: !Int -> SimpleDocStream ann -> SimpleDocStream ann

-- | Add an annotation to the remaining document.
SAnnPush :: ann -> SimpleDocStream ann -> SimpleDocStream ann

-- | Remove a previously pushed annotation.
SAnnPop :: SimpleDocStream ann -> SimpleDocStream ann

-- | Maximum number of characters that fit in one line. The layout
--   algorithms will try not to exceed the set limit by inserting line
--   breaks when applicable (e.g. via <a>softline'</a>).
data PageWidth

-- | Layouters should not exceed the specified space per line.
--   
--   <ul>
--   <li>The <a>Int</a> is the number of characters, including whitespace,
--   that fit in a line. A typical value is 80.</li>
--   <li>The <a>Double</a> is the ribbon with, i.e. the fraction of the
--   total page width that can be printed on. This allows limiting the
--   length of printable text per line. Values must be between 0 and 1, and
--   0.4 to 1 is typical.</li>
--   </ul>
AvailablePerLine :: !Int -> !Double -> PageWidth

-- | Layouters should not introduce line breaks on their own.
Unbounded :: PageWidth

-- | Options to influence the layout algorithms.
newtype LayoutOptions
LayoutOptions :: PageWidth -> LayoutOptions
[layoutPageWidth] :: LayoutOptions -> PageWidth

-- | The default layout options, suitable when you just want some output,
--   and don’t particularly care about the details. Used by the <a>Show</a>
--   instance, for example.
--   
--   <pre>
--   &gt;&gt;&gt; defaultLayoutOptions
--   LayoutOptions {layoutPageWidth = AvailablePerLine 80 1.0}
--   </pre>
defaultLayoutOptions :: LayoutOptions

-- | This is the default layout algorithm, and it is used by <a>show</a>,
--   <tt>putDoc</tt> and <tt>hPutDoc</tt>.
--   
--   <tt><a>layoutPretty</a></tt> commits to rendering something in a
--   certain way if the next element fits the layout constraints; in other
--   words, it has one <a>SimpleDocStream</a> element lookahead when
--   rendering. Consider using the smarter, but a bit less performant,
--   <tt><a>layoutSmart</a></tt> algorithm if the results seem to run off
--   to the right before having lots of line breaks.
layoutPretty :: LayoutOptions -> Doc ann -> SimpleDocStream ann

-- | <tt>(layoutCompact x)</tt> lays out the document <tt>x</tt> without
--   adding any indentation and without preserving annotations. Since no
--   'pretty' printing is involved, this layouter is very fast. The
--   resulting output contains fewer characters than a prettyprinted
--   version and can be used for output that is read by other programs.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = hang 4 (vsep ["lorem", "ipsum", hang 4 (vsep ["dolor", "sit"])])
--   
--   &gt;&gt;&gt; doc
--   lorem
--       ipsum
--       dolor
--           sit
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let putDocCompact = renderIO System.IO.stdout . layoutCompact
--   
--   &gt;&gt;&gt; putDocCompact doc
--   lorem
--   ipsum
--   dolor
--   sit
--   </pre>
layoutCompact :: Doc ann1 -> SimpleDocStream ann2

-- | A layout algorithm with more lookahead than <a>layoutPretty</a>, that
--   introduces line breaks earlier if the content does not (or will not,
--   rather) fit into one line.
--   
--   Consider the following python-ish document,
--   
--   <pre>
--   &gt;&gt;&gt; let fun x = hang 2 ("fun(" &lt;&gt; softline' &lt;&gt; x) &lt;&gt; ")"
--   
--   &gt;&gt;&gt; let doc = (fun . fun . fun . fun . fun) (align (list ["abcdef", "ghijklm"]))
--   </pre>
--   
--   which we’ll be rendering using the following pipeline (where the
--   layout algorithm has been left open):
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Text.IO as T
--   
--   &gt;&gt;&gt; import Prettyprinter.Render.Text
--   
--   &gt;&gt;&gt; let hr = pipe &lt;&gt; pretty (replicate (26-2) '-') &lt;&gt; pipe
--   
--   &gt;&gt;&gt; let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
--   </pre>
--   
--   If we render this using <a>layoutPretty</a> with a page width of 26
--   characters per line, all the <tt>fun</tt> calls fit into the first
--   line so they will be put there:
--   
--   <pre>
--   &gt;&gt;&gt; go layoutPretty doc
--   |------------------------|
--   fun(fun(fun(fun(fun(
--                     [ abcdef
--                     , ghijklm ])))))
--   |------------------------|
--   </pre>
--   
--   Note that this exceeds the desired 26 character page width. The same
--   document, rendered with <tt><a>layoutSmart</a></tt>, fits the layout
--   contstraints:
--   
--   <pre>
--   &gt;&gt;&gt; go layoutSmart doc
--   |------------------------|
--   fun(
--     fun(
--       fun(
--         fun(
--           fun(
--             [ abcdef
--             , ghijklm ])))))
--   |------------------------|
--   </pre>
--   
--   The key difference between <a>layoutPretty</a> and <a>layoutSmart</a>
--   is that the latter will check the potential document until it
--   encounters a line with the same indentation or less than the start of
--   the document. Any line encountered earlier is assumed to belong to the
--   same syntactic structure. <a>layoutPretty</a> checks only the first
--   line.
--   
--   Consider for example the question of whether the <tt>A</tt>s fit into
--   the document below:
--   
--   <pre>
--   1 A
--   2   A
--   3  A
--   4 B
--   5   B
--   </pre>
--   
--   <a>layoutPretty</a> will check only line 1, ignoring whether e.g. line
--   2 might already be too wide. By contrast, <a>layoutSmart</a> stops
--   only once it reaches line 4, where the <tt>B</tt> has the same
--   indentation as the first <tt>A</tt>.
layoutSmart :: LayoutOptions -> Doc ann -> SimpleDocStream ann

-- | Remove all trailing space characters.
--   
--   This has some performance impact, because it does an entire additional
--   pass over the <a>SimpleDocStream</a>.
--   
--   No trimming will be done inside annotations, which are considered to
--   contain no (trimmable) whitespace, since the annotation might actually
--   be <i>about</i> the whitespace, for example a renderer that colors the
--   background of trailing whitespace, as e.g. <tt>git diff</tt> can be
--   configured to do.
--   
--   <i>Historical note:</i> Since v1.7.0, <a>layoutPretty</a> and
--   <a>layoutSmart</a> avoid producing the trailing whitespace that was
--   the original motivation for creating <a>removeTrailingWhitespace</a>.
--   See <a>https://github.com/quchen/prettyprinter/pull/139</a> for some
--   background info.
removeTrailingWhitespace :: SimpleDocStream ann -> SimpleDocStream ann


-- | Conversion of the linked-list-like <a>SimpleDocStream</a> to a
--   tree-like <a>SimpleDocTree</a>.
module Prettyprinter.Render.Util.SimpleDocTree

-- | A <a>SimpleDocStream</a> is a linked list of different annotated cons
--   cells (<a>SText</a> and then some further <a>SimpleDocStream</a>,
--   <a>SLine</a> and then some further <a>SimpleDocStream</a>, …). This
--   format is very suitable as a target for a layout engine, but not very
--   useful for rendering to a structured format such as HTML, where we
--   don’t want to do a lookahead until the end of some markup. These
--   formats benefit from a tree-like structure that explicitly marks its
--   contents as annotated. <a>SimpleDocTree</a> is that format.
data SimpleDocTree ann
STEmpty :: SimpleDocTree ann
STChar :: Char -> SimpleDocTree ann

-- | <a>length</a> is <i>O(n)</i>, so we cache it in the <a>Int</a> field.
STText :: !Int -> Text -> SimpleDocTree ann

-- | <tt>Int</tt> = indentation level for the (next) line
STLine :: !Int -> SimpleDocTree ann

-- | Annotate the contained document.
STAnn :: ann -> SimpleDocTree ann -> SimpleDocTree ann

-- | Horizontal concatenation of multiple documents.
STConcat :: [SimpleDocTree ann] -> SimpleDocTree ann

-- | Convert a <a>SimpleDocStream</a> to its <a>SimpleDocTree</a>
--   representation.
treeForm :: SimpleDocStream ann -> SimpleDocTree ann

-- | Remove all annotations. <a>unAnnotate</a> for <a>SimpleDocTree</a>.
unAnnotateST :: SimpleDocTree ann -> SimpleDocTree xxx

-- | Change the annotation of a document. <a>reAnnotate</a> for
--   <a>SimpleDocTree</a>.
reAnnotateST :: (ann -> ann') -> SimpleDocTree ann -> SimpleDocTree ann'

-- | Change the annotation of a document to a different annotation, or none
--   at all. <a>alterAnnotations</a> for <a>SimpleDocTree</a>.
--   
--   Note that this is as powerful as <a>alterAnnotations</a>, allowing one
--   annotation to become multiple ones, contrary to
--   <a>alterAnnotationsS</a>, which cannot do this.
alterAnnotationsST :: (ann -> [ann']) -> SimpleDocTree ann -> SimpleDocTree ann'

-- | Simplest possible tree-based renderer.
--   
--   For example, here is a document annotated with <tt>()</tt>, and the
--   behaviour is to surround annotated regions with »&gt;&gt;&gt;« and
--   »&lt;&lt;&lt;«:
--   
--   <pre>
--   &gt;&gt;&gt; let doc = "hello" &lt;+&gt; annotate () "world" &lt;&gt; "!"
--   
--   &gt;&gt;&gt; let stdoc = treeForm (layoutPretty defaultLayoutOptions doc)
--   
--   &gt;&gt;&gt; T.putStrLn (renderSimplyDecorated id (\() x -&gt; "&gt;&gt;&gt;" &lt;&gt; x &lt;&gt; "&lt;&lt;&lt;") stdoc)
--   hello &gt;&gt;&gt;world&lt;&lt;&lt;!
--   </pre>
renderSimplyDecorated :: Monoid out => (Text -> out) -> (ann -> out -> out) -> SimpleDocTree ann -> out

-- | Version of <a>renderSimplyDecoratedA</a> that allows for
--   <a>Applicative</a> effects.
renderSimplyDecoratedA :: (Applicative f, Monoid out) => (Text -> f out) -> (ann -> f out -> f out) -> SimpleDocTree ann -> f out
instance GHC.Internal.Base.Alternative (Prettyprinter.Render.Util.SimpleDocTree.UniqueParser s)
instance GHC.Internal.Base.Applicative (Prettyprinter.Render.Util.SimpleDocTree.UniqueParser s)
instance GHC.Classes.Eq ann => GHC.Classes.Eq (Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTok ann)
instance GHC.Classes.Eq ann => GHC.Classes.Eq (Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTree ann)
instance GHC.Internal.Data.Foldable.Foldable Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTree
instance GHC.Internal.Base.Functor Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTree
instance GHC.Internal.Base.Functor (Prettyprinter.Render.Util.SimpleDocTree.UniqueParser s)
instance GHC.Internal.Generics.Generic (Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTree ann)
instance GHC.Internal.Control.Monad.Fail.MonadFail (Prettyprinter.Render.Util.SimpleDocTree.UniqueParser s)
instance GHC.Internal.Base.Monad (Prettyprinter.Render.Util.SimpleDocTree.UniqueParser s)
instance GHC.Classes.Ord ann => GHC.Classes.Ord (Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTok ann)
instance GHC.Classes.Ord ann => GHC.Classes.Ord (Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTree ann)
instance GHC.Internal.Show.Show ann => GHC.Internal.Show.Show (Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTok ann)
instance GHC.Internal.Show.Show ann => GHC.Internal.Show.Show (Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTree ann)
instance GHC.Internal.Data.Traversable.Traversable Prettyprinter.Render.Util.SimpleDocTree.SimpleDocTree


-- | <i>Deprecated: Use <a>Prettyprinter.Render.Util.SimpleDocTree</a>
--   instead.</i>
module Data.Text.Prettyprint.Doc.Render.Util.SimpleDocTree


-- | This module shows how to write a custom prettyprinter backend, based
--   on a tree representation of a <a>SimpleDocStream</a>. For a stack
--   machine approach, which may be more suitable for certain output
--   formats, see
--   <a>Prettyprinter.Render.Tutorials.StackMachineTutorial</a>.
--   
--   Rendering to HTML, particularly using libraries such as blaze-html or
--   lucid, is one important use case of tree-based rendering.
--   
--   The module is written to be readable top-to-bottom in both Haddock and
--   raw source form.
module Prettyprinter.Render.Tutorials.TreeRenderingTutorial
data SimpleHtml
Bold :: SimpleHtml
Italics :: SimpleHtml
Color :: Color -> SimpleHtml
Paragraph :: SimpleHtml
Headline :: SimpleHtml
data Color
Red :: Color
Green :: Color
Blue :: Color
bold :: Doc SimpleHtml -> Doc SimpleHtml
italics :: Doc SimpleHtml -> Doc SimpleHtml
paragraph :: Doc SimpleHtml -> Doc SimpleHtml
headline :: Doc SimpleHtml -> Doc SimpleHtml
color :: Color -> Doc SimpleHtml -> Doc SimpleHtml

-- | To render the HTML, we first convert the <a>SimpleDocStream</a> to the
--   <a>SimpleDocTree</a> format, which makes enveloping sub-documents in
--   markup easier.
--   
--   This function is the entry main API function of the renderer; as such,
--   it is only glue for the internal functions. This is similar to
--   <a>render</a> from the stack machine tutorial in its purpose.
render :: SimpleDocStream SimpleHtml -> Text

-- | Render a <a>SimpleDocTree</a> to a <a>Builder</a>; this is the
--   workhorse of the tree-based rendering approach, and equivalent to
--   <a>renderStackMachine</a> in the stack machine rendering tutorial.
renderTree :: SimpleDocTree SimpleHtml -> Builder

-- | Convert a <a>SimpleHtml</a> to a function that encloses a
--   <a>Builder</a> in HTML tags. This is where the translation of style to
--   raw output happens.
encloseInTagFor :: SimpleHtml -> Builder -> Builder


-- | <i>Deprecated: Use
--   <a>Prettyprinter.Render.Tutorials.TreeRenderingTutorial</a>
--   instead.</i>
module Data.Text.Prettyprint.Doc.Render.Tutorials.TreeRenderingTutorial


-- | This module shows how to write a custom prettyprinter backend, based
--   on directly converting a <a>SimpleDocStream</a> to an output format
--   using a stack machine. For a tree serialization approach, which may be
--   more suitable for certain output formats, see
--   <a>Prettyprinter.Render.Tutorials.TreeRenderingTutorial</a>.
--   
--   Rendering to ANSI terminal with colors is an important use case for
--   stack machine based rendering.
--   
--   The module is written to be readable top-to-bottom in both Haddock and
--   raw source form.

-- | <i>Deprecated: Writing your own stack machine is probably more
--   efficient and customizable; also consider using
--   »renderSimplyDecorated(A)« instead</i>
module Prettyprinter.Render.Tutorials.StackMachineTutorial
data SimpleHtml
Bold :: SimpleHtml
Italics :: SimpleHtml
Color :: Color -> SimpleHtml
Paragraph :: SimpleHtml
Headline :: SimpleHtml
data Color
Red :: Color
Green :: Color
Blue :: Color
bold :: Doc SimpleHtml -> Doc SimpleHtml
italics :: Doc SimpleHtml -> Doc SimpleHtml
paragraph :: Doc SimpleHtml -> Doc SimpleHtml
headline :: Doc SimpleHtml -> Doc SimpleHtml
color :: Color -> Doc SimpleHtml -> Doc SimpleHtml

-- | The <a>StackMachine</a> type defines a stack machine suitable for many
--   rendering needs. It has two auxiliary parameters: the type of the end
--   result, and the type of the document’s annotations.
--   
--   Most <a>StackMachine</a> creations will look like this definition: a
--   recursive walk through the <a>SimpleDocStream</a>, pushing styles on
--   the stack and popping them off again, and writing raw output.
--   
--   The equivalent to this in the tree based rendering approach is
--   <a>renderTree</a>.
renderStackMachine :: SimpleDocStream SimpleHtml -> StackMachine Builder SimpleHtml ()

-- | Convert a <a>SimpleHtml</a> annotation to a pair of opening and
--   closing tags. This is where the translation of style to raw output
--   happens.
htmlTag :: SimpleHtml -> (Builder, Builder)

-- | We can now wrap our stack machine definition from
--   <a>renderStackMachine</a> in a nicer interface; on successful
--   conversion, we run the builder to give us the final <a>Text</a>, and
--   before we do that we check that the style stack is empty (i.e. there
--   are no unmatched style applications) after the machine is run.
--   
--   This function does only a bit of plumbing around
--   <a>renderStackMachine</a>, and is the main API function of a stack
--   machine renderer. The tree renderer equivalent to this is
--   <a>render</a>.
render :: SimpleDocStream SimpleHtml -> Text


-- | <i>Deprecated: Use
--   <a>Prettyprinter.Render.Tutorials.StackMachineTutorial</a>
--   instead.</i>
module Data.Text.Prettyprint.Doc.Render.Tutorials.StackMachineTutorial


-- | Render an unannotated <a>SimpleDocStream</a> as plain <a>Text</a>.
module Prettyprinter.Render.Text

-- | <tt>(<a>renderLazy</a> sdoc)</tt> takes the output <tt>sdoc</tt> from
--   a rendering function and transforms it to lazy text.
--   
--   <pre>
--   &gt;&gt;&gt; let render = TL.putStrLn . renderLazy . layoutPretty defaultLayoutOptions
--   
--   &gt;&gt;&gt; let doc = "lorem" &lt;+&gt; align (vsep ["ipsum dolor", parens "foo bar", "sit amet"])
--   
--   &gt;&gt;&gt; render doc
--   lorem ipsum dolor
--         (foo bar)
--         sit amet
--   </pre>
renderLazy :: SimpleDocStream ann -> Text

-- | <tt>(<a>renderStrict</a> sdoc)</tt> takes the output <tt>sdoc</tt>
--   from a rendering function and transforms it to strict text.
renderStrict :: SimpleDocStream ann -> Text

-- | <tt>(<a>renderIO</a> h sdoc)</tt> writes <tt>sdoc</tt> to the file
--   <tt>h</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; renderIO System.IO.stdout (layoutPretty defaultLayoutOptions "hello\nworld")
--   hello
--   world
--   </pre>
--   
--   This function is more efficient than <tt><a>hPutStr</a> h
--   (<a>renderStrict</a> sdoc)</tt>, since it writes to the handle
--   directly, skipping the intermediate <a>Text</a> representation.
renderIO :: Handle -> SimpleDocStream ann -> IO ()

-- | <tt>(<a>putDoc</a> doc)</tt> prettyprints document <tt>doc</tt> to
--   standard output. Uses the <a>defaultLayoutOptions</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc ("hello" &lt;+&gt; "world")
--   hello world
--   </pre>
--   
--   <pre>
--   <a>putDoc</a> = <a>hPutDoc</a> <a>stdout</a>
--   </pre>
putDoc :: Doc ann -> IO ()

-- | Like <a>putDoc</a>, but instead of using <a>stdout</a>, print to a
--   user-provided handle, e.g. a file or a socket. Uses the
--   <a>defaultLayoutOptions</a>.
--   
--   <pre>
--   main = <a>withFile</a> filename (h -&gt; <a>hPutDoc</a> h doc)
--     where
--       doc = <a>vcat</a> ["vertical", "text"]
--       filename = "someFile.txt"
--   </pre>
--   
--   <pre>
--   <a>hPutDoc</a> h doc = <a>renderIO</a> h (<a>layoutPretty</a> <a>defaultLayoutOptions</a> doc)
--   </pre>
hPutDoc :: Handle -> Doc ann -> IO ()


-- | <i>Deprecated: Use <a>Prettyprinter.Render.Text</a> instead.</i>
module Data.Text.Prettyprint.Doc.Render.Text


-- | <i>Deprecated: Use <a>Prettyprinter</a> instead.</i>
module Data.Text.Prettyprint.Doc


-- | <i>Deprecated: Use <a>Prettyprinter.Symbols.Ascii</a> instead.</i>
module Data.Text.Prettyprint.Doc.Symbols.Ascii


-- | A collection of predefined Unicode values outside of ASCII range. For
--   ASCII, see <a>Prettyprinter.Symbols.Ascii</a>.
module Prettyprinter.Symbols.Unicode

-- | Double „99-66“ quotes, as used in German typography.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (d9966quotes "·")
--   „·“
--   </pre>
d9966quotes :: Doc ann -> Doc ann

-- | Double “66-99” quotes, as used in English typography.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (d6699quotes "·")
--   “·”
--   </pre>
d6699quotes :: Doc ann -> Doc ann

-- | Single ‚9-6‘ quotes, as used in German typography.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (s96quotes "·")
--   ‚·‘
--   </pre>
s96quotes :: Doc ann -> Doc ann

-- | Single ‘6-9’ quotes, as used in English typography.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (s69quotes "·")
--   ‘·’
--   </pre>
s69quotes :: Doc ann -> Doc ann

-- | Double «guillemets», pointing outwards (without adding any spacing).
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (dGuillemetsOut "·")
--   «·»
--   </pre>
dGuillemetsOut :: Doc ann -> Doc ann

-- | Double »guillemets«, pointing inwards (without adding any spacing).
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (dGuillemetsIn "·")
--   »·«
--   </pre>
dGuillemetsIn :: Doc ann -> Doc ann

-- | Single ‹guillemets›, pointing outwards (without adding any spacing).
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (sGuillemetsOut "·")
--   ‹·›
--   </pre>
sGuillemetsOut :: Doc ann -> Doc ann

-- | Single ›guillemets‹, pointing inwards (without adding any spacing).
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (sGuillemetsIn "·")
--   ›·‹
--   </pre>
sGuillemetsIn :: Doc ann -> Doc ann

-- | Bottom „99“ style double quotes.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc b99dquote
--   „
--   </pre>
b99dquote :: Doc ann

-- | Top “66” style double quotes.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc t66dquote
--   “
--   </pre>
t66dquote :: Doc ann

-- | Top “99” style double quotes.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc t99dquote
--   ”
--   </pre>
t99dquote :: Doc ann

-- | Bottom ‚9‘ style single quote.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc b9quote
--   ‚
--   </pre>
b9quote :: Doc ann

-- | Top ‘66’ style single quote.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc t6quote
--   ‘
--   </pre>
t6quote :: Doc ann

-- | Top ‘9’ style single quote.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc t9quote
--   ’
--   </pre>
t9quote :: Doc ann

-- | Right-pointing double guillemets
--   
--   <pre>
--   &gt;&gt;&gt; putDoc rdGuillemet
--   »
--   </pre>
rdGuillemet :: Doc ann

-- | Left-pointing double guillemets
--   
--   <pre>
--   &gt;&gt;&gt; putDoc ldGuillemet
--   «
--   </pre>
ldGuillemet :: Doc ann

-- | Right-pointing single guillemets
--   
--   <pre>
--   &gt;&gt;&gt; putDoc rsGuillemet
--   ›
--   </pre>
rsGuillemet :: Doc ann

-- | Left-pointing single guillemets
--   
--   <pre>
--   &gt;&gt;&gt; putDoc lsGuillemet
--   ‹
--   </pre>
lsGuillemet :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; putDoc bullet
--   •
--   </pre>
bullet :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; putDoc endash
--   –
--   </pre>
endash :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; putDoc euro
--   €
--   </pre>
euro :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; putDoc cent
--   ¢
--   </pre>
cent :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; putDoc yen
--   ¥
--   </pre>
yen :: Doc ann

-- | <pre>
--   &gt;&gt;&gt; putDoc pound
--   £
--   </pre>
pound :: Doc ann


-- | <i>Deprecated: Use <a>Prettyprinter.Symbols.Unicode</a> instead.</i>
module Data.Text.Prettyprint.Doc.Symbols.Unicode


-- | Frequently useful definitions for working with general prettyprinters.
module Prettyprinter.Util

-- | Split an input into word-sized <a>Doc</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; putDoc (tupled (words "Lorem ipsum dolor"))
--   (Lorem, ipsum, dolor)
--   </pre>
words :: Text -> [Doc ann]

-- | Render a document with a certain width. Useful for quick-and-dirty
--   testing of layout behaviour. Used heavily in the doctests of this
--   package, for example.
--   
--   <pre>
--   &gt;&gt;&gt; let doc = reflow "Lorem ipsum dolor sit amet, consectetur adipisicing elit"
--   
--   &gt;&gt;&gt; putDocW 20 doc
--   Lorem ipsum dolor
--   sit amet,
--   consectetur
--   adipisicing elit
--   
--   &gt;&gt;&gt; putDocW 30 doc
--   Lorem ipsum dolor sit amet,
--   consectetur adipisicing elit
--   </pre>
putDocW :: Int -> Doc ann -> IO ()

-- | Insert soft linebreaks between words, so that text is broken into
--   multiple lines when it exceeds the available width.
--   
--   <pre>
--   &gt;&gt;&gt; putDocW 32 (reflow "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.")
--   Lorem ipsum dolor sit amet,
--   consectetur adipisicing elit,
--   sed do eiusmod tempor incididunt
--   ut labore et dolore magna
--   aliqua.
--   </pre>
--   
--   <pre>
--   <a>reflow</a> = <a>fillSep</a> . <a>words</a>
--   </pre>
reflow :: Text -> Doc ann


-- | <i>Deprecated: Use <a>Prettyprinter.Util</a> instead.</i>
module Data.Text.Prettyprint.Doc.Util
