Introduction to PDML

Text Node

Suppose a config file in which parameter color has the value green.

In JSON we would use the following syntax:

"color" = "green"

In XML we could use an attribute:

color = "green"

... or an element:

<color>green</color>

In PDML the syntax is:

[color green]

The above code is called a node in PDML.

As can be seen, a node is delimited by [] - a pair of square brackets. A node starts with [, and ends with ].

A node has a name and an optional value. In our example, the name is color and the value is the text green.

A space character is used to separate the name from the value.

Text values can contain spaces, new lines and Unicode characters:

[names
    Tim
    Tom
    Tam
    😃
]

Child Node

Besides text, a node's value can also be another node:

[config [color green]]

The value of node config is another node with name color and value green.

For better readability we can also write:

[config
    [color green]
]

Tree

The node's content can be a list of nodes, and each child node can itself have any number of child nodes:

[config
    [color green]
    [size
        [width 200]
        [height 100]
    ]
]

Hence, PDML can be used to store simple or complex tree data that can be structured or unstructured.

Mixed Child Nodes

A node's content can be a mixture of any number of text and child notes. This makes PDML convenient to store markup code.

Suppose we want to render:

In HTML we would write:

<div>Life is <i>better</i> if we are <b>kind</b>.</div>

In PDML this is written as:

[div Life is [i better] if we are [b kind].]

Empty Node

A node can be empty. It has a name, but no content:

[color]

In JSON this would be written as:

"color" = null

In XML:

<color></color>

or simply:

<color />

Comments

A comment starts with [- and ends with -]. Comments can be inserted anywhere. They can be nested to any level. Text within comments is ignored.

Example:

This is [- good -] awesome.
[- TODO: explain why -]

[- another comment
    [- nested comment -]
-]

Attributes

PDML attributes are conceptually similar to XML attributes. They are typically used to add metadata to nodes.

For example, the following HTML code uses attributes to identify and style node div:

<div id="my_div" class="my_class">content</div>

In PDML this would be written as follows:

[div (id=my_div class=my_class) content]

Character Escape Sequences

Besides the mandatory character escape sequences (\[, \], and \\), the following whitespace and Unicode escape sequences can be used:

For example, this text:

line 1\nline 2 \u0041 \U0001F600

... is parsed as:

line 1
line 2 A 😃

Parameters

Parameters are used to define recurring text snippets and data structures. This helps to eliminate code duplication and makes PDML documents more maintainable.

A parameter is declared once with a !set node, and its value can then be inserted any number of times with a !get node.

Here is an example of PML markup code that stores the company's website URL into parameter company_URL, and then inserts the URL in subsequent text:

[doc [title Company Overwiew]
    [u:set company_URL=https://www.my_company.org]
    ...
    Our website: [u:get company_URL]
    ...
    Click [link (url=[u:get company_URL]/contacts/index.html) here] to see a list of contacts.
]

Document Splitting

When a PDML document exceeds a certain size, it often makes sense to split it up into different files. For example:

• each table in a database document is stored in a separate file

• each chapter in a long article or book is stored in a separate file

Document splitting is done with the !ins-file extension node. Here is an example of markup code that uses a different file for each chapter in an article:

[doc [title Long Article]
    [u:ins_file path=chapters/introduction.pml]
    [u:ins_file path=chapters/body.pml]
    [u:ins_file path=chapters/conclusion.pml]
]

[ch [title Introduction]
    text text text
]

[ch [title Body]
    text text text
]

[ch [title Conclusion]
    text text text
]

Sub-documents can themselves also be splitted to any level.

!ins-file nodes are also useful if different documents share common parts, such as a common header/footer used in all articles of a blog.

Types (work in progress)

Types are used to validate the content of nodes, and to define how a node is parsed.

For example, node birthdate could be configured to be of type date, which means that the content of node birthdate must be text that represents a valid date in the past, such as:

[birthdate 1879-03-14]

Let's look at a real-world use-case of a PDML type in PML. Some PML nodes are designed to contain small or large pieces of raw text. For instance, PML has a node named code to display highlighted source code. Suppose we want to show the following source code in a PML document:

repeat 3 times
    write_line ( "[Hello]" )
.

If we used only the Core PDML syntax, and a code node that is itself indented (because it's contained in a parent node), we would need to write:

    [code repeat 3 times
    write_line ( "\[Hello\]" )
.]

This is not very readable. Moreover the characters [ and ] in the source code must be escaped ("\[Hello\]").

A dedicated PDML type associated with node code removes these inconveniences and allows us to write:

    [code
        ~~~
        repeat 3 times
            write_line ( "[Hello]" )
        .
        ~~~
    ]

Note that:

• The text content of node code is defined between the two """ lines

• The indent of the first """ defines the indent to be removed in the subsequent source code lines.

• Characters [ and ] in the source code don't need to be escaped anymore.

If a PML highlighter is used, we can use attribute lang to specify the programming language:

    [code (lang=Java)
        ~~~
        for (int i=1; i <= 3; i++) {
            System.out.println ( "[Hello]" );
        }
        ~~~
    ]

A PDML implementation can provide a standard set of frequently used types (string, number, boolean, date, time, etc.). To maximize flexibility and customization for different domains, additional types can be added programmatically or by configuration data that can be included in the PDML document, or provided in an external (possibly shared) PDML document.