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

8.0

top ← prev up next →

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

Mike Sperber

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.

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

(require simple-tree-text-markup/data)
	package: simple-tree-text-markup-lib

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

procedure
(markup? object) → boolean?
object : any

Returns #t if object is a markup object, #f otherwise.

struct
(struct empty-markup ())

This is an empty markup object, which consumes no space.

struct
(struct horizontal-markup (markups))
markups : (listof markup?)

This markup object contains several sub-markups, which will be arranged horizontally when rendered.

struct
(struct vertical-markup (markups))
markups : (listof markup?)

This markup object contains several sub-markups, which will be arranged vertically when rendered.

struct
(struct srcloc-markup (srcloc markup))
srcloc : srcloc?
markup : markup?

This markup object represents a link to a source location, represented by srcloc, where the link visualization is represented by markup.

struct
(struct framed-markup (markup))
markup : markup?

This markup object puts a frame around markup.

2 Markup Construction

(require simple-tree-text-markup/construct)
	package: simple-tree-text-markup-lib

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.

procedure
(srcloc-markup srcloc markup) → markup?
srcloc : srcloc?
markup : markup?

This constructs a markup object that will represent a link to a source location, represented by srcloc, where the link visualization is represented by markup.

procedure
(framed-markup markup) → markup?
markup : markup?

This markup constructor puts a frame around markup.

value
empty-markup : markup?

This is the empty markup object.

value
empty-line : markup?

This is a markup object representing an empty line, i.e. empty vertical space.

procedure
(horizontal markup ...) → markup?
markup : markup?

This procedure arranges the markup arguments horizontally.

procedure
(vertical markup ...) → markup?
markup : markup?

This procedure arranges the markup arguments vertically.

3 Rendering Markup to Text

(require simple-tree-text-markup/text)
	package: simple-tree-text-markup-lib

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

procedure
(display-markup markup [output-port]) → any
markup : markup?
output-port : output-port? = (current-output-port)

Renders a textual version of markup to output-port. It uses Unicode lines and corners to display framed markup.

top ← prev up next →

1	Markup Representation
2	Markup Construction
3	Rendering Markup to Text