### Python-like Document Example Setup

Source: https://hackage.haskell.org/package/prettyprinter-1/docs/Data-Text-Prettyprint-Doc-Internal.html

Sets up a sample document and rendering pipeline for demonstrating layout algorithms.

```haskell
>>> **let fun x = hang 2 ("fun(" <> softline' <> x) <> ")"
**>>> **let doc = (fun . fun . fun . fun . fun) (list ["abcdef", "ghijklm"])
**
```

```haskell
>>> **import Data.Text.IO as T
**>>> **import Data.Text.Prettyprint.Doc.Render.Text
**>>> **let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
**>>> **let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
**
```

--------------------------------

### Setup for layoutSmart and layoutPretty examples

Source: https://hackage.haskell.org/package/prettyprinter-0.1/docs/Data-Text-Prettyprint-Doc.html

Imports necessary modules and defines helper functions for rendering documents with different layout algorithms and page widths.

```haskell
>>> **import Data.Text.IO as T
**>>> **import Data.Text.Prettyprint.Doc.Render.Text
**>>> **let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
**>>> **let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
**
```

--------------------------------

### LayoutSmart Example Setup

Source: https://hackage.haskell.org/package/prettyprinter-1.4.0/docs/Data-Text-Prettyprint-Doc-Internal.html

Sets up a document and rendering pipeline to demonstrate the difference between `layoutPretty` and `layoutSmart`. This part defines the document structure and the rendering function.

```Haskell
>>> **let fun x = hang 2 ("fun(" <> softline' <> x) <> ")"
**>>> **let doc = (fun . fun . fun . fun . fun) (align (list ["abcdef", "ghijklm"]))
**
```

```Haskell
>>> **import Data.Text.IO as T
**>>> **import Data.Text.Prettyprint.Doc.Render.Text
**>>> **let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
**>>> **let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
**
```

--------------------------------

### Doctest Setup

Source: https://hackage.haskell.org/package/prettyprinter-1/docs/src/Data-Text-Prettyprint-Doc.html

This section provides the necessary setup for running doctests, including language extensions and imports for pretty-printing and utility functions.

```haskell
:set -XOverloadedStrings
import Data.Text.Prettyprint.Doc.Render.Text
import Data.Text.Prettyprint.Doc.Util
```

--------------------------------

### Example Document Rendering

Source: https://hackage.haskell.org/package/prettyprinter-1.1/docs/src/Data-Text-Prettyprint-Doc-Render-Tutorials-TreeRenderingTutorial.html

Demonstrates how to use the defined rendering functions to create and render an example document with various HTML-like markup.

```Haskell
:set -XOverloadedStrings
import qualified Data.Text.Lazy.IO as TL

let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (
    vsep
    [
        headline "Example document"
    ,
        paragraph ("This is a" <+> color Red "paragraph" <> comma)
    ,
        paragraph ("and" <+> bold "this text is bold.")
    ]
    )
```

--------------------------------

### Smart Layout Algorithm Example (Conceptual)

Source: https://hackage.haskell.org/package/prettyprinter-1.7.1/docs/src/Prettyprinter.Internal.html

Illustrates the behavior of layoutSmart with a specific example, showing how it introduces line breaks earlier if content won't fit on a single line. This example uses a page width of 26 characters.

```haskell
>>> let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
>>> let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])

>>> go layoutPretty doc
|------------------------|
fun(fun(fun(fun(fun(
                  [ abcdef
```

--------------------------------

### Example Document Rendering

Source: https://hackage.haskell.org/package/prettyprinter-1.6.0/docs/src/Data.Text.Prettyprint.Doc.Render.Tutorials.StackMachineTutorial.html

This example shows how to render a document with various formatting elements like headlines, colored text, and bold text using the `render` function and prettyprinter utilities.

```haskell
>>> :set -XOverloadedStrings
>>> import qualified Data.Text.Lazy.IO as TL
>>> :{ 
>>> let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
>>> in go (vsep
>>>     [ headline "Example document"
>>>     , paragraph ("This is a" <+> color Red "paragraph" <> comma)
>>>     , paragraph ("and" <+> bold "this text is bold.")
>>>     ])
>>> :}
```

--------------------------------

### Example of rendering a document to stdout

Source: https://hackage.haskell.org/package/prettyprinter-1.3.0/docs/src/Data.Text.Prettyprint.Doc.Render.Text.html

Demonstrates the usage of 'putDoc' to print a simple document to standard output. This is a basic example of pretty-printing text.

```haskell
>>> putDoc ("hello" <+> "world")
```

--------------------------------

### Example Invocation of Stack Machine Rendering

Source: https://hackage.haskell.org/package/prettyprinter-1.6.1/docs/src/Data.Text.Prettyprint.Doc.Render.Tutorials.StackMachineTutorial.html

