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

8.1

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. 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

(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
an image-markup

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

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.

struct
(struct image-markup (data alt-markup))
data : any/c
alt-markup : markup?

This markup object represents an image. The data contains the image data. The format is not exactly specified, but a graphical renderer should accept bitmap%, snip%, and record-dc-datum objects.

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

struct
(struct record-dc-datum (datum width height)
    #:extra-constructor-name make-record-dc-datum)
  datum : any/c
  width : natural-number/c
  height : natural-number/c

This represents an image, containing the result the get-recorded-datum from record-dc%, as well as the width and height of that image.

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.

procedure
(markup-transform-image-data transform-image-data
markup) → markup?
transform-image-data : (any/c . -> . any/c)
markup : markup?

This walks over a markup tree, leaving everything unchanged except image-markup values. For those, it applies transform-image-data to its datafield, replacing it by the return value.

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.

4 Generating Markup From a Port

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

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

procedure
(make-markup-output-port special->markup)
→
output-port? (-> markup?)
special->markup : (any/c . -> . markup?)

This procedure returns an output port and a thunk.

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.

procedure
(make-markup-output-port/unsafe special->markup)
→
output-port? (-> markup?)
special->markup : (any/c . -> . markup?)

Thread-unsafe version of make-markup-output-port.

top ← prev up next →

1	Markup Representation
2	Markup Construction
3	Rendering Markup to Text
4	Generating Markup From a Port