module lang::box::\syntax::Box

rascal-Not specified

An abstract declarative language for two dimensional text layout

Usage

import lang::box::\syntax::Box;

Dependencies

import List;

data Box

Every kind of boxes encodes one or more parameterized two-dimensional text constraints.

data Box (int hs=1, int vs=0, int is=4) 
     = H_(list[Box] boxes)
     | V_(list[Box] boxes)
     | HOV_(list[Box] boxes)
     | HV_(list[Box] boxes)
     | I_(list[Box] boxes)
     | WD_(list[Box] boxes)
     | A_(list[Row] rows, Box rs=NULL(), list[Alignment] columns=[])
     | AG_(list[Box] boxes, int gs=2, list[Alignment] columns=[], Box rs=NULL())
     | SPACE(int space)
     | L(str word)
     | U_(list[Box] boxes)
     | G_(list[Box] boxes, bool backwards=false, int gs=2, Box op = H([]))
     | NULL()
     ;

• H puts their elements next to each other one the same line separated by hs spaces.
• V puts their elements below each other on their own line, separated by vs empty lines.
• HOV acts like H as long as the elements all fit on one line, otherwise it becomes a V
• HV acts like H until the line is full, and then continues on the next line like V.
• I is a V box that indents every line in the output with is spaces
• WD produces a number of spaces exactly as wide as the wides line of the constituent boxes
• A is a table formatter. The list of Rows is formatted with H but each cell is aligned vertically with the rows above and below.
• SPACE produces space spaces
• L produces A literal word. This word may only contain printable characters and no spaces; this is a required property that the formatting algorithm depends on for correctness.
• U splices its contents in the surrounding box, for automatic flattening of overly nested structures in syntax trees.
• G is an additional group-by feature for list[Box] that reduces tot the above core features. You can use it to wrap another box around every gs elements.
• AG is an additional group-by feature for array Rows that reduces to the above core features. You can use it to wrap a R row around every gs elements and then construct an A around those rows.
• NULL() is the group that will dissappear from its context, useful for skipping content. It is based on the U box.

Benefits

• Box expressions are a declarative mechanism to express formatting rules that are flexible enough to deal with limited horizontal space, and satisfy the typical alignment and indentation principles found in the coding standards for programming languages.
• The parameters of Box expressions allow for full configuration. It is up to the code that produces Box expressions to present these parameters to the user or not. For example, indentation level is should be set on every I Box according to the current preferences of the user.

Pitfalls

• U(boxes) is rendered as H(boxes) if it's the outermost Box.

function H

Box H(Box boxes..., int hs=1)

function V

Box V(Box boxes..., int vs=0)

function HOV

Box HOV(Box boxes..., int hs=1, int vs=0)

function HV

Box HV(Box boxes..., int hs=1, int vs=0)

function I

Box I(Box boxes...)

function WD

Box WD(Box boxes...)

function A

Box A(Row rows..., Box rs=NULL(), list[Alignment] columns=[])

function AG

Box AG(Box boxes..., int gs=2, list[Alignment] columns=[], Box rs=NULL())

function U

Box U(Box boxes...)

function G

Box G(Box boxes..., bool backwards=false, int gs=2, Box op = H([]))

data Row

A row is a list of boxes that go into an A array/table.

data Row  
     = R(list[Box] cells)
     ;

Rows do not have parameters. These are set on the A level instead, or per cell Box.

data Alignment

data Alignment  
     = l()
     | r()
     | c()
     ;

function NULL

NULL can be used to return a Box that will completely disappear in the surrounding context.

Box NULL()

Consider NULL()`` as an alternative to producing H([])` when you see unexpected additional spaces generated.

Typical applications for NULL would be to produce it for layout nodes that contain only whitespace. If you encounter source code comments you can produce the appropriate L content, but if you want the position ignored, use NULL.

NULL`` depends on the splicing semantics of U` to disappear completely before the layout algorithm starts counting boxes and widths.

Examples

• H([L("A"), H([]),L("B")]) will produce "A B" with two spaces;
• H([L("A"), NULL(),L("B")]) will produce "A B" with only one space.

Pitfalls

• Do not use NULL for empty Row cells, unless you do want your cells aligned to the left and filled up to the right with empty H boxes.
• NULL will be formatted as H([]) if it's the outermost Box.

function SL

Convenience box for adding separators to an existing box list

Box SL(list[Box] boxes, Box sep, Box op = H([], hs=0))

Each element is wrapped by the op operator together with the next separator. The resulting list is wrapped by a G box, of which the elements will be spliced into their context.

function debUG

Flatten and fold U and G boxes to simplify the Box structure

Box debUG(Box b)

U and G and AG boxes greatly simplify the Box tree before it is formatted. This happens "just-in-time" for efficiency reasons. However, from a Box tree with many U and G boxes it can become hard to see what the actual formatting constraints are going to be.

This function applies the semantics of G and U and returns a Box that renders exactly the same output, but with a lot less nested structure.

Benefits

• useful to debug complex toBox mappings
• formatting semantics preserving transformation

Pitfalls

• only useful for debugging purposes, because it becomes a pipeline bottleneck otherwise.

function H0

Short-hand for H(hs=0)

Box H0(Box boxes...)

function H1

Short-hand for H(hs=1)

Box H1(Box boxes...)

function HOV0

Short-hand for `HOV(hs=0)``

Box HOV0(Box boxes ...)

function HV0

Short-hand for `HV(hs=0)``

Box HV0(Box boxes...)

function IH

Short-hand for indented H

Box IH(Box boxes..., int hs=1)

function IV

Short-hand for indented V

Box IV(Box boxes..., int hs=1)

function IHOV

Short-hand for indented HOV

Box IHOV(Box boxes..., int hs=1, int vs=0)

function IHV

Short-hand for indented HV

Box IHV(Box boxes..., int hs=1, int vs=0)