This example demonstrates how to render a document using the `render` function and `layoutPretty`. It includes setting up overloaded strings and importing necessary modules.

```haskell
let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (vsep
    [
        headline "Example document",
        paragraph ("This is a" <+> color Red "paragraph" <> comma),
        paragraph ("and" <+> bold "this text is bold.")
    ])
```

--------------------------------

### Example Invocation of Prettyprinter Rendering

Source: https://hackage.haskell.org/package/prettyprinter-1.2.0.1/docs/Data-Text-Prettyprint-Doc-Render-Tutorials-StackMachineTutorial.html

Demonstrates how to render an example document with various styles using the defined prettyprinter functions and outputs the result to the console.

```Haskell
{-# LANGUAGE OverloadedStrings #-}
import qualified Data.Text.Lazy.IO as TL

let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (
  vsep
  [
    headline "Example document"
  , paragraph ("This is a" <+> color Red "paragraph" <> comma)
  , paragraph ("and" <+> bold "this text is bold.")
  ]
)
```

--------------------------------

### Example Invocation of Stack Machine Renderer

Source: https://hackage.haskell.org/package/prettyprinter-1.7.1/docs/src/Prettyprinter.Render.Tutorials.StackMachineTutorial.html

This example demonstrates how to use the `render` function to process and display a sample document. It includes setting up overloaded strings and using pretty-printing combinators.

```haskell
-- $standalone-text

-- We can now render an example document using our definitions:

-- >>> :set -XOverloadedStrings
-- >>> import qualified Data.Text.Lazy.IO as TL
-- >>> :{
-- >>> let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
-- >>> in go (
-- >>>     vsep
-- >>>         [
-- >>>             headline "Example document"
-- >>>           , paragraph ("This is a" <+> color Red "paragraph" <> comma)
-- >>>           , paragraph ("and" <+> bold "this text is bold.")
-- >>>         ])
-- >>> :}

```

--------------------------------

### Example of putDoc

Source: https://hackage.haskell.org/package/prettyprinter-1.2.0.1/docs/src/Data-Text-Prettyprint-Doc-Render-Text.html

Demonstrates prettyprinting a simple document to standard output.

```haskell
putDoc ("hello" <+> "world")
```

--------------------------------

### Migration Guide

Source: https://hackage.haskell.org/package/prettyprinter-1.5.0/docs/src/Data.Text.Prettyprint.Doc.html

Information on migrating from older versions or other pretty-printing libraries.

```haskell
-- $migration

-- There are 3 main ways to migrate:

--   1. Direct: just replace the previous package and fix the errors
--   2. Using a drop-in replacement mimicing the API of the former module, see
--      the @prettyprinter-compat-<former package>@ packages
--   3. Using a converter from the old @Doc@ type to the new one, see the
--      @prettyprinter-convert-<former package>@ packages

-- If you're already familiar with (ansi-)wl-pprint, you'll recognize many
-- functions in this module, and they work just the same way. However, a couple
-- of definitions are missing:

--   - @char@, @string@, @double@, … – these are all special cases of the
--     overloaded @'pretty'@ function.
--   - @
-->@, @
--<$$>@, @
--</>@, @
--<//>@ are special cases of
--    @'vsep'@, @'vcat'@, @'fillSep'@, @'fillCat'@ with only two documents.
--   - If you need 'String' output, use the backends in the
--     "Data.Text.Prettyprint.Doc.Render.String" module.
--   - The /display/ functions are moved to the rendering submodules, for
--     example conversion to plain 'Text' is in the
--     "Data.Text.Prettyprint.Doc.Render.Text" module.
--   - The /render/ functions are called /layout/ functions.
--   - @SimpleDoc@ was renamed to @'SimpleDocStream'@, in order to make it
--     clearer in the presence of @SimpleDocTree@.
--   - Instead of providing an own colorization function for each
--     color/intensity/layer combination, they have been combined in 'color',
--     'colorDull', 'bgColor', and 'bgColorDull' functions, which can be found
--     in the ANSI terminal specific @prettyprinter-ansi-terminal@ package.
```

--------------------------------

### Align example with vsep

Source: https://hackage.haskell.org/package/prettyprinter-1.2.1.1/docs/Data-Text-Prettyprint-Doc-Internal.html

Demonstrates `align` causing `vsep` contents to start in the same column.

```Haskell
>>> **"lorem" <+> align (vsep ["ipsum", "dolor"])
**lorem ipsum
      dolor

```

--------------------------------

### align example

Source: https://hackage.haskell.org/package/prettyprinter-1.5.0/docs/Data-Text-Prettyprint-Doc-Internal.html

Illustrates how `align` causes subsequent lines to start at the same column, unlike default behavior.

