Data.Tree.Render.Text

Configurable text rendering of trees.

Example renderings for:

import Data.Tree
import Data.Tree.Render.Text

tree :: Tree String
tree
  = Node "Add"
    [ Node "Add"
      [ Node "0" []
      , Node "Mul"
        [ Node "1" []
        , Node "2" []
        ]
      ]
    , Node "Neg"
      [ Node "Max"
        [ Node "3" []
        , Node "4" []
        , Node "5" []
        , Node "Var"
          [ Node "x" []
          ]
        , Node "6" []
        ]
      ]
    ]

renderTree (tracedRenderOptions id) tree

● Add
├─● Add
│ ├─● 0
│ ╰─● Mul
│   ├─● 1
│   ╰─● 2
╰─● Neg
  ╰─● Max
    ├─● 3
    ├─● 4
    ├─● 5
    ├─● Var
    │ ╰─● x
    ╰─● 6

Other renderings by setting 'ParentLocation' and 'ChildOrder' in the options:

  ╭─● 0         ╭─● 0       ● Add             ╭─● 6         ╭─● 6
  │ ╭─● 1     ╭─● Add       ├─● Neg           │ ╭─● x       │ ╭─● x
  │ ├─● 2     │ │ ╭─● 1     │ ╰─● Max         ├─● Var       ├─● Var
  ├─● Mul     │ ╰─● Mul     │   ├─● 6         ├─● 5         ├─● 5
╭─● Add       │   ╰─● 2     │   ├─● Var       ├─● 4       ╭─● Max
│   ╭─● 3     ● Add         │   │ ╰─● x       ├─● 3       │ ├─● 4
│   ├─● 4     ╰─● Neg       │   ├─● 5       ╭─● Max       │ ╰─● 3
│   ├─● 5       │ ╭─● 3     │   ├─● 4     ╭─● Neg       ╭─● Neg
│   │ ╭─● x     │ ├─● 4     │   ╰─● 3     │   ╭─● 2     ● Add
│   ├─● Var     ╰─● Max     ╰─● Add       │   ├─● 1     │   ╭─● 2
│   ├─● 6         ├─● 5       ├─● Mul     │ ╭─● Mul     │ ╭─● Mul
│ ╭─● Max         ├─● Var     │ ├─● 2     │ ├─● 0       │ │ ╰─● 1
├─● Neg           │ ╰─● x     │ ╰─● 1     ├─● Add       ╰─● Add
● Add             ╰─● 6       ╰─● 0       ● Add           ╰─● 0

Documentation

data ParentLocation

Describes where a parent node is rendered, relative to its children.

Constructors

ParentBeforeChildren

Renders the parent before any of its children.

ParentAfterChildren

Renders the parent after all of its children.

ParentBetweenChildren

Renders the parent in the middle of its children (if there are multiple children). The index is rounded down when using FirstToLast and rounded up when using LastToFirst.

ParentAtChildIndex Int

This is a value from [0, 1, ..., length children] inclusive. (Values outside this range are clamped to the closest valid value.)

A value of 0 makes the parent rendered before any of its children A value of length children makes the parent rendered after all of its children. Other values place the parent in the corresponding spot between its children.

Instances

Eq ParentLocation

Defined in Data.Tree.Render.Text

Methods

(==) :: ParentLocation -> ParentLocation -> Bool

(/=) :: ParentLocation -> ParentLocation -> Bool

Ord ParentLocation

Defined in Data.Tree.Render.Text

Methods

compare :: ParentLocation -> ParentLocation -> Ordering

(<) :: ParentLocation -> ParentLocation -> Bool

(<=) :: ParentLocation -> ParentLocation -> Bool

(>) :: ParentLocation -> ParentLocation -> Bool

(>=) :: ParentLocation -> ParentLocation -> Bool

max :: ParentLocation -> ParentLocation -> ParentLocation

min :: ParentLocation -> ParentLocation -> ParentLocation

Show ParentLocation

Defined in Data.Tree.Render.Text

Methods

showsPrec :: Int -> ParentLocation -> ShowS

show :: ParentLocation -> String

