PDML Extensions User Manual

Start/End Symbols

A comment starts with [- and ends with -]:

[- text of comment -]
^^                 ^^

Start/End Positions

A comment can start at any position in a line. It can end at any subsequent position in the same line or at any position in a subsequent line.

Examples:

text [- comment -] text

[- single line comment -]

[-
    multiple
    lines
    comment
-]

text [- this text is
commented out -] text

Location

Comments can be inserted anywhere in a PDML document, even before or after the root node:

[- comment -]

[root
    [- comment -]
    text [- comment -] text
]
[- comment -]

Nested Comments

Comments can be nested. That is, a comment can contain another comment:

[- comment [- nested comment -] comment -]
           ^^^^^^^^^^^^^^^^^^^^

Comments can be nested to any level:

[- level 1 (not nested)
    [- level 2
        [- level 3 -]
    -]
-]

Position

Attributes must appear after the node name, and before the node content.

[node_name [@ a1="v1"] node content]
           ^^^^^^^^^^^

Start/End

A list of attributes starts with [@, and ends with ]:

[node_name [@ a1="v1"] node content]
           ^^        ^

Name

An attribute name has the same rules as a node name. It starts with a letter or an underscore (_), optionally followed by any number of letters, digits, underscores (_), hyphens (-), or dots (.).

Here are some examples of valid attribute names:

color
HTML_file_path
_ID_12.5-a

Attribute names are case-sensitive. Hence the following names are different: color, COLOR, Color.

Each attribute in a single node must have a unique name. The same attribute name can appear in different nodes.

Assignment Symbol

Attribute names and values are separated by an equals sign (=):

color="orange"
     ^

Value

An attribute value is enclosed in a pair of quotes:

color="orange"
      ^      ^

An attribute value can contain any Unicode characters, including spaces and new lines:

colors="red
light green
blue 😀😀😀"

Character Escape Rules in Values