```haskell
>>> **"lorem" <+> vsep ["ipsum", "dolor"]
**lorem ipsum
dolor

>>> **"lorem" <+> align (vsep ["ipsum", "dolor"])
**lorem ipsum
      dolor


```

--------------------------------

### Setting up document rendering with layout options

Source: https://hackage.haskell.org/package/prettyprinter-1.6.1/docs/Data-Text-Prettyprint-Doc-Internal.html

Imports necessary modules and defines a helper function 'go' to render a document with specified layout options. This setup is used to compare different layout algorithms.

```haskell
>>> **import Data.Text.IO as T
**>>> **import Data.Text.Prettyprint.Doc.Render.Text
**>>> **let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
**>>> **let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])

```

--------------------------------

### Hang example with reflowed text

Source: https://hackage.haskell.org/package/prettyprinter-1.2.1.1/docs/Data-Text-Prettyprint-Doc-Internal.html

Shows `hang` indenting reflowed text relative to the start of the first line.

```Haskell
>>> **let doc = reflow "Indenting these words with hang"
**>>> **putDocW 24 ("prefix" <+> hang 4 doc)
**prefix Indenting these
           words with
           hang

```

--------------------------------

### Basic Prettyprinter Setup

Source: https://hackage.haskell.org/package/prettyprinter-0.1/docs/Data-Text-Prettyprint-Doc-Internal.html

Sets up necessary language extensions and imports for using the prettyprinter library.

```haskell
**:set -XOverloadedStrings
**import Data.Text.Prettyprint.Doc.Render.Text
**import Data.Text.Prettyprint.Doc.Util as Util
**import Test.QuickCheck.Modifiers

```

--------------------------------

### Column-based Layout Example

Source: https://hackage.haskell.org/package/prettyprinter-1.1.0.1/docs/Data-Text-Prettyprint-Doc.html

Demonstrates how to lay out a document differently based on the starting column. Useful for aligning content relative to the current position.

```Haskell
>>> **column (\l -> "Columns are" <+> pretty l <> "-based.")
```

--------------------------------

### Rendering Pipeline Setup

Source: https://hackage.haskell.org/package/prettyprinter-0.1/docs/Data-Text-Prettyprint-Doc-Internal.html

Sets up a rendering pipeline using Data.Text.IO and Data.Text.Prettyprint.Doc.Render.Text, including a horizontal rule and a function 'go' to apply a layouter.

```haskell
import Data.Text.IO as T
import Data.Text.Prettyprint.Doc.Render.Text
let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
```

--------------------------------

### Smart Layout vs Pretty Layout Setup

Source: https://hackage.haskell.org/package/prettyprinter-1.7.0/docs/Prettyprinter.html

Sets up a complex document and a rendering pipeline to compare layoutSmart and layoutPretty.

```haskell
import Data.Text.IO as T
import Prettyprinter.Render.Text

let fun x = hang 2 ("fun(" <> softline' <> x) <> ")"
let doc = (fun . fun . fun . fun . fun) (align (list ["abcdef", "ghijklm"]))

let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
```

--------------------------------

### Example of align for vertical alignment

Source: https://hackage.haskell.org/package/prettyprinter-1.2.1/docs/src/Data.Text.Prettyprint.Doc.Internal.html

Demonstrates how 'align' causes subsequent lines to start at the same column as the initial line, contrasting with default 'vsep' behavior.

```haskell
"lorem" <+> align (vsep ["ipsum", "dolor"])
```

--------------------------------

### Show Instance Implementation

Source: https://hackage.haskell.org/package/prettyprinter-1.1.0.1/docs/Data-Text-Prettyprint-Doc-Render-String.html

Example of implementing a Show instance using renderShowS for a custom type. This leverages the prettyprinter to format the output.

```Haskell
instance Show MyType where
    showsPrec _ = renderShowS . layoutPretty defaultLayoutOptions . pretty

```

--------------------------------

### Pretty-Simple Diag Inspection

Source: https://hackage.haskell.org/package/prettyprinter-1.7.0/docs/Prettyprinter-Internal-Debug.html

Use the pretty-simple package to get a nicer layout for show'd Diag's. This example demonstrates inspecting an 'align' Doc with 'vcat'.

```haskell
> Text.Pretty.Simple.pPrintNoColor . diag $ align (vcat ["foo", "bar"])
Column
   [
       (
           10
         ,
           Nesting
             [
                 (
                     10
                   ,
                     Cat ( Text 3 "foo" )
                         ( Cat ( FlatAlt Line Empty ) ( Text 3 "bar" ) )
               )
           ]
       )
   ]

```

--------------------------------

### flatAlt Example: Basic Usage

Source: https://hackage.haskell.org/package/prettyprinter-1.7.1/docs/src/Prettyprinter.Internal.html

Demonstrates the basic rendering of flatAlt, showing the default output and the preferred output when grouped.