showList :: [ParentLocation] -> ShowS

data ChildOrder

Describes the render order of a node's children.

Constructors

FirstToLast

LastToFirst

Instances

Eq ChildOrder

Defined in Data.Tree.Render.Text

Methods

(==) :: ChildOrder -> ChildOrder -> Bool

(/=) :: ChildOrder -> ChildOrder -> Bool

Ord ChildOrder

Defined in Data.Tree.Render.Text

Methods

compare :: ChildOrder -> ChildOrder -> Ordering

(<) :: ChildOrder -> ChildOrder -> Bool

(<=) :: ChildOrder -> ChildOrder -> Bool

(>) :: ChildOrder -> ChildOrder -> Bool

(>=) :: ChildOrder -> ChildOrder -> Bool

max :: ChildOrder -> ChildOrder -> ChildOrder

min :: ChildOrder -> ChildOrder -> ChildOrder

Show ChildOrder

Defined in Data.Tree.Render.Text

Methods

showsPrec :: Int -> ChildOrder -> ShowS

show :: ChildOrder -> String

showList :: [ChildOrder] -> ShowS

data BranchPath

A part of a path along a rendered tree.

Constructors

BranchUp

Describes a turn going up toward the left.

e.g. "╭─"

BranchDown

Describes a turn going down toward the left.

e.g. "╰─"

BranchJoin

Describes a T-join of a path going up and down toward the left.

e.g. "├─"

BranchContinue

Describes a path going up and down.

e.g. "│ "

BranchEmpty

Describes a part that does NOT contain a path piece.

e.g. " "

Instances

Eq BranchPath

Defined in Data.Tree.Render.Text

Methods

(==) :: BranchPath -> BranchPath -> Bool

(/=) :: BranchPath -> BranchPath -> Bool

Ord BranchPath

Defined in Data.Tree.Render.Text

Methods

compare :: BranchPath -> BranchPath -> Ordering

(<) :: BranchPath -> BranchPath -> Bool

(<=) :: BranchPath -> BranchPath -> Bool

(>) :: BranchPath -> BranchPath -> Bool

(>=) :: BranchPath -> BranchPath -> Bool

max :: BranchPath -> BranchPath -> BranchPath

min :: BranchPath -> BranchPath -> BranchPath

Show BranchPath

Defined in Data.Tree.Render.Text

Methods

showsPrec :: Int -> BranchPath -> ShowS

show :: BranchPath -> String

showList :: [BranchPath] -> ShowS

data LocalContext label

Local context about a node.

Constructors

LocalContext

Fields

• lcCurrentNode :: Tree label

  The node assiated with this context.

• lcCurrentDepth :: !Int

  The depth of the current node.

• lcLitterIndex :: !Int

  The index of the current node with respect to its parent's children.

• lcLitterSize :: !Int

  The number of children the current node's parent has.

data RenderOptionsM m string label

Options used for rendering a Tree.

Constructors

RenderOptions

Fields

• oParentLocation :: Maybe (LocalContext label) -> m ParentLocation

  Controls where parent nodes are rendered.

  A value of Nothing is passed when rending the artificial root of a Forest.

  Simple use cases would use a constant function ignoring the local context.

• oChildOrder :: Maybe (LocalContext label) -> m ChildOrder

  Controls the order a node's children are rendered.

  A value of Nothing is passed when rending the artificial root of a Forest.

  Simple use cases would use a constant function ignoring the local context.

• oVerticalPad :: Int

  The amount of vertical spacing between nodes.

• oPrependNewline :: Bool

  If True, a newline is prepended to the rendered output.

• oWriteNewline :: m ()

  Writes a newline.

• oWrite :: string -> m ()

  Writes a string.

• oShowNodeLabel :: Maybe label -> m string

  Shows a rootLabel. The returned value should contain no newlines.

• oNodeMarker :: Maybe (LocalContext label) -> m string

  Get the marker for a node (without rendering its label). The returned value should contain no newlines.

  LocalContext is passed as an argument to allow things such as:

  • Rendering a node marker differently for labels that fail to pass a test.
  • Highlighting a node currently being visited.
  • Numbered bullets.

  A value of Nothing is passed when rending the artificial root of a Forest.

  Simple use cases would typically ignore the local context.

