|
This Reference Guide uses the following typographical conventions:
Bold type means that the syntax element is mandatory, not optional.
Example 1
In this example, the SELECT keyword is mandatory. The DISTINCT keyword is optional. Whatever is represented by column-list is mandatory:
SELECT DISTINCT column-list
...
|
Example 2
In this example, 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 must be replaced by something else. This replacement is necessary to obtain the syntax that is actually supported.
Lines containing an equivalence operator ( ::= ) explain what a placeholder must be replaced by. The placeholder is on the left. What it must be replaced by is on the right.
Such explanations may or may not be given locally (ie., within the same syntax block). The following syntax block explains that column-list is a comma-separated list of column-expressions, but you need to look elsewhere to find out exactly what column-expression may be replaced by.
SELECT DISTINCT column-list
FROM { table-name table-alias | join-construct }
where-clause
group-by-clause
order-by-clause
column-list ::= column-expression, column-expression...
where-clause ::= WHERE condition
group-by-clause ::= GROUP BY column-list HAVING condition
order-by-clause ::= ORDER BY column-list
{ ASC | ASCENDING | DESC | DESCENDING }
|
In the example, the SELECT clause must end in a column-list. This is a list of one or more comma-separated column-expressions.
The SELECT clause is followed by a mandatory FROM clause, and then by an optional where-clause. If a where-clause is present, it must start with a mandatory WHERE keyword... (and so on).
|
A double greater-than symbol ( >> ) introduces an explanation of required data type. This is used in USoft Blend syntax prescriptions.
Example 1
<pc:assign-nodeset
[ variable = "expr >> node-set" ... ] />
|
In this example, each expr that you provide as value for a variable must evaluate to a node-set. If expr does not evaluate to a node-set, this may lead to an explicit error, or it may silently lead to unexpected results, or it may lead to some implicitly performed data type conversion which you may or may not have intended.
Example 2
In this example, the value that you provide for the select attribute is interpreted as a string. As a consequence, in realisations of this syntax prescription, you probably want curly braces to convert node-sets to strings:
<pc:value-of select="{$myvariable}" />
|
If you omit the curly braces, the value is interpreted not as the value of $myvariable, but as the following literal string:
|
Curly braces that do NOT contain a pipe symbol ('|') represent literal code (Java, JavaScript). These curly braces typically appear on different lines:
.checkRecords( options )
options := {
double: double
}
double := { all | current }
|
This is matched by the following 2 realisations:
.checkRecords( { double: 'all' } )
.checkRecords( { double: 'current' } )
|
|
A pair of curly braces that surrounds one or more pipe symbols ( | ) represents a set of alternatives from which exactly 1 must be selected. If one of the alternatives is the default, it is underlined:
<pc:DeleteDirectories>
<Directory dirpath="folder-path" recursive="recursive"/>
</pc:DeleteDirectories>
recursive ::= { yes | no }
|
The following three snippets are legal realisations of this syntax prescription. The two last examples are equivalent:
<pc:DeleteDirectories>
<Directory dirpath="c:\myproject\myprojectfolder" recursive="yes" />
</pc:DeleteDirectories>
<pc:DeleteDirectories>
<Directory dirpath="c:\myproject\myprojectfolder" recursive="no" />
</pc:DeleteDirectories>
<pc:DeleteDirectories>
<Directory dirpath="c:\myproject\myprojectfolder" />
</pc:DeleteDirectories>
|
|
If surrounded by whitespace, the ellipsis symbol ( ... ) denotes a place where code is omitted or left unspecified. If the ellipsis dots appear in non-Bold type, there is optionally omitted code. In the following example, the ellipsis symbol stands for some unspecified code that could appear between the curly braces after if (struct):
$.udb.getMenu({
menuName: menuName,
success: function() {
var struc = $.udb.menus.menu(menuName);
if (struc) {
...
}
}
});
|
|
If following an expression (as opposed to: being surrounded by whitespace), an ellipsis symbol ( ... ) indicates that the preceding element may be repeated any number of times. If the preceding element is preceded by a comma, repeated elements must be separated by commas:
Example 1
SELECT column-list
FROM table-name
column-list ::= column-expression, column-expression...
|
The following snippet is a legal realisation of this syntax prescription:
SELECT substr( destination, 1, 3 ), destination, tour_type
FROM tour_programme
|
Example 2
hostvars := { name : value, ... }
|
A legal realisation in the place of hostvars is:
{ first-name: 'ERIC', family-name: 'DUMOULIN', status: 'MEMBER' }
|
Square brackets indicate the beginning and end of the element to be repeated. The ellipsis symbol is the last element before the ending bracket:
Example 3
<pc:apply2file
xml = "file-path"
xsl = "file-path"
filepath = "file-path"
[ variable = "value" ... ] />
|
A legal realisation of this is:
<pc:apply2file
xml="../../env.xml"
xsl="using/env.xsl"
filepath="env.xml"
servername="{$servername}"
serverdir="C:\USoft\Servers" />
|
|
Brackets ( [ ] ) that surround a section ending in an ellipsis symbol ( ... ) indicate the beginning and end of the element to be repeated:
<pc:apply2file
xml = "file-path"
xsl = "file-path"
filepath = "file-path"
[ variable = "value" ... ] />
|
A legal realisation of this is:
<pc:apply2file
xml="../../env.xml"
xsl="using/env.xsl"
filepath="env.xml"
servername="{$servername}"
serverdir="C:\USoft\Servers" />
|
|
In syntax prescriptions, 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.
<pc:comment-of
select="expression" >
content
</pc:comment>
|
This contrasts with interpunction for the special typographical conventions explained in this help topic. You are expected to replace or interpret, not to reproduce, the double greater-than symbols ( >> ), the brackets ( [ ] ), and the ellipsis symbol ( ... ) in the following example:
<pc:apply
xml = "expr >> path"
xsl = "expr >> path"
variable = "value"
[ variable = "value" ... ] />
|
|
The following notation is used in USoft Blend syntax prescriptions. It 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:
<pc:comment-of
select="expression" >
content
</pc:comment>
|
|
See also
USoft Developer Reference Guide
USoft Blend Guide to expressions and data types
|