```Haskell
>>> let doc = flatAlt "a" "b"
>>> putDoc doc
a
>>> putDoc (group doc)
b
>>> putDocW 0 (group doc)
a
```

--------------------------------

### Pretty-print a Diag representation

Source: https://hackage.haskell.org/package/prettyprinter-1.6.0/docs/Data-Text-Prettyprint-Doc-Internal-Debug.html

Use the `pretty-simple` package to get a nicer layout for `show`n `Diag`s. This example demonstrates pretty-printing a `Diag` representation of an `align`ed `Doc`.

```haskell
>>> **Text.Pretty.Simple.pPrintNoColor . diag $ align (vcat ["foo", "bar"])
**Column
   [
       ( 10
       , Nesting
           [
               ( 10
               , Cat ( Text 3 "foo" )
                   ( Cat ( FlatAlt Line Empty ) ( Text 3 "bar" ) )
               )
           ]
       )
   ]


```

--------------------------------

### Hang vs Nest Example

Source: https://hackage.haskell.org/package/prettyprinter-1.2.1.1/docs/src/Data.Text.Prettyprint.Doc.Internal.html

Demonstrates the difference between 'hang' and 'nest' for indenting documents. 'hang' adjusts indentation relative to the start of the line, while 'nest' adjusts relative to the current nesting level.

```haskell
>>> let doc = reflow "Indenting these words with hang"
>>> putDocW 24 ("prefix" <+> hang 4 doc)
prefix Indenting these
           words with
           hang

>>> let doc = reflow "Indenting these words with nest"
>>> putDocW 24 ("prefix" <+> nest 4 doc)
prefix Indenting these
    words with nest
```

--------------------------------

### Example Document and Rendering Pipeline

Source: https://hackage.haskell.org/package/prettyprinter-1.2/docs/src/Data-Text-Prettyprint-Doc-Internal.html

Defines a sample document and sets up a rendering pipeline using Data.Text.IO and Data.Text.Prettyprint.Doc.Render.Text. This pipeline is used to demonstrate different layout algorithms.

```haskell
-- >>> let doc = (fun . fun . fun . fun . fun) (align (list ["abcdef", "ghijklm"]))
--
-- which we’ll be rendering using the following pipeline (where the layout
-- algorithm has been left open),
--
-- >>> import Data.Text.IO as T
-- >>> import Data.Text.Prettyprint.Doc.Render.Text
-- >>> let hr = pipe <> pretty (replicate (26-2) '-') <> pipe
-- >>> let go layouter x = (T.putStrLn . renderStrict . layouter (LayoutOptions (AvailablePerLine 26 1))) (vsep [hr, x, hr])
```

--------------------------------

### Prettyprinting String (Example)

Source: https://hackage.haskell.org/package/prettyprinter-1.1/docs/src/Data-Text-Prettyprint-Doc-Internal.html

Example of prettyprinting a string literal.

```Haskell
pretty ("string" :: String)
```

--------------------------------

### Example Document Rendering

Source: https://hackage.haskell.org/package/prettyprinter-0.1/docs/Data-Text-Prettyprint-Doc-Render-Tutorials-TreeRenderingTutorial.html

Demonstrates rendering a sample document with headlines, paragraphs, colored text, and bold text using the custom prettyprinter and SimpleHtml backend. Requires OverloadedStrings and IO for output.

```Haskell
>>> **:set -XOverloadedStrings
**>>> **import qualified Data.Text.Lazy.IO as TL
**>>> **:{ 
**>>> **let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
**>>> **in go (
**>>> **vsep
**>>> **[
**>>> **headline "Example document"
**>>> **, paragraph ("This is a" <+> color Red "paragraph" <> comma)
**>>> **, paragraph ("and" <+> bold "this text is bold.")
**>>> **]
**>>> **)
**>>> **:} 
**<h1>Example document</h1>
<p>This is a <span style="color: #f00">paragraph</span>,</p>
<p>and <strong>this text is bold.</strong></p>

```

--------------------------------

### Pretty Tuple Example

Source: https://hackage.haskell.org/package/prettyprinter-1.0.1/docs/Data-Text-Prettyprint-Doc.html

Example of pretty-printing a 2-element tuple where both elements are `Pretty`.

```haskell
(Pretty a1, Pretty a2) => Pretty (a1, a2)

>>> pretty (123, "hello")
**(123, "hello")
```

--------------------------------

### Haddock example for Pretty Void in prettyprinter 1.0.1

Source: https://hackage.haskell.org/package/prettyprinter-1.7.1/changelog

A Haddock example for `Pretty Void` has been added.

```markdown
* Haddock: example for `Pretty Void`
```

--------------------------------

### Example: Rendering to IO Handle

Source: https://hackage.haskell.org/package/prettyprinter-1.1/docs/src/Data-Text-Prettyprint-Doc-Render-Text.html