Quote characters (") and backslashes (\) within a value must be escaped. For example, the value "1\2" would be assigned as follows:

code="\"1\\2\""
      ^^ ^^ ^^

Square brackets ([]) don't need to be escaped, but for consistency with text nodes, they can be escaped if desired. For example, to assign the value [1], the following two assignments are valid:

index = "[1]"
index = "\[1\]"

If the parser supports Character Escape Sequences in text nodes, then the same escape sequences can also be used in attribute values:

a1 = "line 1\nline\t2\r\nline \u0033 \U0001F600"
            ^^    ^^ ^^^^     ^^^^^^ ^^^^^^^^^^

The above attribute contains the value:

line 1
line    2
line 3 😀

Whitespace Handling

While whitespace in text nodes is preserved by a PDML parser, it is ignored in attributes.

Whitespace characters (spaces, tabs, and/or new lines) before, between, or after attributes is ignored. Hence the following nodes are equivalent:

[image [@ source="resources/images/flower.png" width="200" height="100"]]

[image [@
    source = "resources/images/flower.png"
    width = "200"
    height = "100"
]]

[image
    [@
        source = "resources/images/flower.png"
         width = "200"
        height = "100"
    ]]

The first whitespace character after the list of attributes is ignored. Additional whitespace is part of a text node. Hence the following node (which contains two spaces after the list of attributes) contains the text " foo" (foo with one leading space)

[name [@ a1="v1"]  foo]
                 ^^

Comments in Attributes

If the parser supports comments, then any number of comments is allowed before or after an attribute assignment. Example:

[image [@
    [- width in pixels -]
    width = "200"

    color = "0, 255, 0" [- RGB values -]
]]

Comments are not allowed

• Between the node name and the start of attributes ([@).

• Before or after the assignment symbol (=).

Lenient Parsing

To shorten the syntax for attributes, a parser can support the following lenient parsing rules:

• Quotes around attribute values can be omitted if the value does not contain:

  • Whitespace (spaces, tabs, carriage returns, and line feeds)

  • The following characters: [ ] ( ) " '

  • Escape sequences like \n, \u0041, etc.

  Hence, instead of writing:

  size="200" file="foo\\bar.txt"
       ^   ^      ^            ^

  ... we can write shorter code:

  size=200 file=foo\bar.txt

• If a node is specified to have only attributes (child nodes are not allowed) then the start/end symbols ([@ ]) around attributes can be omitted.

  Consider an image node that has attributes, but no child nodes. Instead of writing:

  [image [@ source="images/juicy apple.png" width="400"]]
         ^^                                       ^   ^^

  ... we can simply write:

  [image source="images/juicy apple.png" width=400]

  Warning

  Omitting the start/end symbols can lead to subtle bugs and invalid documents if the specification for a node changes.

  Consider a node specified to have only attributes:

  [foo a1 = "v1"]

  Now suppose that the specification of the node changes later. The node can now also contain text.

  Then the meaning of the above code silently changes!

  The initial version was parsed as node foo with attribute a1 set to v1. But now the node is parsed as node foo with text content a1 = "v1". To keep the initial semantics, the code must be changed to:

  [foo [@ a1 = "v1"]]

  This is error prone!

  Hence, one should think twice before making the start/end symbols optional. It is best to avoid this syntax simplification if the specification for nodes risks to change in future versions.

Alternative Start/End Syntax

Instead of using the [@ ] symbols to embed attributes, a pair of parenthesis () can alternatively be used.

Using parenthesis makes the code a bit shorter and more visually appealing, as shown below:

[name [@ a1="v1" a2="v2" ] ]     // standard syntax
      ^^                 ^

[name ( a1="v1" a2="v2" ) ]      // alternative syntax
      ^                 ^

However, using parenthesis is error-prone if the text in a node starts with (.

Suppose a node contains the text (organic=better), but no attributes. Then the following code is ambiguous:

[i (organic=better)]

If the parser does not support attributes (i.e. a parser that supports only Core PDML), then a node with text (organic=better) is parsed. However, if attributes are supported, then a node with attribute organic is parsed.

There are two workarounds.

• To make it clear that there are no attributes, we can write:

  [i () (organic=better)]

• If the parser supports an additional \) escape sequence, then we can escape the ( to make it clear that the ( is not the start of attributes:

  [i \(organic=better)]

However, the above workarounds are error-prone if the document is accidentally parsed with a parser that doesn't support attributes (e.g. a parser that supports only Core PDML).

In the first case the parser reads a node with text () (organic=better) (instead of (organic=better)).

In the second case the parser generates an error because \( is not supported. That's better, because we get aware of the problem, instead of silently getting wrong data.

Another rare edge case can arise if the specification of a node changes.

For example, suppose a node specified to contain only attributes (no child nodes) changes to a node that contains only child nodes (no attributes). Then the following code silently changes from a node with attribute a1 to a node with text (a1="v1"):

[foo (a1="v1")]

All above edge cases don't exist when the standard syntax is used:

[i [@ organic=better]]

Moreover, if a document using attributes is accidentally read by a parser without support for attributes then an error is generated, because [@ is parsed as the start of a node with an invalid name. Hence there is no risk of silently parsing wrong data.

A PDML parser implementation that supports attributes should clearly specify which syntax it supports: only the standard syntax, only the alternative syntax, or both.

Expression Node

Here is an example of an expression node used in a document:

1 + 1 = [s:exp 1 + 1]

This snippet results in:

1 + 1 = 2

Ok, that's not very spectacular! However, as we'll see later, the power of expressions quickly becomes obvious if we consider that any valid Javascript expression can be used, including complex expressions that compose internal and/or external functions defined somewhere else.

Now let's look at how this works.

First, the [] pair tells us that we are using a PDML node:

[s:exp 1 + 1]
^           ^

The namespace s states that we are using an extension node in the scripting category:

[s:exp 1 + 1]
 ^

The node's name is exp, which is an abbreviation for expression:

[s:exp 1 + 1]
   ^^^

Finally we can see that the node's content is the text 1 + 1:

[s:exp 1 + 1]
       ^^^^^

As soon as the parser sees the s:, it passes control to PDML's extension node handler. This handler checks the node's name and namespace, and passes control to a dedicated handler for expressions. The expression handler reads the node's text content, evaluates it, converts it to a string, and then inserts the result (2 in our case) into the PDML document. The final result will be that the code:

[s:exp 1 + 1]

... has been replaced with:

2

Hence, the application that reads the PDML document will see the following code:

1 + 1 = [s:exp 1 + 1]

... like this:

1 + 1 = 2

Real-world examples demonstrating the power of expressions can be found in Scripting Examples.

Script Node

A s:script node contains one or more Javascript statements. Here is an example:

[s:script doc.insert ( "Hello" );]

This code insert the text Hello in the document, so that the result of parsing the above code will be:

Hello

Yes, we could as well just have written Hello in the document. So let's look at a more compelling example:

[s:script
    ~~~
    const licenseFile = "resources/license.txt"
    if ( fileUtils.exists ( licenseFile ) ) {
        doc.insert ( fileUtils.readText ( licenseFile ) );
    } else {
        stderr.writeLine ( "WARNING: No license file found!" );
    }
    ~~~
]

This code checks if file resources/license.txt exists. If it exists, its content is written into the PDML document. If it doesn't exist, a warning is written to the operating system's standard error device stderr (e.g. the terminal).

Note the ~~~ delimiters that embed the script. We'll soon see how this works.

Note for programmers: You can think of a script node as the body of a function that has no input arguments and doesn't return a value. Hence, a script is executed for its side effects (such as inserting code into the document).

Definition Node

A definition node has the qualified name s:def. It is used to define constants, variables, and functions that will later be used in s:exp or s:script nodes.

s:def nodes must be declared before using them in s:exp or s:script nodes.

A single document can have any number of s:def nodes.

Here is a simple example of an s:def node that defines the constant PI, as well as functions to compute the circumference and area of a circle:

[s:def
    ~~~
    const PI = 3.1415926;

    function computeCircumference ( radius ) {
        return 2 * PI * radius;
    }

    function computeArea ( radius ) {
        return PI * radius * radius;
    }
    ~~~
]

Suppose the above code is in a PML document, and later in the document we write:

Consider a circle of radius 10 cm.

It's [i circumference] is [s:exp computeCircumference ( 10 );] cm.

It's [i area] is [s:exp computeArea ( 10 );] cm[sup 2].

This code would expand to:

Consider a circle of radius 10 cm.

It's [i circumference] is 62.831852 cm.

It's [i area] is 314.15926 cm[sup 2].

... and, after converting to HTML, be displayed as:

Instead of embedding definition nodes in a document (as shown above) you can also import definition nodes from external resources. This is useful if you need the same set of functions in different documents, or if you want to share them with other users, for example via Github or Gitlab.

Definitions can be imported with an u:ins_file node, or any other method that inserts text into a document.

For example, you can store the above definition node in file circle_library.def (the file name and extension can be chosen freely). The file looks like this:

[s:def
    ~~~
    const PI = 3.1415926;

    function computeCircumference ( radius ) {
        return 2 * PI * radius;
    }

    function computeArea ( radius ) {
        return PI * radius * radius;
    }
    ~~~
]

Here is an example of a fully functioning PML file that uses a u:ins_file node to import the definitions:

[doc [title Circle Demo]

    [u:ins_file path=circle_library.def]

    Suppose a circle of radius 10 cm.
    
    It's [i circumference] is [s:exp computeCircumference ( 10 );] cm.
    
    It's [i area] is [s:exp computeArea ( 10 );] cm[sup 2].
]

If PML is installed on your computer you can convert the above PML file to HTML by executing the following command in a terminal:

pmlc circle_demo.pml

This command creates file output/circle_demo.html which is displayed as follows in a browser:

Standard Libraries

Standard libraries contain functions that are implicitly available.

External Libraries

External libraries need to be explicitly loaded before their functions can be used.