PDML Extensions Reference Manual

First Published

2022-02-07

Latest Update

2022-02-10

License

CC BY-ND 4.0

Author

Christian Neumanns

Website

https://pdml-lang.dev/

PML Markup Code

Github

Introduction

This manual enumerates and documents elements that are part of PDML's extension nodes.

The following elements are documented:

  • Utility nodes

  • Types

  • Scripting API

Utility Nodes

This chapter describes utility nodes.

Utility nodes are all part of the namespace prefix u.

u:set

A u:set node assigns a value to one or more parameters.

After defining a parameter, its value can be inserted in the document with a u:get node.

The syntax for assigning a value to a parameter is:

name = "value"

Hence, the following code assigns the value light green to parameter color:

[u:set color = "light green"]

The syntax rules for parameters are the same as those for attributes (quoted/unquoted values, whitespace, character escapes, and lenient parsing):

For example, several parameters can be assigned in a single u:set node, whitespace between attributes is ignored, and some values can be unquoted:

[u:set
    width=200
    height=100
]

The rules for a parameter's name are the same as those for a node name.

After assigning a value to a parameter, its value cannot be changed later in the document. Parameters are like constants in programming languages.

u:get

A u:get node gets a parameter and inserts the parameter's value in the document. The parameter must have been defined with a u:set node before it can be used in a u:get node.

The name of the parameter to be retrieved is defined by the node's text content. Hence, the following code inserts the value of parameter color into the document:

[u:get color]

u:ins_file

A u:ins_file node reads a text file and inserts the text into the PDML document.

The file's path is specified by attribute path.

For example, the following code inserts the text stored in file foo.txt into the document:

[u:ins_file path=foo.txt]

The path can be absolute or relative. If it's relative, it is relative to the directory of the PDML file in which u:ins_file is used. If u:ins_file is not used in a file, then the current working directory is used as root.

Types

This chapter describes type nodes.

Type nodes are all part of the namespace prefix t.

Note

The number of types currently supported is very limited. More types (e.g. number, boolean, time, URL, etc.) will be added in the future.

date

A t:date type denotes a node that contains text representing a date in the ISO 8601 format.

The format of the date must be: YYYY-MM-DD. Example: 1999-12-31.

string

A t:string type denotes a node that can only contain text.

Text within the node must be escaped, as in a standard node.

For example, this code:

[t:string line \[1\]
    line 2
line 3
]

... expands to:

line [1]
    line 2
line 3

See also: raw_text.

raw_text

A t:raw_text type denotes a block of raw text.

In this context, the term raw means that the text is not interpreted by the parser. For example, the text [foo] is not parsed as an empty node with name foo. It is pared as the text "[foo]".

There are two syntax variations supported, as shown in the following chapters:

Delimited Text Syntax

Example:

[t:raw_text
    ~~~
    first text line
    ...
    last text line
    ~~~
]

The text is embedded between two delimiter lines (the ~~~ lines in the above example).

A delimiter line is a sequence of:

  • an optional indent (spaces and tabs)

  • 3 or more identical delimiter characters

  • a new line

A delimiter character must be a ", =, or ~.