Demonstrates rendering a simple document to a specified IO handle, in this case, standard output. Shows direct IO rendering.

```haskell
-- | @('renderIO' h sdoc)@ writes @sdoc@ to the file @h@.
--
-- >>> renderIO System.IO.stdout (layoutPretty defaultLayoutOptions "hello\nworld")
-- hello
-- world
```

--------------------------------

### Haskell Prettyprinter: Example for Pretty Void

Source: https://hackage.haskell.org/package/prettyprinter.rss

Provides an example for Pretty Void within the Haddock documentation.

```haskell
Pretty Void
```

--------------------------------

### Example: Rendering a document with layout options

Source: https://hackage.haskell.org/package/prettyprinter-1.6.1/docs/src/Data.Text.Prettyprint.Doc.Render.Text.html

Demonstrates rendering a document with line breaks and alignment using renderLazy and layoutPretty.

```Haskell
>>> :set -XOverloadedStrings
>>> import qualified Data.Text.IO as T
>>> import qualified Data.Text.Lazy.IO as TL


>>> let render = TL.putStrLn . renderLazy . layoutPretty defaultLayoutOptions
>>> let doc = "lorem" <+> align (vsep ["ipsum dolor", parens "foo bar", "sit amet"])
>>> render doc
lorem ipsum dolor
      (foo bar)
      sit amet
```

--------------------------------

### Simple Decorated Rendering Example

Source: https://hackage.haskell.org/package/prettyprinter-1.4.0/docs/src/Data.Text.Prettyprint.Doc.Render.Util.StackMachine.html

Demonstrates rendering a document with simple annotations. It shows how to define behavior for writing text, pushing, and popping annotations.

```haskell
{-# LANGUAGE BangPatterns      #-}
{-# LANGUAGE CPP               #-}
{-# LANGUAGE OverloadedStrings #-}

#include "version-compatibility-macros.h"

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

    -- * Simple, pre-defined stack machines
    -- 
    -- | These cover most basic use cases where there is not too much special
    -- logic, and all that’s important is how to render text, and how to
    -- add/remove an annotation.
    renderSimplyDecorated,
    renderSimplyDecoratedA,

    -- * General stack machine
    -- 
    -- | These definitions allow defining a full-blown stack machine renderer,
    -- allowing for arbitrary peeking, popping and what not.
    StackMachine,
    execStackMachine,

    pushStyle,
    unsafePopStyle,
    unsafePeekStyle,
    writeOutput,
) where



import           Control.Applicative
import           Data.Text           (Text)
import qualified Data.Text           as T

import Data.Text.Prettyprint.Doc                   (SimpleDocStream (..))
import Data.Text.Prettyprint.Doc.Render.Util.Panic

#if !(SEMIGROUP_MONOID_SUPERCLASS)
import Data.Monoid
#endif


-- $setup
--
-- (Definitions for the doctests)
--
-- >>> import Data.Text.Prettyprint.Doc hiding ((<>))
-- >>> import qualified Data.Text.IO as T



-- | Simplest possible stack-based renderer.
--
-- For example, here is a document annotated with @()@, and the behaviour is to
-- write »>>>« at the beginning, and »<<<« at the end of the annotated region:
--
-- >>> let doc = "hello" <+> annotate () "world" <> "!"
-- >>> let sdoc = layoutPretty defaultLayoutOptions doc
-- >>> T.putStrLn (renderSimplyDecorated id (\() -> ">>>") (\() -> "<<<") sdoc)
-- hello >>>world<<<!
--
-- The monoid will be concatenated in a /right associative/ fashion.
renderSimplyDecorated
    :: Monoid out
    => (Text -> out) -- ^ Render plain 'Text'
    -> (ann -> out)  -- ^ How to render an annotation
    -> (ann -> out)  -- ^ How to render the removed annotation
    -> SimpleDocStream ann
    -> out
renderSimplyDecorated text push pop = go []
  where
    go _           SFail               = panicUncaughtFail
    go []          SEmpty              = mempty
    go (_:_)       SEmpty              = panicInputNotFullyConsumed
    go stack       (SChar c rest)      = text (T.singleton c) <> go stack rest
    go stack       (SText _l t rest)   = text t <> go stack rest
    go stack       (SLine i rest)      = text (T.singleton '\n') <> text (T.replicate i " ") <> go stack rest
    go stack       (SAnnPush ann rest) = push ann <> go (ann : stack) rest
    go (ann:stack) (SAnnPop rest)      = pop ann <> go stack rest
    go []          SAnnPop{}           = panicUnpairedPop
{-# INLINE renderSimplyDecorated #-}

-- | Version of 'renderSimplyDecoratedA' that allows for 'Applicative' effects.
renderSimplyDecoratedA
    :: (Applicative f, Monoid out)
    => (Text -> f out) -- ^ Render plain 'Text'
    -> (ann -> f out)  -- ^ How to render an annotation
    -> (ann -> f out)  -- ^ How to render the removed annotation
    -> SimpleDocStream ann
    -> f out
renderSimplyDecoratedA text push pop = go []
  where
    go _           SFail               = panicUncaughtFail
    go []          SEmpty              = pure mempty
    go (_:_)       SEmpty              = panicInputNotFullyConsumed
    go stack       (SChar c rest)      = text (T.singleton c) <++> go stack rest
    go stack       (SText _l t rest)   = text t <++> go stack rest
    go stack       (SLine i rest)      = text (T.singleton '\n') <++> text (T.replicate i " ") <++> go stack rest
    go stack       (SAnnPush ann rest) = push ann <++> go (ann : stack) rest
    go (ann:stack) (SAnnPop rest)      = pop ann <++> go stack rest
    go []          SAnnPop{}           = panicUnpairedPop

    (<++>) = liftA2 mappend
{-# INLINE renderSimplyDecoratedA #-}



-- | @WriterT output StateT [style] a@, but with a strict Writer value.
--
-- The @output@ type is used to append data chunks to, the @style@ is the member
-- of a stack of styles to model nested styles with.
newtype StackMachine output style a = StackMachine ([style] -> (a, output, [style]))
{-# DEPRECATED StackMachine "Writing your own stack machine is probably more efficient and customizable; also consider using »renderSimplyDecorated(A)« instead" #-}

instance Functor (StackMachine output style) where
    fmap f (StackMachine r) = StackMachine (\s ->
        let (x1, w1, s1) = r s
        in (f x1, w1, s1))

instance Monoid output => Applicative (StackMachine output style) where
    pure x = StackMachine (\s -> (x, mempty, s))
    StackMachine f <*> StackMachine x = StackMachine (\s ->
        let (f1, w1, s1) = f s
            (x2, w2, s2) = x s1
            !w12 = w1 <> w2
        in (f1 x2, w12, s2))
```

