Guide to syntax descriptions

Bold type means that the syntax element is mandatory, not optional:

This means that when calling the pc:DeleteFile directive, you must supply a source attribute that has a valid filepath value.

Non-bold type is used for elements that you are allowed to omit:

This means that when calling the pc:call directive, you must supply an xpath attribute, but you are free to either supply or omit a filepath attribute.

Italic type indicates a placeholder. A placeholder is a text that must be replaced by an element not shown, but referred to by the placeholder. The replacement is necessary to obtain the syntax that is actually supported:

The folder-path placeholder must be replaced by a path leading to a folder on the file system.

The recursive placeholder must be replaced either by the word yes or by the word no. These 2 allowed values are explicitly stated as a replacement instruction which has the recursive placeholder on the left-hand side, the equivalence operator:

in the middle, and the replacement (in this case, the allowed values) on the right-hand side. Thus, the following is valid syntax:

To help you understand what are the expected values for attributes and what happens with them during processing, many syntax descriptions show double greater-than symbols ( >> ) that have one placeholder to the left of them and another placeholder to the right.

You can click on each element to get more information about the expressions and datatypes, except on expr and (any), which are not clickable:

The placeholder on the left indicates the type of expression expected.

The placeholder on the right indicates the datatype that the expression must evaluate to. This could be an XPath datatype (node set, string, number or boolean), but it could also be a valid folder path or file path, a valid JSON or XML fragment, a SQL statement, or simply a literal. If you provide input that cannot be evaluated to the datatype indicated, then this may lead to an explicit error, or it may silently lead to unexpected results, or it may lead to some implicitly performed datatype conversion which you may or may not have intended.

These indications help you decide whether or not you must write curly braces to get XPath expressions evaluated. (Do not confuse with curly braces surrounding pipe symbols - the are explained in the next section in this help topic.)

Contrast the following 2 examples.

Example 1

This example means that you must provide an XPath expression that evaluates to a node set, or that will automatically convert to a node set. You MUST NOT write curly braces: what you write is automatically evaluated as an XPath expression.

Example 2

This example means that you can provide a literal expression, which may or may not be an XPath expression. If you provide an XPath expression, you MUST write curly braces to get it evaluated as such. The expression must evaluate to a name-literal (a simple string datatype), or it will automatically be converted to such a string.

In syntax descriptions, curly braces ( { } ) only appear in combination with pipe symbols ( | ). Do not confuse with curly braces you write yourself to get an expression evaluated as an XPath expression.

A pair of curly braces that surrounds one or more pipe symbols ( | ) represents a set of alternatives from which exactly 1 must be selected:

In this example, if you use the optional recursive attibute, then you must give it either the value yes or the value no.

The fact that no is underlined means that no is the default value. The following 2 are equivalent:

In formal statements, a fragment surrounded by brackets ( [ ] ) and ending in an ellipsis symbol ( ... ) may be repeated any number of times. The statement:

means that the following, in which the fragment in brackets has been replaced twice, is a valid call to pc:apply2file:

If the ellipsis symbol is preceded by a comma ( , )

then multiple occurrences of the fragment must be separated by commas:

In syntax descriptions, all interpunction symbols must be spelled as shown to obtain legal syntax. This applies to opening and closing angular brackets, colons, forward slashes, equal signs, double quotes, single quotes, and non-italic hyphen characters and underscore characters.

The following example shows angular brackets, colons, a hyphen, an equal sign, double quotes, and a forward slash. All of these must be spelled as shown to get legal syntax. Only the italicised placeholders expression and content must be replaced by variable input.

By contrast, you must not actually reproduce symbols for the special typographical conventions explained in this help topic. In the following example, you are expected to replace, not to reproduce, the double greater-than symbols ( >> ) because they are part of a placeholder ( expr >> path ) which must be replaced as a whole. Similarly, you are not expected to actually reproduce the brackets ( [ ] ) or the ellipsis symbol ( ... ).

Similarly, never reproduce curly braces in combination with pipe symbols as in { commit | rollback }. Instead, produce one of the options they indicate (either commit, or rollback).

The following notation represents an XML fragment contained within other XML:

This is a shortcut notation which leaves unspecified whether an XML fragment or an XML document is required. An XML fragment must be valid XML according to the XML 1.0 specification, for example in terms of element names and attribute names and in terms of tag structure, but it is not required to have a single top-level document element. An XML document is an XML fragment with a single document element. In USoft Blend, XML documents are the norm but XML fragments without a document node are not excluded.

The following notation means that the <pc:comment-of> element is allowed to have an XML fragment as a child node: