prettyprinter-1.5.1: A modern, easy to use, well-documented, extensible pretty-printer.

Safe HaskellSafe
LanguageHaskell2010

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

Description

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.

Synopsis

Documentation

data Color Source #

Constructors

Red 
Green 
Blue 

data SimpleHtml Source #

Constructors

Bold 
Italics 
Color Color 
Paragraph 
Headline 

bold :: Doc SimpleHtml -> Doc SimpleHtml Source #

italics :: Doc SimpleHtml -> Doc SimpleHtml Source #

paragraph :: Doc SimpleHtml -> Doc SimpleHtml Source #

headline :: Doc SimpleHtml -> Doc SimpleHtml Source #

color :: Color -> Doc SimpleHtml -> Doc SimpleHtml Source #

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

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) Source #

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 Source #

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.