--------------------------------

### Basic Doc Concatenation Example

Source: https://hackage.haskell.org/package/prettyprinter-1.1.0.1/docs/Data-Text-Prettyprint-Doc-Internal.html

A simple example showing the concatenation of strings and a character using the `<>` operator.

```haskell
"a" <> "b" <> pretty 'c' <> "d"
```

--------------------------------

### Simple Decorated Rendering Example

Source: https://hackage.haskell.org/package/prettyprinter-1.6.1/docs/src/Data.Text.Prettyprint.Doc.Render.Util.StackMachine.html

Demonstrates rendering a document with simple annotations. It shows how to prepend '>>>' and append '<<<' to annotated text regions.

```haskell
>>> import Data.Text.Prettyprint.Doc hiding ((<>))
>>> import qualified Data.Text.IO as T

>>> let doc = "hello" <+> annotate () "world" <> "!"
>>> let sdoc = layoutPretty defaultLayoutOptions doc
>>> T.putStrLn (renderSimplyDecorated id (\() -> ">>>") (\() -> "<<<") sdoc)
hello >>>world<<<!

```

--------------------------------

### Enclose document with prefix and suffix example

Source: https://hackage.haskell.org/package/prettyprinter-1.3.0/docs/Data-Text-Prettyprint-Doc-Internal.html

Provides a simple example of using `enclose` to wrap a string literal.

```haskell
>>> **enclose "A" "Z" "·"
**A·Z
```

--------------------------------

### Compact Layout Rendering Example

Source: https://hackage.haskell.org/package/prettyprinter-1.1.0.1/docs/Data-Text-Prettyprint-Doc-Internal.html

Shows how to render a document using `layoutCompact` to standard output. This is a fast layouter that produces minimal output.

```haskell
let putDocCompact = renderIO System.IO.stdout . layoutCompact

```

```haskell
putDocCompact doc
```

```haskell
lorem
ipsum
dolor
sit

```

--------------------------------

### pretty Method Examples

Source: https://hackage.haskell.org/package/prettyprinter-1.3.0/docs/Data-Text-Prettyprint-Doc-Internal.html

Examples demonstrating the usage of the `pretty` method for different types, including integers, strings, and floating-point numbers.

```APIDOC
## Pretty Method Examples

### Pretty Int
```haskell
>>> pretty (123 :: Int)
**123
```

### Pretty Integer
```haskell
>>> pretty (2^123 :: Integer)
**10633823966279326983230456482242756608
```

### Pretty Double
```haskell
>>> pretty (exp 1 :: Double)
**2.71828182845904...
```

### Pretty Float
```haskell
>>> pretty (pi :: Float)
**3.1415927
```

### Pretty Char
```haskell
>>> pretty 'f' <> pretty 'o' <> pretty 'o'
**foo
```

### Pretty String
```haskell
>>> pretty ("string" :: String)
**string
```

### Pretty Bool
```haskell
>>> pretty True
**True
```

### Pretty List Example
```haskell
>>> prettyList [1, 23, 456]
**[1, 23, 456]
```
```