• oShowBranchPath :: BranchPath -> string

  Shows a BranchPath. The returned value should contain no newlines and should all be of the same printed width when rendered as text.

type RenderOptions = RenderOptionsM (Writer (DList Char))

An alias of RenderOptionsM for producing pure String renders.

renderTree :: RenderOptions String label -> Tree label -> String

Renders a Tree to a String.

renderForest :: RenderOptions String label -> Forest label -> String

Renders a Forest to a String.

renderTreeM :: Monad m => RenderOptionsM m string label -> Tree label -> m ()

Renders a pretty printed Tree within a monadic context.

renderForestM :: Monad m => RenderOptionsM m string label -> Forest label -> m ()

Renders a pretty printed Forest within a monadic context.

tracedRenderOptions

Arguments

:: (label -> String)

Shows a rootLabel.

-> RenderOptions String label

A simplified tracedRenderOptionsM specialized to RenderOptions.

tracedRenderOptionsAscii

Arguments

:: (label -> String)

Shows a rootLabel.

-> RenderOptions String label

A simplified tracedRenderOptionsAsciiM specialized to RenderOptions.

middleCutRenderOptions

Arguments

:: (label -> String)

Shows a rootLabel.

-> RenderOptions String label

A simplified middleCutRenderOptionsM specialized to RenderOptions.

zigZagRenderOptions

Arguments

:: (label -> String)

Shows a rootLabel.

-> RenderOptions String label

A simplified zigZagRenderOptionsM specialized to RenderOptions.

tabbedRenderOptions

Arguments

:: String

The string used for a tab.

-> (label -> String)

Shows a rootLabel.

-> RenderOptions String label

A simplified tabbedRenderOptionsM specialized to RenderOptions.

tracedRenderOptionsM

Arguments

:: Monad m

=> (String -> string)

Promotes a String to a string.

-> (string -> m ())

Writes a string.

-> (label -> m string)

Shows a rootLabel.

-> RenderOptionsM m string label

Options for rendering a line-traced tree using unicode drawing characters.

This uses:

BranchUp       -> "╭─"
BranchDown     -> "╰─"
BranchJoin     -> "├─"
BranchContinue -> "│ "
BranchEmpty    -> "  "

oNodeMarker = \case
  Just {} -> "● "
  Nothing -> "●"

tracedRenderOptionsAsciiM

Arguments

:: Monad m

=> (String -> string)

Promotes a String to a string.

-> (string -> m ())

Writes a string.

-> (label -> m string)

Shows a rootLabel.

-> RenderOptionsM m string label

Options for rendering a line-traced tree using ASCII characters.

This uses:

BranchUp       -> ",-"
BranchDown     -> "`-"
BranchJoin     -> "|-"
BranchContinue -> "| "
BranchEmpty    -> "  "

oNodeMarker = \case
  Just {} -> "o "
  Nothing -> "o"

middleCutRenderOptionsM

Arguments

:: Monad m

=> (String -> string)

Promotes a String to a string.

-> (string -> m ())

Writes a string.

-> (label -> m string)

Shows a rootLabel.

-> RenderOptionsM m string label

A variety on tracedRenderOptionsM where the path tracing is performed in a zig-zag-like fashion such that there is a cut down the middle of a node's children.

zigZagRenderOptionsM

Arguments

:: Monad m

=> (String -> string)

Promotes a String to a string.

-> (string -> m ())

Writes a string.

-> (label -> m string)

Shows a rootLabel.

-> RenderOptionsM m string label

A variety on tracedRenderOptionsM where the path tracing is performed in a zig-zag fashion.

tabbedRenderOptionsM

Arguments

:: Monad m

=> String

The string used for a tab.

-> (String -> string)

Promotes a String to a string.

-> (string -> m ())

Writes a string.

-> (label -> m string)

Shows a rootLabel.

-> RenderOptionsM m string label

Options for rendering a tree in rows indented only by tabs.