Processing instructions are generally used in XML documents to tell the XML application to perform some particular action. For example, a processing instruction similar to:
<?xml-stylesheet type="text/xsl" href="formatter.xsl"?>
appears in some XML documents to associate them with an XSLT stylesheet. When opened in some browsers, the XML document will be displayed using that stylesheet. This processing instruction has a target, which consists of the characters after the <?, up to the first space, namely xml-stylesheet. The rest of the characters are referred to as its content, namely type="text/xsl" href="formatter.xsl". Although the content of this particular processing instruction looks like a pair of attributes, it is simply considered a string.
Processing instructions can be both queried and constructed using XQuery.
Although processing instructions often appear at the beginning of an XML document, they can actually appear within element content or at the end of the document as well. Example 21-4 shows a small XML document with two processing instructions. The xml-stylesheet processing instruction appears on the second line, whereas doc-processor appears within the content of the b:header element. The first line is the XML declaration, which, although it looks like a processing instruction, is not considered to be one.
Example 21-4. XML document with processing instructions (pi.xml)
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="formatter.xsl"?>
<b:businessDocument xmlns:b="http://datypic.com/b">
<b:header>
<?doc-processor appl="BDS" version="4.3"?>
<b:date>2006-10-15</b:date>
</b:header>
</b:businessDocument>Processing instruction nodes do not have any children, and their parent is either a document node or an element node. In this example, the xml-stylesheet processing instruction is a child of the document node, and doc-processor is a child of the b:header element.
The node name of a processing instruction node is its target. It is never in a namespace, so the namespace portion of the name will be a zero-length string. The string value (and typed value) is its content, minus any leading spaces, as an instance of xs:string. For example, the node name of the first processing instruction in the example is xml-stylesheet, and its string value is type="text/xsl" href="formatter.xsl".
Processing instructions can be queried in path expressions using the processing-instruction( ) kind test. For example:
doc("pi.xml")//processing-instruction( )will return the both processing instructions in the document, whereas:
doc("pi.xml")/b:businessDocument/b:header/processing-instruction( )will return only the doc-processor processing instruction.
You can also specify a target between the parentheses. For example, specifying processing-instruction(doc-processor) returns only processing instructions whose target is doc-processor. Quotes can optionally be used around the target for compatibility with XPath 1.0.
The node( ) kind test will return processing instructions as well as all other node kinds. For example, the expression:
doc("pi.xml")/b:businessDocument/b:header/node( )will return a sequence consisting of the doc-processor processing instruction node, followed by the b:date element. This is in contrast to *, which selects child element nodes only.
The processing-instruction( ) keyword can also be used in sequence types to match processing-instruction nodes. For example, to display the target and content of a processing instruction as a string, you could use the function shown in Example 21-5. The use of the processing-instruction( ) sequence type in the function signature ensures that only processing-instruction nodes are passed to this function.
Example 21-5. Function that displays processing instructions
declare function local:displayPIValue
($pi as processing-instruction( ))as xs:string {
concat("Target is ", name($pi),
" and content is ", string($pi))
};As with node kind tests, a specific target may be specified in the sequence type. If the sequence type for the argument had been processing-instruction("xml-stylesheet"), the function would only accept only processing-instruction nodes with that target, or a type error would be raised.
A processing-instruction node will also match the node( ) and item( ) sequence types.
Processing instructions can be constructed in queries, using either direct or computed constructors. A direct processing-instruction constructor uses the XML syntax, namely target, followed by the optional content, enclosed in <? and ?>.
A computed processing-instruction constructor allows you to use an expression for its target and/or content. Its syntax, shown in Figure 21-2, has three parts:
The keyword
processing-instructionThe target, which can be either a literal name or an enclosed expression (in braces) that evaluates to a name
The content as an enclosed expression (in braces), that is evaluated and cast to
xs:string
Example 21-6 shows three different processing-instruction constructors. The first is a direct constructor, the second is a computed constructor with a literal name, and the third is a computed constructor with a calculated name.
Example 21-6. Processing-instruction constructors
Query <ul>{ <?doc-processor version="4.3"?>, processing-instruction doc-processor2 {'version="4.3"'}, processing-instruction {concat("doc-processor", "3")} {concat('version="', '4.3', '"')} }</ul> Results <ul> <?doc-processor version="4.3"?> <?doc-processor2 version="4.3"?> <?doc-processor3 version="4.3"?> </ul>
Whether it's a direct or computed constructor, the target specified must be a valid NCName, which means that it must follow the rules for XML names and not contain a colon.