--------------------------------

### Example of renderIO with default layout

Source: https://hackage.haskell.org/package/prettyprinter-1/docs/src/Data-Text-Prettyprint-Doc-Render-Text.html

Shows how to use 'renderIO' to write a simple document to 'System.IO.stdout'. The document contains a newline character, demonstrating basic text rendering to an IO handle.

```haskell
>>> renderIO System.IO.stdout (layoutPretty defaultLayoutOptions "hello\nworld")
hello
world
```

--------------------------------

### Example Document for Layout

Source: https://hackage.haskell.org/package/prettyprinter-1.1/docs/Data-Text-Prettyprint-Doc.html

An example of a document structure that can be used to test layout algorithms. It demonstrates nested indentation and vertical separation.

```haskell
let doc = hang 4 (vsep ["lorem", "ipsum", hang 4 (vsep ["dolor", "sit"])])
```

--------------------------------

### Example Document Creation

Source: https://hackage.haskell.org/package/prettyprinter-1.7.1/docs/src/Prettyprinter.html

Creates a sample document representing a type signature for demonstration purposes.

```haskell
let doc = prettyprintDeclaration "example" ["Int", "Bool", "Char", "IO ()"]
```

--------------------------------

### Pretty-printing Setup

Source: https://hackage.haskell.org/package/prettyprinter-1.1.0.1/docs/src/Data-Text-Prettyprint-Doc.html

Configuration for doctests, enabling overloaded strings and importing necessary rendering and utility modules.

```haskell
-- $setup

-- (Definitions for the doctests)

>>> :set -XOverloadedStrings
>>> import Data.Text.Prettyprint.Doc.Render.Text
>>> import Data.Text.Prettyprint.Doc.Util

```

--------------------------------

### hang: Indenting Relative to Start of Line

Source: https://hackage.haskell.org/package/prettyprinter-1.6.2/docs/src/Data.Text.Prettyprint.Doc.Internal.html

Lays out a document with a nesting level relative to the start of the first line, allowing for indentation.

```haskell
hang :: Int -- ^ Change of nesting level, relative to the start of the first line
    -> Doc ann
    -> Doc ann
hang i d = align (nest i d)
```

--------------------------------

### Rendering an Example Document

Source: https://hackage.haskell.org/package/prettyprinter-1.6.0/docs/Data-Text-Prettyprint-Doc-Render-Tutorials-StackMachineTutorial.html

Demonstrates rendering a document with headlines, colored text, and bold text using the prettyprinter library. Ensure OverloadedStrings is enabled and necessary imports are included.

```haskell
:set -XOverloadedStrings
import qualified Data.Text.Lazy.IO as TL
let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (
vsep
[ headline "Example document"
, paragraph ("This is a" <+> color Red "paragraph" <> comma)
, paragraph ("and" <+> bold "this text is bold.")
])
```

--------------------------------

### Default Layout Options Example

Source: https://hackage.haskell.org/package/prettyprinter-1.0.1/docs/src/Data.Text.Prettyprint.Doc.Internal.html

Shows the structure and values of the default layout options.

```haskell
-- >>> defaultLayoutOptions
-- LayoutOptions {layoutPageWidth = AvailablePerLine 80 0.4}
```

--------------------------------

### Example of Doc Fusion

Source: https://hackage.haskell.org/package/prettyprinter-1.6.1/docs/src/Data.Text.Prettyprint.Doc.Internal.html

Demonstrates how concatenating small strings can be fused for efficiency. This example shows the unfused and fused versions of a string concatenation.

```haskell
>>> "a" <> "b" <> pretty 'c' <> "d"
abcd
```

```haskell
>>> "abcd" :: Doc ann
abcd
```

```haskell
>>> let oftenUsed = fuse Shallow ("a" <> "b" <> pretty 'c' <> "d")
>>> hsep (replicate 5 oftenUsed)
abcd abcd abcd abcd abcd
```

--------------------------------

### Example Invocation of Tree Rendering

Source: https://hackage.haskell.org/package/prettyprinter-1/docs/src/Data-Text-Prettyprint-Doc-Render-Tutorials-TreeRenderingTutorial.html

Demonstrates how to use the defined rendering functions to create and print an example document with various HTML markup.

```haskell
:set -XOverloadedStrings
import qualified Data.Text.Lazy.IO as TL
:{
let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (vsep
    [
        headline "Example document"
    ,
        paragraph ("This is a" <+> color Red "paragraph" <> comma)
    ,
        paragraph ("and" <+> bold "this text is bold.")
    ])
:}
```

