Simple Tree Text Markup:   Simple Markup for Display as Text or in GUI
1 Markup Representation
markup?
empty-markup
horizontal-markup
vertical-markup
srcloc-markup
framed-markup
image-markup
record-dc-datum
2 Markup Construction
srcloc-markup
framed-markup
empty-markup
empty-line
horizontal
vertical
markup-transform-image-data
3 Rendering Markup to Text
display-markup
4 Generating Markup From a Port
make-markup-output-port
make-markup-output-port/  unsafe
8.0.900

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:

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.

This is the empty markup object.

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.