Simple Tree Text Markup: Simple Markup for Display as Text or in GUI

This is a tree-based combinator library for simple markup, mainly for displaying messages in a REPL. It features horizontal and vertical composition as well as framed markup. Its main distinguishing feature is its ability to embed source locations, which can be rendered as links.

This package comes with separate modules for inspecting and constructing markup - simple-tree-text-markup/data and simple-tree-text-markup/construct, respectively. Markup can also be constructed through a custom output port, supplied by simple-tree-text-markup/port.

There’s also a module simple-tree-text-markup/text that renders markup to text. Rendering markup to GUI is quite context-specific. Hence, the code for rendering to GUIs is implemented with specific applications, such as DrRacket or the test engine.

1 Markup Representation

This module defines the representation for markup as a set of struct definitions. It should be required when inspecting markup, For constructing markup, see simple-tree-text-markup/construct.

A markup object can be one of the following:

• a string

• an empty-markup

• a horizontal-markup

• a vertical-markup

• a srcloc-markup

• a framed-markup

• an image-markup

• a number-markup

If rendering of data is not possible, alt-markup can be substituted.

The exact-prefix argument specifies whether the representation should carry a #e prefix: Always, never, or when necessary to identify a representation that would otherwise be considered inexact.

Similarly for inexact-prefix. Note however that 'when-necessary is usually equivalent to 'never, as inexact numbers are always printed with a decimal dot, which is sufficient to identify a number representation as inexact.

The fraction-view field specifies how exact non-integer reals - fractions - should be rendered: As a mixed fraction, an improper fraction, or a decimal, possibly identifying periodic digits. For 'decimal, if it’s not possible to render the number as a decimal exactly, a fraction representation might be generated. For 'mixed an improper fraction representation might be generated if a mixed representation could not be read back.

If fraction-view is #f, this option comes from some unspecified user preference.

The monoid itself is defined by combine (its binary operation) and identity (its identity / neutral element).

The extractors list consists of pairs: Each pair consists of a predicate on markup nodes (usually string?, empty-markup? etc.) and a procedure to map a node, for which the predicate returns a true value, to an element of the monoid.

The following example extracts a list of source locations from a markup tree:

(define markup-srclocs

(markup-folder append '()

`((,srcloc-markup? . ,(lambda (markup)

(list (srcloc-markup-srcloc markup)))))))

The following example transforms each piece of image data in a markup tree:

(define (markup-transform-image-data transform-image-data markup)

(transform-markup

`((,image-markup? . ,(lambda (data alt-markup)

(image-markup (transform-image-data data) alt-markup))))

markup))

2 Markup Construction

While the struct definitions in simple-tree-text-markup/data can also be used for constructing markup, the procedures exported here are somewhat more convenient to use, and do a fair amount of normalization upon constructions.

The exact-prefix argument specifies whether the representation should carry a #e prefix: Always, never, or when necessary to identify a representation that would otherwise be considered inexact.

Similarly for inexact-prefix. Note however that 'when-necessary is usually equivalent to 'never, as inexact numbers are always printed with a decimal dot, which is sufficient to identify a number representation as inexact.

The fraction-view field specifies how exact non-integer reals - fractions - should be rendered: As a mixed fraction, an improper fraction, or a decimal, possibly identifying periodic digits. For 'decimal, if it’s not possible to render the number as a decimal exactly, a fraction representation might be generated. For 'mixed an improper fraction representation might be generated if a mixed representation could not be read back.

If fraction-view is #f, this option comes from some unspecified user preference.

3 Rendering Markup to Text

This module renders markup to text by printing to a port.

4 Generating Markup From a Port

This modules define procedures for creating output ports whose output is captured as a markup object.

The thunk will return whatever has been output to the port as a markup object.

The port also supports write-special: Any object output through it will be converted into markup by the special->markup procedure.