The PPML library#

Program notes need to be stored and later displayed in browsers. This presents us with two problems. At the point of creation we have no way of knowing the column width that will be used when the note is displayed. There may even be more than one width if we want to be smart when a browser window is resized. A second problem arises if we store a program note in the form of a condition string + arguments and the arguments are context sensitive. We could just save everything as a string, but then the logical structure of the message is lost. An alternative is to store the text in a more structured form. This is the purpose of the <ppml> class and its derivatives. The interface is based on Oppen’s 1980 TOPLAS paper.

A PPML document, represented as <ppml> is a tree of PPML tokens. The tokens available and their associated constructor functions are:

Structure is provided through instances of <ppml-block> and <ppml-separator-block> as they can contain subnodes of PPML.

Constructing a PPML Document#

Constructing a PPML document is typically done by using the various constructor functions:

define compiler-sideways method as
    (class == <ppml>, o :: <&generic-function>)
 => (ppml :: <ppml>)
  let sig = model-signature(o);
  if (sig)
    ppml-block(vector(ppml-string(o.^function-name),
                      ppml-break(),
                      as(<ppml>, sig)))
  else
    ppml-string(o.^function-name)
  end;
end method;

Printing a PPML Document#

Given a PPML document, the best way to print it is via ppml-print:

ppml-print(ppml, make(<ppml-printer>, margin: 100));

The PPML module#

PPML Tokens and Constructors#

<ppml> Abstract Class#
Superclasses:

<object>

Discussion:

The abstract base class for all PPML tokens.

<ppml-block> Class#
Superclasses:

<ppml>

Init-Keywords:
Discussion:

To add structure to the output, we can package up a sequence of tokens into a block. There are a couple of attributes associated with a block. The offset indicates how much to indent subsequent lines of the block if a break is necessary. When a block is longer than a line then we have a number of options. We can display as much on each line as possible, only breaking when really necessary. Alternatively, we can break the block at each break point, e.g.:

aaa             aaa bbb
bbb             ccc ddd
ccc
ddd

The choice of layout depends on whether the break-type attribute of the block is #"consistent" or #"inconsistent". The third alternative is #"fit". This suppresses all breaks and truncates the output if it won’t fit on a line.

The size of the block is cached in the block for efficiency.

ppml-block Function#
Signature:

ppml-block (constituents #key offset type) => (ppml)

Parameters:
Values:
Discussion:

Construct a <ppml-block>.

<ppml-break> Class#
Superclasses:

<ppml>

Init-Keywords:

  • blank-space – An instance of <nat>.

  • offset – An instance of <nat>.

Discussion:

A <ppml-break> indicates a position in the output where it is permissible to break the output if it won’t fit on a single line. If we don’t need to break the line then we output blank-space spaces. If we do need to break then we indent offset spaces relative to the current line indent.

ppml-break Function#
Signature:

ppml-break (#key space offset) => (ppml)

Parameters:

  • space (#key) – An instance of <nat>.

  • offset (#key) – An instance of <nat>.

Values:
Discussion:

Construct a <ppml-break>.

<ppml-browser-aware-object> Class#
Superclasses:

<ppml>

Init-Keywords:
Discussion:

The browser “knows” about some of the objects manipulated by the compiler, e.g. the various kinds of definition, and so we store these directly. Furthermore we recompute the ppml representation of the object every time token-size is called as the representation may depend on browser settings.

ppml-browser-aware-object Function#
Signature:

ppml-browser-aware-object (o) => (ppml)

Parameters:
Values:
Discussion:

Construct a <ppml-browser-aware-object>.

<ppml-separator-block> Class#
Superclasses:

<ppml-block>

Init-Keywords:
Discussion:

When constructing blocks representing collections it is wasteful to explicitly store the separators between elements. The <ppml-separator-block> class captures this common case.

The default value for the separator is vector(ppml-string(","), ppml-break(space: 1)).

ppml-separator-block Function#
Signature:

ppml-separator-block (constituents #key separator offset type left-bracket right-bracket) => (ppml)

Parameters:

  • constituents – An instance of <ppml-sequence>.

  • separator (#key) – An instance of <ppml-sequence>.

  • offset (#key) – An instance of <nat>.

  • type (#key) – An instance of <ppml-break-type>. The default value is #"inconsistent".

  • left-bracket (#key) – An instance of false-or(<ppml>).

  • right-bracket (#key) – An instance of false-or(<ppml>).

Values:

  • ppml – An instance of <ppml>.

Discussion:

Construct a <ppml-separator-block>.

<ppml-string> Class#
Superclasses:

<ppml>

Init-Keywords:
Discussion:

The simplest ppml token is just a string.

ppml-string Function#
Signature:

ppml-string (str) => (ppml)

Parameters:
Values:
Discussion:

Construct a <ppml-string>.

<ppml-suspension> Class#
Superclasses:

<ppml>

Init-Keywords:
Discussion:

Sometimes it is more space efficient to delay the construction of the <ppml> equivalent of an object until we need to print it. The <ppml-suspension> class supports this. It contains either a <ppml> token, or a pair of a function and its arguments. When we need a token and encounter the pair we apply the function to its arguments. This should return an instance of <ppml>. Optionally we can overwrite the pair by the result.

ppml-suspension Function#
Signature:

ppml-suspension (fun #rest args) => (ppml)

Parameters:
Values:
Discussion:

Construct a <ppml-suspension>.

Conversion to PPML#

as(class == <ppml>, <object>) Method#
Parameters:
Values:

  • ppml – An instance of <ppml>.

Discussion:

Returns the result of calling print-object on the object as PPML. (It does this by using "%=" along with format-to-string.

as(class == <ppml>, <byte-string>) Method#
Parameters:
Values:

  • ppml – An instance of <ppml>.

Discussion:

Returns the quoted string value as PPML.

as(class == <ppml>, <symbol>) Method#
Parameters:
Values:

  • ppml – An instance of <ppml>.

Discussion:

Returns the string value of the symbol as PPML.

as(class == <ppml>, <collection>) Method#
Parameters:
Values:

  • ppml – An instance of <ppml>.

Discussion:

Returns PPML representing the collection as a comma-separated list surrounded by #(...).

as(class == <ppml>, <explicit-key-collection>) Method#
Parameters:
Values:

  • ppml – An instance of <ppml>.

Discussion:

Returns PPML representing the collection.

as(class == <ppml>, <vector>) Method#
Parameters:
Values:

  • ppml – An instance of <ppml>.

Discussion:

Returns PPML representing the vector as a comma-separated list surrounded by #[...].

as(class == <ppml>, <list>) Method#
Parameters:

  • class – The class <ppml>.

  • object – An instance of <list>.

Values:

  • ppml – An instance of <ppml>.

Discussion:

Returns PPML representing the list as a comma-separated list surrounded by #(...).

Printing / Formatting#

format-to-ppml Generic function#
Signature:

format-to-ppml (string #rest args) => (ppml)

Parameters:
Values:

  • ppml – An instance of <ppml>.

Discussion:

We insert breaks at the places where arguments are inserted in the format string. This will hopefully give us reasonable output, but not always as good as we could do by hand. We separate out the processing of the format string so that we can share the constant components of the resulting ppml-block if the same format expression is used multiple times.

ppml-format-string Generic function#
Signature:

ppml-format-string (string) => (f)

Parameters:
Values:
Discussion:

Used by format-to-ppml.

ppml-print Generic function#
Signature:

ppml-print (t pp) => ()

Parameters:
Discussion:

This is the best way to display PPML.

ppml-print-one-line Generic function#
Signature:

ppml-print-one-line (t pp) => ()

Parameters:
Discussion:

This prints in the same way as ppml-print, but will limit the output to a single line. It does this by internally using a line-break-type of #"fit".

<ppml-printer> Class#
Superclasses:

<object>

Init-Keywords:

  • margin – An instance of <nat>.

  • newline-function – An instance of <function>, taking no arguments. The default value writes a newline to *standard-output*.

  • output-function – An instance of <function>, taking a single <string> argument. The default value writes to *standard-output*.

  • terse-depth – An instance of <integer>. The default value is 100.

Discussion:

When outputting ppml we need to keep track of the space left on the current line and the current margin. We store these values in a <ppml-printer> object, along with the functions used to display text and line breaks.

The terse-depth is used to limit recursion amongst <ppml-block> instances. Once printing has recursed through terse-depth blocks, it will change the break-type to #"fit" to abbreviate things.

Type Aliases and Constants#

<nat> Type#
Equivalent:

limited(<integer>, min: 0)

<ppml-break-type> Type#
Equivalent:

one-of(#"consistent", #"inconsistent", #"fit")

<ppml-sequence> Type#
Equivalent:

<sequence>

Discussion:

Note

This should be limited(<sequence>, of: <ppml>).

$line-break Constant#
Value:

ppml-break(space: 999)

Discussion:

A way to force a line break by making a break with a space larger than the column width.