Package net.sf.saxon.expr.parser

## Class XPathParser

- java.lang.Object
- - net.sf.saxon.expr.parser.XPathParser

- Direct Known Subclasses:
    `PatternParser30`, `SelectionParser`, `XQueryParser`

      public class XPathParser
      extends java.lang.Object

  Parser for XPath expressions and XSLT patterns.

  This code was originally inspired by James Clark's xt but has been totally rewritten (several times)

  The base class handles parsing of XPath 2.0, XPath 3.0 and XPath 3.1 syntax (switched by a languageVersion variable). Subclasses refine this to handle XQuery syntax (1.0, 3.0 and 3.1) and XQuery Update syntax.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `XPathParser.Accelerator` |
    `static class` | `XPathParser.NestedLocation` | A nested location: for use with XPath expressions and queries nested within some larger document.
    `static class` | `XPathParser.ParsedLanguage` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `allowSaxonExtensions` |
    `protected boolean` | `allowXPath30Syntax` |
    `protected boolean` | `allowXPath30XSLTExtensions` |
    `protected boolean` | `allowXPath31Syntax` |
    `protected int` | `catchDepth` |
    `protected java.util.function.IntPredicate` | `charChecker` |
    `protected CodeInjector` | `codeInjector` |
    `protected StaticContext` | `env` |
    `protected XPathParser.ParsedLanguage` | `language` |
    `protected int` | `languageVersion` |
    `protected ParserExtension` | `parserExtension` |
    `protected QNameParser` | `qNameParser` |
    `protected java.util.Stack<LocalBinding>` | `rangeVariables` |
    `protected boolean` | `scanOnly` |
    `protected Tokenizer` | `t` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XPathParser()` | Create an expression parser

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected boolean` | `atStartOfRelativePath()` | Test whether the current token is one that can start a RelativePathExpression
    `protected void` | `checkLanguageVersion30()` | Check that XPath 3.0 is in use
    `protected void` | `checkLanguageVersion31()` | Check that XPath 3.1 is in use
    `protected void` | `checkMapExtensions()` | Check that the map syntax is enabled: this covers the extensions to XPath 3.0 syntax defined in XSLT 3.0 (and also, of course, in XPath 3.1)
    `void` | `checkSyntaxExtensions​(java.lang.String construct)` | Check that Saxon syntax extensions are permitted
    `protected java.lang.String` | `currentTokenDisplay()` | Display the current token in an error message
    `protected void` | `customizeTokenizer​(Tokenizer t)` | Callback to tailor the tokenizer
    `void` | `declareRangeVariable​(LocalBinding declaration)` | Declare a range variable (record its existence within the parser).
    `protected boolean` | `disallowedAtStartOfRelativePath()` | Test whether the current token is one that is disallowed after a "leading lone slash".
    `void` | `expect​(int token)` | Expect a given token; fail if the current token is different.
    `protected LocalBinding` | `findRangeVariable​(StructuredQName qName)` | Locate a range variable with a given name.
    `protected Expression` | `generateApplyCall​(Expression functionItem, java.util.ArrayList<Expression> args)` |
    `CodeInjector` | `getCodeInjector()` | Set a CodeInjector which can be used to modify or wrap expressions on the tree as the expression is parsed and the tree is constructed.
    `protected java.lang.String` | `getLanguage()` | Get the current language (XPath or XQuery)
    `static java.lang.String` | `getMissingFunctionExplanation​(StructuredQName functionName, Configuration config)` | Get a message containing suggestions as to why a requested function might not be available
    `ItemType` | `getPlainType​(StructuredQName sq)` |
    `QNameParser` | `getQNameParser()` | Get the QNameParser to be used while parsing
    `java.util.Stack<LocalBinding>` | `getRangeVariables()` | Get the stack of in-scope range variables
    `StaticContext` | `getStaticContext()` | Get the static context used by this expression parser
    `Tokenizer` | `getTokenizer()` | Get the tokenizer (the lexical analyzer)
    `void` | `grumble​(java.lang.String message)` | Report a syntax error (a static error with error code XPST0003)
    `void` | `grumble​(java.lang.String message, java.lang.String errorCode)` | Report a static error
    `void` | `grumble​(java.lang.String message, java.lang.String errorCode, int offset)` | Report a static error, with location information
    `protected void` | `grumble​(java.lang.String message, StructuredQName errorCode, int offset)` | Report a static error
    `boolean` | `isAllowAbsentExpression​(boolean allowEmpty)` | Ask whether an absent expression is permitted
    `boolean` | `isAllowXPath31Syntax()` | Ask if XPath 3.1 is in use
    `protected boolean` | `isKeyword​(java.lang.String s)` | Test whether the current token is a given keyword.
    `protected boolean` | `isNamespaceTestAllowed()` | Ask whether the syntax namespace-node() is allowed in a node kind test.
    `protected static boolean` | `isReservedFunctionName30​(java.lang.String name)` | Check whether a function name is reserved in XPath 3.0 (when unprefixed)
    `static boolean` | `isReservedFunctionName31​(java.lang.String name)` | Check whether a function name is reserved in XPath 3.1 (when unprefixed)
    `protected boolean` | `isReservedInQuery​(java.lang.String uri)` |
    `protected Expression` | `makeCurriedFunction​(int offset, StructuredQName name, Expression[] args, IntSet placeMarkers)` | Process a function call in which one or more of the argument positions are represented as "?" placemarkers (indicating partial application or currying)
    `int` | `makeFingerprint​(java.lang.String qname, boolean useDefault)` | Make a NameCode, using the static context for namespace resolution
    `LocalNameTest` | `makeLocalNameTest​(short nodeType, java.lang.String localName)` | Make a LocalNameTest (*:name)
    `Location` | `makeLocation()` |
    `Location` | `makeLocation​(int offset)` | Make a location object corresponding to a specified offset in the query
    `NamespaceTest` | `makeNamespaceTest​(short nodeType, java.lang.String prefix)` | Make a NamespaceTest (name:*)
    `NodeTest` | `makeNameTest​(short nodeType, java.lang.String qname, boolean useDefault)` | Make a NameTest, using the static context for namespace resolution
    `Location` | `makeNestedLocation​(Location containingLoc, int line, int column, java.lang.String nearbyText)` | Make a Location object relative to an existing location
    `NodeName` | `makeNodeName​(java.lang.String qname, boolean useDefault)` | Make a FingerprintedQName, using the static context for namespace resolution
    `QNameTest` | `makeQNameTest​(short nodeType, java.lang.String qname)` |
    `protected Literal` | `makeStringLiteral​(java.lang.String currentTokenValue, boolean doUnescaping)` | Method to make a string literal from a token identified as a string literal.
    `StructuredQName` | `makeStructuredQName​(java.lang.String qname, java.lang.String defaultUri)` | Make a Structured QName, using the static context for namespace resolution
    `StructuredQName` | `makeStructuredQNameSilently​(java.lang.String qname, java.lang.String defaultUri)` | Make a NameCode, using the static context for namespace resolution.
    `Expression` | `makeTracer​(Expression exp, StructuredQName qName)` | If tracing, wrap an expression in a trace instruction
    `void` | `nextToken()` | Read the next token, catching any exception thrown by the tokenizer
    `static int` | `operatorPrecedence​(int operator)` | Get the precedence associated with a given operator
    `Expression` | `parse​(java.lang.String expression, int start, int terminator, StaticContext env)` | Parse a string representing an expression.
    `protected AnnotationList` | `parseAnnotationsList()` | Parse the annotations that can appear in a variable or function declaration
    `protected Expression` | `parseArrayCurlyConstructor()` | Parse a "curly" array constructor array "{" expr "}" Applies to XPath/XQuery 3.1 only
    `protected ItemType` | `parseArrayItemType()` | Get the item type used for array items (XPath 3.1) Syntax: array '(' '*' ') | array '(' SeqType ')' The "array(" has already been read
    `protected Expression` | `parseArraySquareConstructor()` | Parse a "square" array constructor "[" (exprSingle ("," exprSingle)* )? "]" Applies to XPath/XQuery 3.1 only
    `protected Expression` | `parseArrowPostfix​(Expression lhs)` | Parse an XPath 3.1 arrow operator ("=>")
    `protected Expression` | `parseBackTickedStringLiteral()` |
    `protected Expression` | `parseBasicStep​(boolean firstInPattern)` | Parse a basic step expression (without the predicates)
    `Expression` | `parseBinaryExpression​(Expression lhs, int minPrecedence)` | Parse a binary expression, using operator precedence parsing.
    `protected Expression` | `parseConstructor()` | Parse a node constructor.
    `Expression` | `parseDynamicFunctionCall​(Expression functionItem, Expression prefixArgument)` | Parse a dynamic function call
    `Expression` | `parseExpression()` | Parse a top-level Expression: ExprSingle ( ',' ExprSingle )*
    `Expression` | `parseExprSingle()` | Parse an ExprSingle
    `ItemType` | `parseExtendedItemType​(java.lang.String input, StaticContext env)` | Parse a string representing an extended item type: specifically, the content of itemType or nodeTest attributes in an exported package.
    `SequenceType` | `parseExtendedSequenceType​(java.lang.String input, StaticContext env)` | Parse a string representing a sequence type with syntax extensions used in exported stylesheets.
    `protected Expression` | `parseExtensionExpression()` | Parse an Extension Expression This construct is XQuery-only, so the XPath version of this method throws an error unconditionally
    `protected Expression` | `parseFLWORExpression()` | Parse a FOR or LET expression: for $x in expr (',' $y in expr)* 'return' expr let $x := expr (', $y := expr)* 'return' expr This version of the method handles the subset of the FLWOR syntax allowed in XPath
    `Expression` | `parseFunctionArgument()` | Parse an argument to a function call.
    `Expression` | `parseFunctionCall​(Expression prefixArgument)` | Parse a function call.
    `protected ItemType` | `parseFunctionItemType​(AnnotationList annotations)` | Get the item type used for function items (XPath 3.0 higher order functions)
    `protected Expression` | `parseInlineFunction​(AnnotationList annotations)` | Parse an inline function "function" "(" ParamList? ")" ("as" SequenceType)? EnclosedExpr On entry, "function (" has already been read
    `ItemType` | `parseItemType()` | Parse an ItemType within a SequenceType
    `protected Expression` | `parseLookup​(Expression lhs)` | Parse a lookup operator ("?")
    `protected Expression` | `parseMapExpression()` | Parse a map expression.
    `protected ItemType` | `parseMapItemType()` | Parse the item type used for maps (XSLT extension to XPath 3.0) Syntax: map '(' '*' ') | map '(' ItemType ',' SeqType ')' 'as' SeqType The "map(" has already been read
    `protected Expression` | `parseNamedFunctionReference()` | Parse a literal function item (introduced in XQuery 1.1) Syntax: QName # integer The QName and # have already been read
    `protected NodeTest` | `parseNodeTest​(short nodeType)` | Parse a NodeTest.
    `Expression` | `parseNumericLiteral​(boolean traceable)` |
    `Expression` | `parseParenthesizedExpression()` |
    `protected Expression` | `parsePathExpression()` | Parse a PathExpresssion.
    `protected Expression` | `parsePredicate()` | Parse the expression within a predicate.
    `protected Expression` | `parsePredicate​(Expression step)` |
    `protected Expression` | `parseRelativePath()` | Parse a relative path (a sequence of steps).
    `protected Expression` | `parseRemainingPath​(Expression start)` | Parse the remaining steps of an absolute path expression (one starting in "/" or "//").
    `SequenceType` | `parseSequenceType()` | Parse the sequence type production.
    `SequenceType` | `parseSequenceType​(java.lang.String input, StaticContext env)` | Parse a string representing a sequence type
    `protected Expression` | `parseSimpleMappingExpression()` | Parse an XPath 3.0 simple mapping expression ("!" operator)
    `protected Expression` | `parseStepExpression​(boolean firstInPattern)` | Parse a step (including an optional sequence of predicates)
    `protected Expression` | `parseStringConstructor()` |
    `protected Expression` | `parseStringLiteral​(boolean traceable)` |
    `protected Expression` | `parseSwitchExpression()` | Parse a Switch Expression.
    `protected Expression` | `parseTryCatchExpression()` | Parse a try/catch Expression This construct is XQuery-3.0 only, so the XPath version of this method throws an error unconditionally
    `protected Expression` | `parseTypeswitchExpression()` | Parse a Typeswitch Expression.
    `protected Expression` | `parseValidateExpression()` | Parse a Validate Expression.
    `Expression` | `parseVariableReference()` |
    `Expression` | `reportMissingFunction​(int offset, StructuredQName functionName, Expression[] arguments, java.util.List<java.lang.String> reasons)` |
    `protected StructuredQName` | `resolveFunctionName​(java.lang.String fname)` | Interpret a function name, returning it as a resolved QName
    `void` | `setAccelerator​(XPathParser.Accelerator accelerator)` | Set an accelerator which can be used for fast parsing of special cases
    `void` | `setAllowAbsentExpression​(boolean allowEmpty)` | Say whether an absent expression is permitted
    `void` | `setCatchDepth​(int depth)` | Set the depth of nesting within try/catch
    `void` | `setCodeInjector​(CodeInjector injector)` | Set a CodeInjector which can be used to modify or wrap expressions on the tree as the expression is parsed and the tree is constructed.
    `void` | `setLanguage​(XPathParser.ParsedLanguage language, int version)` | Set the current language (XPath or XQuery, XSLT Pattern, or SequenceType)
    `protected void` | `setLocation​(Expression exp)` | Set location information on an expression.
    `void` | `setLocation​(Expression exp, int offset)` | Set location information on an expression.
    `void` | `setLocation​(Clause clause, int offset)` | Set location information on a clause of a FLWOR expression.
    `void` | `setParserExtension​(ParserExtension extension)` | Set a parser extension which can handle extensions to the XPath syntax, e.g.
    `void` | `setQNameParser​(QNameParser qp)` | Set the QNameParser to be used while parsing
    `void` | `setRangeVariables​(java.util.Stack<LocalBinding> variables)` | Set a new stack of in-scope range variables
    `void` | `setRangeVariableStack​(java.util.Stack<LocalBinding> stack)` | Set the range variable stack.
    `void` | `setScanOnly​(boolean scanOnly)` | Set that we are parsing in "scan only"
    `protected void` | `testPermittedAxis​(int axis, java.lang.String errorCode)` |
    `void` | `undeclareRangeVariable()` | Note when the most recently declared range variable has gone out of scope
    `protected java.lang.CharSequence` | `unescape​(java.lang.String token)` | Unescape character references and built-in entity references in a string.
    `protected void` | `warning​(java.lang.String message)` | Output a warning message
    `static java.lang.String` | `whyDisallowedType​(PackageData pack, BuiltInAtomicType type)` | Determine whether a given built-in type is disallowed in a given environment, and in the case where it is disallowed, return a string explaining why

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### t

          protected Tokenizer t

    - #### env

          protected StaticContext env

    - #### rangeVariables

          protected java.util.Stack<LocalBinding> rangeVariables

    - #### qNameParser

          protected QNameParser qNameParser

    - #### parserExtension

          protected ParserExtension parserExtension

    - #### charChecker

          protected java.util.function.IntPredicate charChecker

    - #### allowXPath30Syntax

          protected boolean allowXPath30Syntax

    - #### allowXPath30XSLTExtensions

          protected boolean allowXPath30XSLTExtensions

    - #### allowXPath31Syntax

          protected boolean allowXPath31Syntax

    - #### allowSaxonExtensions

          protected boolean allowSaxonExtensions

    - #### scanOnly

          protected boolean scanOnly

    - #### codeInjector

          protected CodeInjector codeInjector

    - #### language

          protected XPathParser.ParsedLanguage language

    - #### languageVersion

          protected int languageVersion

    - #### catchDepth

          protected int catchDepth

  - ### Constructor Detail

    - #### XPathParser

          public XPathParser()

      Create an expression parser

  - ### Method Detail

    - #### setCodeInjector

          public void setCodeInjector​(CodeInjector injector)

      Set a CodeInjector which can be used to modify or wrap expressions on the tree as the expression is parsed and the tree is constructed. This is typically used to add tracing code.
      Parameters:
        `injector` - the code injector to be used

    - #### getCodeInjector

          public CodeInjector getCodeInjector()

      Set a CodeInjector which can be used to modify or wrap expressions on the tree as the expression is parsed and the tree is constructed. This is typically used to add tracing code.
      Returns:
        the code injector in use, if any; or null otherwise

    - #### setAccelerator

          public void setAccelerator​(XPathParser.Accelerator accelerator)

      Set an accelerator which can be used for fast parsing of special cases
      Parameters:
        `accelerator` - a parsing accelerator

    - #### getTokenizer

          public Tokenizer getTokenizer()

      Get the tokenizer (the lexical analyzer)
      Returns:
        the tokenizer (the lexical analyzer)

    - #### getStaticContext

          public StaticContext getStaticContext()

      Get the static context used by this expression parser
      Returns:
        the static context

    - #### setParserExtension

          public void setParserExtension​(ParserExtension extension)

      Set a parser extension which can handle extensions to the XPath syntax, e.g. for XQuery update extensions
      Parameters:
        `extension` - a parser extension

    - #### setCatchDepth

          public void setCatchDepth​(int depth)

      Set the depth of nesting within try/catch
      Parameters:
        `depth` - the depth of nesting

    - #### nextToken

          public void nextToken()
                         throws XPathException

      Read the next token, catching any exception thrown by the tokenizer
      Throws:
        `XPathException` - if an invalid token is found

    - #### expect

          public void expect​(int token)
                      throws XPathException

      Expect a given token; fail if the current token is different. Note that this method does not read any tokens.
      Parameters:
        `token` - the expected token
      Throws:
        `XPathException` - if the current token is not the expected token

    - #### grumble

          public void grumble​(java.lang.String message)
                       throws XPathException

      Report a syntax error (a static error with error code XPST0003)
      Parameters:
        `message` - the error message
      Throws:
        `XPathException` - always thrown: an exception containing the supplied message

    - #### grumble

          public void grumble​(java.lang.String message,
                              java.lang.String errorCode)
                       throws XPathException

      Report a static error
      Parameters:
        `message` - the error message
        `errorCode` - the error code
      Throws:
        `XPathException` - always thrown: an exception containing the supplied message

    - #### grumble

          public void grumble​(java.lang.String message,
                              java.lang.String errorCode,
                              int offset)
                       throws XPathException

      Report a static error, with location information
      Parameters:
        `message` - the error message
        `errorCode` - the error code
        `offset` - the coded location of the error, or -1 if the location of the current token should be used
      Throws:
        `XPathException` - always thrown: an exception containing the supplied message

    - #### grumble

          protected void grumble​(java.lang.String message,
                                 StructuredQName errorCode,
                                 int offset)
                          throws XPathException

      Report a static error
      Parameters:
        `message` - the error message
        `errorCode` - the error code
        `offset` - the coded location of the error, or -1 if the location of the current token should be used
      Throws:
        `XPathException` - always thrown: an exception containing the supplied message

    - #### warning

          protected void warning​(java.lang.String message)

      Output a warning message
      Parameters:
        `message` - the text of the message

    - #### setLanguage

          public void setLanguage​(XPathParser.ParsedLanguage language,
                                  int version)

      Set the current language (XPath or XQuery, XSLT Pattern, or SequenceType)
      Parameters:
        `language` - one of the constants `XPathParser.ParsedLanguage.XPATH`, `XPathParser.ParsedLanguage.XQUERY`, `XPathParser.ParsedLanguage.XSLT_PATTERN`, `XPathParser.ParsedLanguage.SEQUENCE_TYPE` etc
        `version` - The XPath or XQuery language version. For XQuery the value must be 10 (for "1.0"), 30 (for "3.0") or 31 (for "3.1"); for XPath it must be 20 (="2.0"), 30 (="3.0") or 31 (="3.1"). The value 305 is also recognized to mean XPath 3.0 plus the extensions defined in XSLT 3.0

    - #### getLanguage

          protected java.lang.String getLanguage()

      Get the current language (XPath or XQuery)
      Returns:
        a string representation of the language being parsed, for use in error messages

    - #### isAllowXPath31Syntax

          public boolean isAllowXPath31Syntax()

      Ask if XPath 3.1 is in use
      Returns:
        true if XPath 3.1 syntax (and therefore XQuery 3.1 syntax) is permitted

    - #### setQNameParser

          public void setQNameParser​(QNameParser qp)

      Set the QNameParser to be used while parsing
      Parameters:
        `qp` - the QNameParser

    - #### getQNameParser

          public QNameParser getQNameParser()

      Get the QNameParser to be used while parsing
      Returns:
        the QNameParser

    - #### currentTokenDisplay

          protected java.lang.String currentTokenDisplay()

      Display the current token in an error message
      Returns:
        the display representation of the token

    - #### parse

          public Expression parse​(java.lang.String expression,
                                  int start,
                                  int terminator,
                                  StaticContext env)
                           throws XPathException

      Parse a string representing an expression. This will accept an XPath expression if called on an ExpressionParser, or an XQuery expression if called on a QueryParser.
      Parameters:
        `expression` - the expression expressed as a String
        `start` - offset within the string where parsing is to start
        `terminator` - token to treat as terminating the expression
        `env` - the static context for the expression
      Returns:
        an Expression object representing the result of parsing
      Throws:
        `XPathException` - if the expression contains a syntax error

    - #### customizeTokenizer

          protected void customizeTokenizer​(Tokenizer t)

      Callback to tailor the tokenizer
      Parameters:
        `t` - the Tokenizer to be customized

    - #### parseSequenceType

          public SequenceType parseSequenceType​(java.lang.String input,
                                                StaticContext env)
                                         throws XPathException

      Parse a string representing a sequence type
      Parameters:
        `input` - the string, which should conform to the XPath SequenceType production
        `env` - the static context
      Returns:
        a SequenceType object representing the type
      Throws:
        `XPathException` - if any error is encountered

    - #### parseExtendedItemType

          public ItemType parseExtendedItemType​(java.lang.String input,
                                                StaticContext env)
                                         throws XPathException

      Parse a string representing an extended item type: specifically, the content of itemType or nodeTest attributes in an exported package. As well as regular itemType syntax, these allow combined node tests separated with "|", "except", or "intersect" operators. Expressions using these operators will always be parenthesized.
      Parameters:
        `input` - the string, which should conform to the XPath SequenceType production
        `env` - the static context
      Returns:
        a SequenceType object representing the type
      Throws:
        `XPathException` - if any error is encountered

    - #### parseExtendedSequenceType

          public SequenceType parseExtendedSequenceType​(java.lang.String input,
                                                        StaticContext env)
                                                 throws XPathException

      Parse a string representing a sequence type with syntax extensions used in exported stylesheets. Also allows the extensions permitted in saxon:as, e.g. tuple types, type aliases
      Parameters:
        `input` - the string, which should conform to the XPath SequenceType production
        `env` - the static context
      Returns:
        a SequenceType object representing the type
      Throws:
        `XPathException` - if any error is encountered

    - #### parseExpression

          public Expression parseExpression()
                                     throws XPathException

      Parse a top-level Expression: ExprSingle ( ',' ExprSingle )*
      Returns:
        the Expression object that results from parsing
      Throws:
        `XPathException` - if the expression contains a syntax error

    - #### parseExprSingle

          public Expression parseExprSingle()
                                     throws XPathException

      Parse an ExprSingle
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### parseBinaryExpression

          public Expression parseBinaryExpression​(Expression lhs,
                                                  int minPrecedence)
                                           throws XPathException

      Parse a binary expression, using operator precedence parsing. This is used to parse the part of the grammar consisting largely of binary operators distinguished by precedence: from "or expressions" down to "unary expressions". Algorithm for the mainstream binary operators is from Wikipedia article on precedence parsing; operator precedences are from the XQuery specification appendix B.
      Parameters:
        `lhs` - Left-hand side "basic expression"
        `minPrecedence` - the minimum precedence of an operator that is to be treated as not terminating the current expression
      Returns:
        the parsed expression
      Throws:
        `XPathException` - if a static error is found

    - #### operatorPrecedence

          public static int operatorPrecedence​(int operator)

      Get the precedence associated with a given operator
      Parameters:
        `operator` - the operator in question
      Returns:
        a higher number for higher precedence (closer binding)

    - #### parseTypeswitchExpression

          protected Expression parseTypeswitchExpression()
                                                  throws XPathException

      Parse a Typeswitch Expression. This construct is XQuery-only, so the XPath version of this method throws an error unconditionally
      Returns:
        the expression that results from the parsing
      Throws:
        `XPathException` - if a static error is found

    - #### parseSwitchExpression

          protected Expression parseSwitchExpression()
                                              throws XPathException

      Parse a Switch Expression. This construct is XQuery-only. SwitchExpr ::= "switch" "(" Expr ")" SwitchCaseClause+ "default" "return" ExprSingle SwitchCaseClause ::= ("case" ExprSingle)+ "return" ExprSingle
      Returns:
        the parsed expression
      Throws:
        `XPathException` - in the event of a syntax error

    - #### parseValidateExpression

          protected Expression parseValidateExpression()
                                                throws XPathException

      Parse a Validate Expression. This construct is XQuery-only, so the XPath version of this method throws an error unconditionally
      Returns:
        the parsed expression; except that this version of the method always throws an exception
      Throws:
        `XPathException` - if a static error is found

    - #### parseExtensionExpression

          protected Expression parseExtensionExpression()
                                                 throws XPathException

      Parse an Extension Expression This construct is XQuery-only, so the XPath version of this method throws an error unconditionally
      Returns:
        the parsed expression; except that this version of the method always throws an exception
      Throws:
        `XPathException` - if a static error is found

    - #### parseTryCatchExpression

          protected Expression parseTryCatchExpression()
                                                throws XPathException

      Parse a try/catch Expression This construct is XQuery-3.0 only, so the XPath version of this method throws an error unconditionally
      Returns:
        the parsed expression; except that this version of the method always throws an exception
      Throws:
        `XPathException` - if a static error is found

    - #### parseFLWORExpression

          protected Expression parseFLWORExpression()
                                             throws XPathException

      Parse a FOR or LET expression: for $x in expr (',' $y in expr)* 'return' expr let $x := expr (', $y := expr)* 'return' expr This version of the method handles the subset of the FLWOR syntax allowed in XPath
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### getPlainType

          public ItemType getPlainType​(StructuredQName sq)
                                throws XPathException

      Throws:
        `XPathException`

    - #### whyDisallowedType

          public static java.lang.String whyDisallowedType​(PackageData pack,
                                                           BuiltInAtomicType type)

      Determine whether a given built-in type is disallowed in a given environment, and in the case where it is disallowed, return a string explaining why
      Parameters:
        `pack` - the containing package
        `type` - the built-in type to be tested
      Returns:
        null if the type is OK to be used; or a string explaining why not.

    - #### parseSequenceType

          public SequenceType parseSequenceType()
                                         throws XPathException

      Parse the sequence type production. The QName must be the name of a built-in schema-defined data type.
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### parseItemType

          public ItemType parseItemType()
                                 throws XPathException

      Parse an ItemType within a SequenceType
      Returns:
        the ItemType after parsing
      Throws:
        `XPathException` - if a static error is found

    - #### parseFunctionItemType

          protected ItemType parseFunctionItemType​(AnnotationList annotations)
                                            throws XPathException

      Get the item type used for function items (XPath 3.0 higher order functions)
      Parameters:
        `annotations` - the list of annotation assertions for this function item type
      Returns:
        the item type representing a function item
      Throws:
        `XPathException` - if a static error occurs (including the case where XPath 3.0 syntax is not enabled)

    - #### parseMapItemType

          protected ItemType parseMapItemType()
                                       throws XPathException

      Parse the item type used for maps (XSLT extension to XPath 3.0) Syntax: map '(' '*' ') | map '(' ItemType ',' SeqType ')' 'as' SeqType The "map(" has already been read
      Returns:
        the item type of the map
      Throws:
        `XPathException` - if a parsing error occurs or if the map syntax is not available

    - #### parseArrayItemType

          protected ItemType parseArrayItemType()
                                         throws XPathException

      Get the item type used for array items (XPath 3.1) Syntax: array '(' '*' ') | array '(' SeqType ')' The "array(" has already been read
      Returns:
        the item type of the array
      Throws:
        `XPathException` - if a parsing error occurs or if the array syntax is not available

    - #### atStartOfRelativePath

          protected boolean atStartOfRelativePath()

      Test whether the current token is one that can start a RelativePathExpression
      Returns:
        the resulting subexpression

    - #### disallowedAtStartOfRelativePath

          protected boolean disallowedAtStartOfRelativePath()

      Test whether the current token is one that is disallowed after a "leading lone slash". These composite tokens have been parsed as operators, but are not allowed after "/" under the rules of erratum E24
      Returns:
        the resulting subexpression

    - #### parsePathExpression

          protected Expression parsePathExpression()
                                            throws XPathException

      Parse a PathExpresssion. This includes "true" path expressions such as A/B/C, and also constructs that may start a path expression such as a variable reference $name or a parenthesed expression (A|B). Numeric and string literals also come under this heading.
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### parseSimpleMappingExpression

          protected Expression parseSimpleMappingExpression()
                                                     throws XPathException

      Parse an XPath 3.0 simple mapping expression ("!" operator)
      Returns:
        the parsed expression
      Throws:
        `XPathException` - in the event of a syntax error

    - #### parseRelativePath

          protected Expression parseRelativePath()
                                          throws XPathException

      Parse a relative path (a sequence of steps). Called when the current token immediately follows a separator (/ or //), or an implicit separator (XYZ is equivalent to ./XYZ)
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### parseRemainingPath

          protected Expression parseRemainingPath​(Expression start)
                                           throws XPathException

      Parse the remaining steps of an absolute path expression (one starting in "/" or "//"). Note that the token immediately after the "/" or "//" has already been read, and in the case of "/", it has been confirmed that we have a path expression starting with "/" rather than a standalone "/" expression.
      Parameters:
        `start` - the initial implicit expression: root() in the case of "/", root()/descendant-or-self::node in the case of "//"
      Returns:
        the completed path expression
      Throws:
        `XPathException` - if a static error is found

    - #### parseStepExpression

          protected Expression parseStepExpression​(boolean firstInPattern)
                                            throws XPathException

      Parse a step (including an optional sequence of predicates)
      Parameters:
        `firstInPattern` - true only if we are parsing the first step in a RelativePathPattern in the XSLT Pattern syntax
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### parsePredicate

          protected Expression parsePredicate​(Expression step)
                                       throws XPathException

      Throws:
        `XPathException`

    - #### parseArrowPostfix

          protected Expression parseArrowPostfix​(Expression lhs)
                                          throws XPathException

      Parse an XPath 3.1 arrow operator ("=>")
      Returns:
        the expression that results from the parsing
      Throws:
        `XPathException`

    - #### parsePredicate

          protected Expression parsePredicate()
                                       throws XPathException

      Parse the expression within a predicate. A separate method so it can be overridden
      Returns:
        the expression within the predicate
      Throws:
        `XPathException` - if a static error is found

    - #### isReservedInQuery

          protected boolean isReservedInQuery​(java.lang.String uri)

    - #### parseBasicStep

          protected Expression parseBasicStep​(boolean firstInPattern)
                                       throws XPathException

      Parse a basic step expression (without the predicates)
      Parameters:
        `firstInPattern` - true only if we are parsing the first step in a RelativePathPattern in the XSLT Pattern syntax
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### parseParenthesizedExpression

          public Expression parseParenthesizedExpression()
                                                  throws XPathException

      Throws:
        `XPathException`

    - #### testPermittedAxis

          protected void testPermittedAxis​(int axis,
                                           java.lang.String errorCode)
                                    throws XPathException

      Throws:
        `XPathException`

    - #### parseNumericLiteral

          public Expression parseNumericLiteral​(boolean traceable)
                                         throws XPathException

      Throws:
        `XPathException`

    - #### parseStringLiteral

          protected Expression parseStringLiteral​(boolean traceable)
                                           throws XPathException

      Throws:
        `XPathException`

    - #### parseBackTickedStringLiteral

          protected Expression parseBackTickedStringLiteral()
                                                     throws XPathException

      Throws:
        `XPathException`

    - #### parseStringConstructor

          protected Expression parseStringConstructor()
                                               throws XPathException

      Throws:
        `XPathException`

    - #### parseVariableReference

          public Expression parseVariableReference()
                                            throws XPathException

      Throws:
        `XPathException`

    - #### makeStringLiteral

          protected Literal makeStringLiteral​(java.lang.String currentTokenValue,
                                              boolean doUnescaping)
                                       throws XPathException

      Method to make a string literal from a token identified as a string literal. This is trivial in XPath, but in XQuery the method is overridden to identify pseudo-XML character and entity references. Note that the job of handling doubled string delimiters is done by the tokenizer.
      Parameters:
        `currentTokenValue` - the token as read (excluding quotation marks)
      Returns:
        The string value of the string literal
      Throws:
        `XPathException` - if a static error is found

    - #### unescape

          protected java.lang.CharSequence unescape​(java.lang.String token)
                                             throws XPathException

      Unescape character references and built-in entity references in a string. Does nothing in XPath, because XPath does not recognize entity references in string literals
      Parameters:
        `token` - the input string, which may include XML-style character references or built-in entity references
      Returns:
        the string with character references and built-in entity references replaced by their expansion
      Throws:
        `XPathException` - if a malformed character or entity reference is found

    - #### parseConstructor

          protected Expression parseConstructor()
                                         throws XPathException

      Parse a node constructor. This is allowed only in XQuery, so the method throws an error for XPath.
      Returns:
        the expression that results from the parsing
      Throws:
        `XPathException` - if a static error occurs

    - #### parseDynamicFunctionCall

          public Expression parseDynamicFunctionCall​(Expression functionItem,
                                                     Expression prefixArgument)
                                              throws XPathException

      Parse a dynamic function call
      Parameters:
        `functionItem` - the expression that determines the function to be called
        `prefixArgument` - the LHS of an arrow operator, or null if this is not part of an arrow expression
      Returns:
        the expression that results from the parsing
      Throws:
        `XPathException` - if a static error is found

    - #### generateApplyCall

          protected Expression generateApplyCall​(Expression functionItem,
                                                 java.util.ArrayList<Expression> args)
                                          throws XPathException

      Throws:
        `XPathException`

    - #### parseLookup

          protected Expression parseLookup​(Expression lhs)
                                    throws XPathException

      Parse a lookup operator ("?")
      Parameters:
        `lhs` - the expression that the function to be called
      Returns:
        the expression that results from the parsing
      Throws:
        `XPathException` - if a static error is found

    - #### parseNodeTest

          protected NodeTest parseNodeTest​(short nodeType)
                                    throws XPathException

      Parse a NodeTest. One of QName, prefix:*, *:suffix, *, text(), node(), comment(), or processing-instruction(literal?), or element(~,~), attribute(~,~), etc.
      Parameters:
        `nodeType` - the node type being sought if one is specified
      Returns:
        the resulting NodeTest object
      Throws:
        `XPathException` - if any error is encountered

    - #### isNamespaceTestAllowed

          protected boolean isNamespaceTestAllowed()

      Ask whether the syntax namespace-node() is allowed in a node kind test.
      Returns:
        true unless XPath 2.0 / XQuery 1.0 syntax is required

    - #### checkLanguageVersion30

          protected void checkLanguageVersion30()
                                         throws XPathException

      Check that XPath 3.0 is in use
      Throws:
        `XPathException` - if XPath 3.0 support was not requested

    - #### checkLanguageVersion31

          protected void checkLanguageVersion31()
                                         throws XPathException

      Check that XPath 3.1 is in use
      Throws:
        `XPathException` - if XPath 3.1 support was not requested

    - #### checkMapExtensions

          protected void checkMapExtensions()
                                     throws XPathException

      Check that the map syntax is enabled: this covers the extensions to XPath 3.0 syntax defined in XSLT 3.0 (and also, of course, in XPath 3.1)
      Throws:
        `XPathException` - if XPath 3.1 support was not requested

    - #### checkSyntaxExtensions

          public void checkSyntaxExtensions​(java.lang.String construct)
                                     throws XPathException

      Check that Saxon syntax extensions are permitted
      Throws:
        `XPathException` - if Saxon syntax extensions have not been enabled

    - #### parseMapExpression

          protected Expression parseMapExpression()
                                           throws XPathException

      Parse a map expression. Requires XPath/XQuery 3.0 Provisional syntax map { expr : expr (, expr : expr )*} }
      Returns:
        the map expression
      Throws:
        `XPathException` - if parsing fails

    - #### parseArraySquareConstructor

          protected Expression parseArraySquareConstructor()
                                                    throws XPathException

      Parse a "square" array constructor "[" (exprSingle ("," exprSingle)* )? "]" Applies to XPath/XQuery 3.1 only
      Throws:
        `XPathException`

    - #### parseArrayCurlyConstructor

          protected Expression parseArrayCurlyConstructor()
                                                   throws XPathException

      Parse a "curly" array constructor array "{" expr "}" Applies to XPath/XQuery 3.1 only
      Returns:
        the parsed expression
      Throws:
        `XPathException` - if the syntax is invalid or the construct is not permitted

    - #### parseFunctionCall

          public Expression parseFunctionCall​(Expression prefixArgument)
                                       throws XPathException

      Parse a function call. function-name '(' ( Expression (',' Expression )* )? ')'
      Parameters:
        `prefixArgument` - left hand operand of arrow operator, or null in the case of a conventional function call
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### reportMissingFunction

          public Expression reportMissingFunction​(int offset,
                                                  StructuredQName functionName,
                                                  Expression[] arguments,
                                                  java.util.List<java.lang.String> reasons)
                                           throws XPathException

      Throws:
        `XPathException`

    - #### getMissingFunctionExplanation

          public static java.lang.String getMissingFunctionExplanation​(StructuredQName functionName,
                                                                       Configuration config)

      Get a message containing suggestions as to why a requested function might not be available
      Parameters:
        `functionName` - the name of the required function
        `config` - the Saxon configuration
      Returns:
        a suggestion as to why the function was not found; or null if no suggestions can be offered.

    - #### resolveFunctionName

          protected StructuredQName resolveFunctionName​(java.lang.String fname)
                                                 throws XPathException

      Interpret a function name, returning it as a resolved QName
      Parameters:
        `fname` - the lexical QName used as the function name; or an EQName presented by the tokenizer as a name in Clark notation
      Returns:
        the Structured QName obtained by resolving any prefix in the function name
      Throws:
        `XPathException` - if the supplied name is not a valid QName or if its prefix is not in scope

    - #### parseFunctionArgument

          public Expression parseFunctionArgument()
                                           throws XPathException

      Parse an argument to a function call. Separate method so it can be overridden. With higher-order-function syntax in XPath 3.0/XQuery 3.0, this returns null if the pseudo-argument "?" is found.
      Returns:
        the Expression used as the argument, or null if the argument is the place-holder "?"
      Throws:
        `XPathException` - if the argument expression does not parse correctly

    - #### parseNamedFunctionReference

          protected Expression parseNamedFunctionReference()
                                                    throws XPathException

      Parse a literal function item (introduced in XQuery 1.1) Syntax: QName # integer The QName and # have already been read
      Returns:
        an ExternalObject representing the function item
      Throws:
        `XPathException` - if a static error is encountered

    - #### parseAnnotationsList

          protected AnnotationList parseAnnotationsList()
                                                 throws XPathException

      Parse the annotations that can appear in a variable or function declaration
      Returns:
        the annotations as a list
      Throws:
        `XPathException` - in the event of a syntax error

    - #### parseInlineFunction

          protected Expression parseInlineFunction​(AnnotationList annotations)
                                            throws XPathException

      Parse an inline function "function" "(" ParamList? ")" ("as" SequenceType)? EnclosedExpr On entry, "function (" has already been read
      Parameters:
        `annotations` - the function annotations, which have already been read, or null if there are none
      Returns:
        the parsed inline function
      Throws:
        `XPathException` - if a syntax error is found

    - #### makeCurriedFunction

          protected Expression makeCurriedFunction​(int offset,
                                                   StructuredQName name,
                                                   Expression[] args,
                                                   IntSet placeMarkers)
                                            throws XPathException

      Process a function call in which one or more of the argument positions are represented as "?" placemarkers (indicating partial application or currying)
      Parameters:
        `offset` - the position of the expression in the source text
        `name` - the function name (as if there were no currying)
        `args` - the arguments (with EmptySequence in the placemarker positions)
        `placeMarkers` - the positions of the placemarkers @return the curried function
      Returns:
        the curried function
      Throws:
        `XPathException` - if a static error is found

    - #### isReservedFunctionName30

          protected static boolean isReservedFunctionName30​(java.lang.String name)

      Check whether a function name is reserved in XPath 3.0 (when unprefixed)
      Parameters:
        `name` - the function name (the local-name as a string)
      Returns:
        true if the function name is reserved

    - #### isReservedFunctionName31

          public static boolean isReservedFunctionName31​(java.lang.String name)

      Check whether a function name is reserved in XPath 3.1 (when unprefixed)
      Parameters:
        `name` - the function name (the local-name as a string)
      Returns:
        true if the function name is reserved

    - #### getRangeVariables

          public java.util.Stack<LocalBinding> getRangeVariables()

      Get the stack of in-scope range variables
      Returns:
        the stack of variables

    - #### setRangeVariables

          public void setRangeVariables​(java.util.Stack<LocalBinding> variables)

      Set a new stack of in-scope range variables
      Parameters:
        `variables` - the stack of variables

    - #### declareRangeVariable

          public void declareRangeVariable​(LocalBinding declaration)

      Declare a range variable (record its existence within the parser). A range variable is a variable declared within an expression, as distinct from a variable declared in the context.
      Parameters:
        `declaration` - the variable declaration to be added to the stack

    - #### undeclareRangeVariable

          public void undeclareRangeVariable()

      Note when the most recently declared range variable has gone out of scope

    - #### findRangeVariable

          protected LocalBinding findRangeVariable​(StructuredQName qName)

      Locate a range variable with a given name. (By "range variable", we mean a variable declared within the expression where it is used.)
      Parameters:
        `qName` - identifies the name of the range variable
      Returns:
        null if not found (this means the variable is probably a context variable); otherwise the relevant RangeVariable

    - #### setRangeVariableStack

          public void setRangeVariableStack​(java.util.Stack<LocalBinding> stack)

      Set the range variable stack. Used when parsing a nested subexpression inside an attribute constructor.
      Parameters:
        `stack` - the stack to be used for local variables declared within the expression

    - #### makeFingerprint

          public final int makeFingerprint​(java.lang.String qname,
                                           boolean useDefault)
                                    throws XPathException

      Make a NameCode, using the static context for namespace resolution
      Parameters:
        `qname` - The name as written, in the form "[prefix:]localname"; alternatively, a QName in Clark notation ({uri}local)
        `useDefault` - Defines the action when there is no prefix. If true, use the default namespace URI for element names. If false, use no namespace URI (as for attribute names).
      Returns:
        the fingerprint, which can be used to identify this name in the name pool
      Throws:
        `XPathException` - if the name is invalid, or the prefix undeclared

    - #### makeStructuredQNameSilently

          public final StructuredQName makeStructuredQNameSilently​(java.lang.String qname,
                                                                   java.lang.String defaultUri)
                                                            throws XPathException

      Make a NameCode, using the static context for namespace resolution. This variant of the method does not call "grumble" to report any errors to the ErrorListener, it only reports errors by throwing exceptions. This allows the caller to control the message output.
      Parameters:
        `qname` - The name as written, in the form "[prefix:]localname"
        `defaultUri` - Defines the URI to be returned if there is no prefix.
      Returns:
        the structured QName
      Throws:
        `XPathException` - if the name is invalid, or the prefix undeclared or if the name is not a lexically valid QName

    - #### makeStructuredQName

          public final StructuredQName makeStructuredQName​(java.lang.String qname,
                                                           java.lang.String defaultUri)
                                                    throws XPathException

      Make a Structured QName, using the static context for namespace resolution
      Parameters:
        `qname` - The name as written, in the form "[prefix:]localname"; alternatively, a QName in Clark format ({uri}local)
        `defaultUri` - The URI to be used if the name is written as a localname with no prefix
      Returns:
        the QName as an instance of StructuredQName
      Throws:
        `XPathException` - if the name is invalid, or the prefix undeclared

    - #### makeNodeName

          public final NodeName makeNodeName​(java.lang.String qname,
                                             boolean useDefault)
                                      throws XPathException

      Make a FingerprintedQName, using the static context for namespace resolution
      Parameters:
        `qname` - The name as written, in the form "[prefix:]localname"; alternatively, a QName in Clark format ({uri}local)
        `useDefault` - Defines the action when there is no prefix. If true, use the default namespace URI for element names. If false, use no namespace URI (as for attribute names).
      Returns:
        the fingerprinted QName
      Throws:
        `XPathException` - if the name is invalid, or the prefix undeclared

    - #### makeNameTest

          public NodeTest makeNameTest​(short nodeType,
                                       java.lang.String qname,
                                       boolean useDefault)
                                throws XPathException

      Make a NameTest, using the static context for namespace resolution
      Parameters:
        `nodeType` - the type of node required (identified by a constant in class Type)
        `qname` - the lexical QName of the required node; alternatively, a QName in Clark notation ({uri}local)
        `useDefault` - true if the default namespace should be used when the QName is unprefixed
      Returns:
        a NameTest, representing a pattern that tests for a node of a given node kind and a given name
      Throws:
        `XPathException` - if the QName is invalid

    - #### makeQNameTest

          public QNameTest makeQNameTest​(short nodeType,
                                         java.lang.String qname)
                                  throws XPathException

      Throws:
        `XPathException`

    - #### makeNamespaceTest

          public NamespaceTest makeNamespaceTest​(short nodeType,
                                                 java.lang.String prefix)
                                          throws XPathException

      Make a NamespaceTest (name:*)
      Parameters:
        `nodeType` - integer code identifying the type of node required
        `prefix` - the namespace prefix
      Returns:
        the NamespaceTest, a pattern that matches all nodes in this namespace
      Throws:
        `XPathException` - if the namespace prefix is not declared

    - #### makeLocalNameTest

          public LocalNameTest makeLocalNameTest​(short nodeType,
                                                 java.lang.String localName)
                                          throws XPathException

      Make a LocalNameTest (*:name)
      Parameters:
        `nodeType` - the kind of node to be matched
        `localName` - the requred local name
      Returns:
        a LocalNameTest, a pattern which matches all nodes of a given local name, regardless of namespace
      Throws:
        `XPathException` - if the local name is invalid

    - #### setLocation

          protected void setLocation​(Expression exp)

      Set location information on an expression. At present this consists of a simple line number. Needed mainly for XQuery.
      Parameters:
        `exp` - the expression whose location information is to be set

    - #### setLocation

          public void setLocation​(Expression exp,
                                  int offset)

      Set location information on an expression. At present only the line number is retained. Needed mainly for XQuery. This version of the method supplies an explicit offset (character position within the expression or query), which the tokenizer can convert to a line number and column number.
      Parameters:
        `exp` - the expression whose location information is to be set
        `offset` - the character position within the expression (ignoring newlines)

    - #### makeLocation

          public Location makeLocation​(int offset)

      Make a location object corresponding to a specified offset in the query

    - #### setLocation

          public void setLocation​(Clause clause,
                                  int offset)

      Set location information on a clause of a FLWOR expression. This version of the method supplies an explicit offset (character position within the expression or query), which the tokenizer can convert to a line number and column number.
      Parameters:
        `clause` - the clause whose location information is to be set
        `offset` - the character position within the expression (ignoring newlines)

    - #### makeLocation

          public Location makeLocation()

    - #### makeNestedLocation

          public Location makeNestedLocation​(Location containingLoc,
                                             int line,
                                             int column,
                                             java.lang.String nearbyText)

      Make a Location object relative to an existing location
      Parameters:
        `containingLoc` - the containing location
        `line` - the line number relative to the containing location (zero-based)
        `column` - the column number relative to the containing location (zero-based)
        `nearbyText` - (maybe null) expression text around the point of the error
      Returns:
        a suitable Location object

    - #### makeTracer

          public Expression makeTracer​(Expression exp,
                                       StructuredQName qName)

      If tracing, wrap an expression in a trace instruction
      Parameters:
        `exp` - the expression to be wrapped
        `qName` - the name of the construct (if applicable)
      Returns:
        the expression that does the tracing

    - #### isKeyword

          protected boolean isKeyword​(java.lang.String s)

      Test whether the current token is a given keyword.
      Parameters:
        `s` - The string to be compared with the current token
      Returns:
        true if they are the same

    - #### setScanOnly

          public void setScanOnly​(boolean scanOnly)

      Set that we are parsing in "scan only"
      Parameters:
        `scanOnly` - true if parsing is to proceed in scan-only mode. In this mode namespace bindings are not yet known, so no attempt is made to look up namespace prefixes.

    - #### setAllowAbsentExpression

          public void setAllowAbsentExpression​(boolean allowEmpty)

      Say whether an absent expression is permitted
      Parameters:
        `allowEmpty` - true if it is permitted for the expression to consist only of whitespace and comments, in which case the result of parsing will be an EmptySequence literal

    - #### isAllowAbsentExpression

          public boolean isAllowAbsentExpression​(boolean allowEmpty)

      Ask whether an absent expression is permitted
      Returns:
        true if it is permitted for the expression to consist only of whitespace and comments, in which case the result of parsing will be an EmptySequence literal