--------------------------------

### Example Document Rendering to HTML

Source: https://hackage.haskell.org/package/prettyprinter-1.6.0/docs/Data-Text-Prettyprint-Doc-Render-Tutorials-TreeRenderingTutorial.html

Demonstrates rendering a sample document with various markup elements (headline, paragraph, bold, color) into an HTML string. Requires OverloadedStrings and specific imports.

```Haskell
{-# LANGUAGE OverloadedStrings #-}
import qualified Data.Text.Lazy.IO as TL

let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (
  vsep
    [
      headline "Example document"
    , paragraph ("This is a" <+> color Red "paragraph" <> comma)
    , paragraph ("and" <+> bold "this text is bold.")
    ]
  )
```

--------------------------------

### Example of renderSimplyDecorated usage

Source: https://hackage.haskell.org/package/prettyprinter-1.6.0/docs/Data-Text-Prettyprint-Doc-Render-Util-SimpleDocTree.html

Demonstrates how to use renderSimplyDecorated to surround annotated text with custom markers. This example shows rendering a document with annotations of type '()'.

```haskell
>>> **let doc = "hello" <+> annotate () "world" <> "!"
**>>> **let stdoc = treeForm (layoutPretty defaultLayoutOptions doc)
**>>> **T.putStrLn (renderSimplyDecorated id (	y x -> ">>>" <> x <> "<<<") stdoc)
**hello >>>world<<<!
```

--------------------------------

### Render Example Document to HTML

Source: https://hackage.haskell.org/package/prettyprinter-1.7.1/docs/src/Prettyprinter.Render.Tutorials.TreeRenderingTutorial.html

Demonstrates rendering a structured document with headlines, paragraphs, and styled text into HTML using the prettyprinter library. Requires OverloadedStrings and imports for Text.Lazy.IO.

```haskell
:set -XOverloadedStrings
import qualified Data.Text.Lazy.IO as TL
let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (vsep
    [
        headline "Example document"
    ,
        paragraph ("This is a" <+> color Red "paragraph" <> comma)
    ,
        paragraph ("and" <+> bold "this text is bold.")
    ])
```

--------------------------------

### Render Example Document

Source: https://hackage.haskell.org/package/prettyprinter-1.7.2/docs/Prettyprinter-Render-Tutorials-StackMachineTutorial.html

Demonstrates rendering a document with a headline, colored text, and bold text. Requires OverloadedStrings extension.

```haskell
**set -XOverloadedStrings
**import qualified Data.Text.Lazy.IO as TL
**let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
**in go (
vsep
[
headline "Example document"
, paragraph ("This is a" <+> color Red "paragraph" <> comma)
, paragraph ("and" <+> bold "this text is bold.")
])

```

--------------------------------

### Example: Rendering SimpleDocTree with Annotations

Source: https://hackage.haskell.org/package/prettyprinter-1.4.0/docs/src/Data.Text.Prettyprint.Doc.Render.Util.SimpleDocTree.html

Shows how to use 'treeForm' to render a document with annotations. This example uses overloaded strings and demonstrates nested annotations.

```Haskell
-- $ 
--
-- >>> :set -XOverloadedStrings
-- >>> treeForm (layoutPretty defaultLayoutOptions ("lorem" <+> "ipsum" <+> annotate True ("TRUE" <+> annotate False "FALSE") <+> "dolor"))
-- STConcat [STText 5 "lorem",STChar ' ',STText 5 "ipsum",STChar ' ',STAnn True (STConcat [STText 4 "TRUE",STChar ' ',STAnn False (STText 5 "FALSE")]),STChar ' ',STText 5 "dolor"]
```

--------------------------------

### Example Document Rendering

Source: https://hackage.haskell.org/package/prettyprinter-1.2.1.1/docs/src/Data.Text.Prettyprint.Doc.Render.Tutorials.TreeRenderingTutorial.html

Demonstrates rendering a sample document with various SimpleHtml annotations using the defined prettyprinter functions and layout options.

```haskell
:set -XOverloadedStrings
import qualified Data.Text.Lazy.IO as TL
let go = TL.putStrLn . render . layoutPretty defaultLayoutOptions
in go (vsep
    [ headline "Example document"
    , paragraph ("This is a" <+> color Red "paragraph" <> comma)
    , paragraph ("and" <+> bold "this text is bold.")
    ])
```

--------------------------------

### Combined Pretty Printing Example

Source: https://hackage.haskell.org/package/prettyprinter-1.1.0.1/docs/Data-Text-Prettyprint-Doc-Internal.html

An example showing how to combine different pretty-printed values using the `<+>` operator for spacing. This demonstrates composing Doc values.

```haskell
>>> pretty 1 <+> pretty "hello" <+> pretty 1.234
**1 hello 1.234
```