XParse Module

2.1 Supported languages

There are two sense of languages supported by this API definition:

• The languages for which expression data is supported. In this case it is expected to be defined for various (all?) versions of the following language families: XPath ([XPath1.0],[XPath2.0],[XPath3.0]) and XQuery ([XQuery1.0],[XQuery3.0]).

  It is anticipated that implementors will use tools to generate portions of code semi-automatically from EBNF descriptions of the language grammars, and thus the suite of supported languages, especially in terms of succeeding versions, will be extensible. For further details see 6 Extensibility & Enquiry.

• The languages within which the functions can be executed. At present the model of describing options uses a map, which restricts its use to XPath3.0+, XQuery3.0+ and XSLT3.0+

2.2 Namespace conventions

The module defined by this document defines several functions, all contained in the namespace http://expath.org/ns/xparse. In this document, the xp prefix, when used, is bound to this namespace URI.

Error codes are defined in the same namespace (http://expath.org/ns/xparse), and in this document are displayed with the same prefix, xp.

2.3 Error management

There are two principal types of error: those resulting from erronious arguments or useage and those resulting from invalid primary inputs (e.g. an invalid XPath expression). Both types of failure will generate an error identified by a code (a QName.) When such an error condition is reached in the evaluation of an expression, a dynamic error is thrown, with the corresponding error code (as if the standard XPath function error() had been called.). An implementation may provide additional information about the exact nature of the error, that can for example be processed in an XSLT 3.0 try/catch construct.

2.4 Parse trees

Parse trees within this module are represented as XML trees, with element names corresponding to the EBNF grammar productions for the version of XPath/XQuery being parsed. For example:

<AdditiveExpr>
   <IntegerLiteral>1</IntegerLiteral>
   <TOKEN>+</TOKEN>
   <IntegerLiteral>5</IntegerLiteral>
</AdditiveExpr>

is a subtree corresponding to the string section 1 + 5.

Currently these trees are in the 'null' namespace, but this might be set parametrically.

2.5 Test suite

A suite of test-cases for all the functions defined in this module, in [QT3] format, is defined at [Test-suite].

3.1 Example – Refactoring a variable name

Within XPath and XQuery variable references are denoted through interpolations of the $name form. In simple cases, without local variable definitions or the character $ present in string literals, regular expressions can be used to extract and/or modify such variable references relatively cheaply, but in general this must be performed in a suitable parse tree.

Suppose an external variable $anyOldName is being renamed to $someNewVariableName. If we assume that this name is not overridden in the XPath, then the following XSLT code should suffice::

<xsl:template match="VarRef/@name">
  <xsl:param name="old" as="xs:string" tunnel="yes"/>
  <xsl:param name="new" as="xs:string" tunnel="yes"/>
  <xsl:attribute name="name" select="if(. = $old) then $new else ."/>
</xsl:template>

<xsl:variable name="expr">$anyOldName to string-length('$anyOldName is a variable')</xsl:variable>
<xsl:variable name="parse" select="xp:parse.xpath($expr,map{})"/>
 ==>
   <RangeExpr>
      <VarRef name="anyOldName"/>
      <FunctionCall name="string-length">
        <StringLiteral>$anyOldName is a variable</StringLiteral>
      </FunctionCall>
   </RangeExpr>
   
<xsl:variable name="replace">
  <xsl:apply-templates select="$parse">
    <xsl:with-param name="old" as="xs:string" tunnel="yes">anyOldName</xsl:with-param>
    <xsl:with-param name="new" as="xs:string" tunnel="yes">someNewVariableName</xsl:with-param>
  </xsl:apply-templates> 
</xsl:variable>
 ==>
   <RangeExpr>
      <VarRef name="someNewVariableName"/>
      <FunctionCall name="string-length">
        <StringLiteral>$anyOldName is a variable</StringLiteral>
      </FunctionCall>
   </RangeExpr>
 
<xsl:variable name="new.expr" select="xp:to-expression($replace)"/>
 ==> "$someNewVariableName to string-length('$anyOldName is a variable')"

If local variable bindings are present (using let or for or quantified expressions) then suitable updating of the replacement parameters within push templates can support correct use of variable reference scoping.

7.1 xp:parse

Summary

The xp:parse function returns a parse tree for an expression.

Signatures

xp:parse($in as xs:string) as element()

xp:parse($in as xs:string, $options as map(*)) as element()

Rules

Returns a parse-tree for the XPath/XQuery expression given in $in.

$options is a map of control options as described in 4 Options.

In the absence of any options, the default values are used.

Error Conditions

[xp:parsing-error] is raised if $in cannot be parsed successfully against the given grammar. It is implementation (and language) dependent as to what and how further information is made available about this failure.

[xp:invalid-option] is raised if one or more of the option values within $options is invalid or unrecognised.

Notes

Some notes

Examples

Parsing a simple range expression, with options to flatten single trees and remove unnecessary tokens:

xp:parse('1 to 8',map{'flatten':true(),'version':2.0})
==>
 <RangeExpr>
   <Literal type="xs:integer" value="1"/>
   <Literal type="xs:integer" value="8"/>
 </RangeExpr>

8.1 xp:to-expression

Summary

The xp:to-expression function returns an expression tree corresponding to a given parse tree.

Signatures

xp:to-expression($in as element()) as xs:string

xp:to-expression($in as element(), $options as map(*)) as xs:string

Rules

Returns a string for the XPath/XQuery expression tree given in $in.

$options is a map of control options as described in 4 Options.

In the absence of any options, the default values are used.

Error Conditions

[xp:invalid-tree] is raised if $in is not a valid expression tree, or suitable reduced subtree, for the grammar requested. It is implementation (and language) dependent as to what and how further information is made available about this failure.

[xp:invalid-option] is raised if one or more of the option values within $options is invalid or unrecognised.

Notes

Some notes

Examples

Testing whether $data variable starts with binary content consistent with a PDF file:

<xsl:variable name="in">
  <RangeExpr>
    <AdditiveExpr op="-">
      <Literal type="xs:integer" value="4"/>            
      <Literal type="xs:integer" value="2"/>
    </AdditiveExpr>
    <Literal type="xs:integer" value="8"/>
  </RangeExpr>
</xsl:variable>
<xsl:value-of select="xp:to-expression($in)"/>
 ==> "4 - 2 to 8"