Data.Text.Prettyprint.Doc.Render.Tutorials.StackMachineTutorial

Deprecated: Writing your own stack machine is probably more efficient and customizable; also consider using »renderSimplyDecorated(A)« instead

This module shows how to write a custom prettyprinter backend, based on directly converting a SimpleDocStream to an output format using a stack machine. For a tree serialization approach, which may be more suitable for certain output formats, see Data.Text.Prettyprint.Doc.Render.Tutorials.TreeRenderingTutorial.

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.

Documentation

data Color

Constructors

Red

Green

Blue

data SimpleHtml

Constructors

Bold

Italics

Color Color

Paragraph

Headline

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

renderStackMachine :: SimpleDocStream SimpleHtml -> StackMachine Builder SimpleHtml ()

The StackMachine 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 StackMachine creations will look like this definition: a recursive walk through the SimpleDocStream, 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 renderTree.

htmlTag :: SimpleHtml -> (Builder, Builder)

Convert a SimpleHtml annotation to a pair of opening and closing tags. This is where the translation of style to raw output happens.

render :: SimpleDocStream SimpleHtml -> Text

We can now wrap our stack machine definition from renderStackMachine in a nicer interface; on successful conversion, we run the builder to give us the final Text, 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 renderStackMachine, and is the main API function of a stack machine renderer. The tree renderer equivalent to this is render.