The opening delimiter line must contain at least 3 delimiter characters. The closing delimiter line must contain the same number of delimiter characters as the opening delimiter line. Examples of valid delimiter lines: """, ====, ~~~~~~~~~~.

The indent within the node is handled as follows:

  • The indent of the opening delimiter line is optional. It is composed of only spaces, or only tabs. Mixing spaces and tabs is not allowed.

  • The closing delimiter line must have exactly the same indent as the opening delimiter line. More indent is not allowed.

  • The text lines between delimiter lines must have at least the same indent as the opening delimiter line. Text lines can have more indent.

  • The indent of the opening delimiter line is removed in all subsequent text lines. Additional indent in text lines is preserved.

Hence, the following node:

    [t:raw_text
        ~~~
        if ( list[index] == 0 ) {
            write_line ( "The value is zero." )
        }
        ~~~
    ]

... expands to:

if ( list[index] == 0 ) {
    write_line ( "The value is zero." )
}

Standard Text Syntax

Example:

[t:raw_text first text line
...
last text line]

When this syntax variation is used, the text must start on the same line as the node, just after the node's name.

The node is handled like a standard text node, not as raw text. All indent is preserved. Text must be escaped, as in a normal text node.

Hence, this code:

[t:raw_text line \[1\]
    line 2
        line 3
]

... expands to:

line [1]
    line 2
        line 3

This syntax variation is sometimes useful when PDML markup code needs to be parsed in a raw text node. Example:

[t:raw_text first line
[u:ins_file path=foo.txt]
last line
]

Scripting API

This chapter lists specific PDML functions available in script nodes.

The functions are divided into two categories:

  • PDML API

    The PDML API provides functions used to interact with the PDML document.

  • Core API

    The core API provides a set of general functions used to work with text files and URLS, interact with the operating system, run external programs and OS scripts, interact with the user, etc.

PDML API

Object doc

Functions to work with the currently parsed PDML document.

Function insert

Insert a string into the document, at the current position.

Input:

  • string String: The string to be inserted. The string can be PDML code or text that is escaped already.

Output: none

Throws:

  • IOException: Thrown if an IO error occurs.

Function insertText

Insert text into the document, at the current position. Note: Use function 'insert' to insert PDML code, or text that is escaped already.

Input:

  • text String: The text to be inserted. The text is escaped automatically by this function. Hence, the text should not be escaped already, to avoid double-escaping.

Output: none

Throws:

  • IOException: Thrown if an IO error occurs.

Function insertLine

Insert a string, followed by an OS-dependant new line, into the document, at the current position.

Input:

  • string String: The string to be inserted. The string can be PDML code or text that is escaped already.

Output: none

Throws:

  • IOException: Thrown if an IO error occurs.

Function insertTextLine

Insert text, followed by an OS-dependant new line, into the document, at the current position. Note: Use function 'insertLine' to insert PDML code, or text that is escaped already.

Input:

  • text String: The text to be inserted. The text is escaped automatically by this function. Hence, the text should not be escaped already, to avoid double-escaping.

Output: none

Throws:

  • IOException: Thrown if an IO error occurs.

Function insertNewLine

Insert an OS-dependant new line (LF on Linux; CRLF on Windows) into the document, at the current position.

Input: none

Output: none

Throws:

  • IOException: Thrown if an IO error occurs.

Function escapeText

Escape text.

Input:

  • text String: The text to be escaped.

Output:

  • String: Escaped text.

Function insertOSCommandOutput

Execute an OS command, and insert the command's output (written to stdout) into the document, at the current position.

Input:

  • OSCommandTokens String[]: An array of command tokens. The first token is the program name. Remaining tokens are command line arguments. Example: "program_name" "--arg1" "value1" "--arg2" "value2"

  • input String or null: The input string that will be fed into the command's standard input device (stdin). Use 'null' if no input is needed by the command.

Output: none

Throws:

  • IOException: Thrown if an IO error occurs.

  • InterruptedException: Thrown if the command is interrupted.

Core API

Object fileUtils

Functions to work with files. Text files are supposed to be encoded in UTF8

Function writeText

Write UTF8-encoded text into a file. If the file exists already, it is overwritten. If the file doesn't exist yet, it is created.

Input:

  • path String: The absolute or relative-to-the-working-directory path of the file.

  • text String: The text to be stored in the file.

Output: none

Throws:

  • IOException: Thrown if an error occurs while writing to the file.

Function readText

Read the text stored in a UTF8-encoded text file.

Input:

  • path String: The absolute or relative-to-the-working-directory path of the file to read.

Output:

  • String or null: The text stored in the file, or ,,null,, if the file is empty.

Throws:

  • IOException: Thrown if an error occurs while reading the file (e.g. file does not exist).

Function readLines

Read the lines stored in a UTF8-encoded text file.

Input:

  • path String: The absolute or relative-to-the-working-directory path of the file to read.

Output:

  • List<String> or null: The list of lines stored in the text file, or ,,null,, if the file is empty. Empty lines are represented as empty strings in the list.

Throws:

  • IOException: Thrown if an error occurs while reading the file (e.g. file does not exist).

Function exists

Check if a file exists

Input:

  • path String: The absolute or relative-to-the-working-directory path of the file to check.

Output:

  • boolean: 'true' if the file exists, 'false' if the file does not exist.

Throws:

  • IOException: Thrown if an error occurs while acessing the file.

Object GUIUtils

Function showInfo

Input:

  • info String

Output: none

Function showInfoWithTitle

Input:

  • info String

  • title String or null

Output: none

Function showWarning

Input:

  • warning String

Output: none

Function showWarningWithTitle

Input:

  • warning String

  • title String or null

Output: none

Function showError

Input:

  • error String

Output: none

Function showErrorWithTitle

Input:

  • error String

  • title String or null

Output: none

Function askString

Input:

  • message String

Output:

  • String or null

Function askStringWithTitle

Input:

  • message String

  • title String or null

Output:

  • String or null

Function askYesNo

Input:

  • question String

Output:

  • Boolean or null

Function askYesNoWithTitle

Input:

  • question String

  • title String or null

Output:

  • Boolean or null

Function openFile

Input:

  • filePath String

Output: none

Throws:

  • IOException

Object numberUtils

Utility functions to work with numbers.

Function formatFloat

Format and round a floating point number.

Input:

  • number double: The floating point number to be formatted.

  • format String: The format to apply. Please refer to https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/DecimalFormat.html for more information.

Output:

  • String: A string representing the formatted and rounded floating point number.

Object OSCommand

Function runAndWait

Input:

  • OSCommandTokens String[]

Output:

  • int

Throws:

  • IOException

  • InterruptedException

Function startAndContinue

Input:

  • OSCommandTokens String[]

Output: none

Throws:

  • IOException

Function textPipe

Input:

  • OSCommandTokens String[]

  • input String or null

Output:

  • String

Throws:

  • IOException

  • InterruptedException

Object OSConfig

Function OSName

Get the name of the current operating system.

Input: none

Output:

  • String: The name of the current operating system.

Function isWindows

Check if the current operating system is Windows.

Input: none

Output:

  • boolean: 'true' if the current operating system is Windows, otherwise returns 'false '.

Function newLine

Get the new line used on the current operating system.

Input: none

Output:

  • String: A string representing a new line (LF on Unix/Linux; CRLF on Windows).

Object OSConsole

Function askString

Input:

  • message String

Output:

  • String or null

Object OSEnvUtils

Function getVarOrNull

Input:

  • varName String

Output:

  • String or null

Function getVarOrDefault

Input:

  • varName String

  • defaultValue String

Output:

  • String

Function getVar

Input:

  • varName String

Output:

  • String

Object stderr

Function write

Input:

  • string String

Output: none

Function writeLine

Input:

  • string String

Output: none

Function writeNewLine

Input: none

Output: none

Object stdin

Function readInt

Input: none

Output:

  • int

Throws:

  • IOException

Function readLine

Input: none

Output:

  • String or null

Throws:

  • IOException

Function readRest

Input: none

Output:

  • String or null

Object stdout

Functions to write to the current process's standard output device (stdout).

Function write

Write a string to stdout.

Input:

  • string String: The string to be written

Output: none

Function writeLine

Write a string, followed by a new line, to stdout. The new line is OS dependant (LF on Linux, CRLF on Windows).

Input:

  • string String: The string to be written

Output: none

Function writeNewLine

Write a new line to stdout. The new line is OS dependant (LF on Linux, CRLF on Windows).

Input: none

Output: none

Object timeUtils

Date/time utility functions line 2 line 3

Function formattedCurrentLocalDateTime

Get the current local date and time line 2 line 3

Input:

  • format String: A string defining the format to use

Output:

  • String: A string representing the current local date and time

Function currentLocalDateTimeMinutes

Get the current local date and time up to minutes

Input: none

Output:

  • String: A string representing the current local date and time

Function currentLocalDateTimeSeconds

Input: none

Output:

  • String

Function formattedCurrentLocalDate

Input:

  • format String

Output:

  • String

Function currentLocalDate

Input: none

Output:

  • String

Function formattedCurrentLocalTime

Input:

  • format String

Output:

  • String

Function currentLocalTimeMinutes

Input: none

Output:

  • String

Function currentLocalTimeSeconds

Input: none

Output:

  • String

Object URLUtils

Function readText

Input:

  • URL String

Output:

  • String or null

Throws:

  • IOException

Object WinCmdUtils

Function getInstructionsOutput

Input:

  • instructions String

  • arguments String[] or null

  • input String or null

Output:

  • String or null

Throws:

  • IOException

  • InterruptedException