net.sf.saxon.query

## Class QueryParser

- java.lang.Object
- - net.sf.saxon.expr.parser.ExpressionParser
  - - net.sf.saxon.query.QueryParser

- Direct Known Subclasses:
    ExtendedXQueryParser

      public class QueryParser
      extends ExpressionParser

  This class defines extensions to the XPath parser to handle the additional syntax supported in XQuery

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class net.sf.saxon.expr.parser.ExpressionParser

      `ExpressionParser.TemporaryContainer`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected Executable` | `executable`
    `Set` | `importedModules`
    `protected String` | `queryVersion`
    `static String` | `XQUERY10`
    `static String` | `XQUERY30`

    - ### Fields inherited from class net.sf.saxon.expr.parser.ExpressionParser

      `allowXPath30Syntax, catchDepth, codeInjector, defaultContainer, env, language, languageVersion, nameChecker, rangeVariables, scanOnly, SEQUENCE_TYPE, t, XPATH, XQUERY, XSLT_PATTERN`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `QueryParser()` Constructor for internal use: this class should be instantiated via the QueryModule

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `applyModuleImport(net.sf.saxon.query.QueryParser.Import mImport)`
    `protected boolean` | `atStartOfRelativePath()` Test whether the current token is one that can start a RelativePathExpression
    `protected void` | `checkForClauseAllowingEmpty(ForClause clause)` Check a ForClause for an "outer for"
    `protected void` | `customizeTokenizer(Tokenizer t)` Callback to tailor the tokenizer
    `Executable` | `getExecutable()` Get the executable containing this expression.
    `protected String` | `getLanguage()` Get the current language (XPath or XQuery)
    `int` | `getPermittedFunctions()` Get the permitted set of standard functions in this environment
    `protected void` | `grumble(String message, StructuredQName errorCode, int offset)` Report a static error
    `protected boolean` | `isReservedFunctionName(String reservedStr)`
    `protected void` | `lookAhead()` Lookahead one token, catching any exception thrown by the tokenizer.
    `protected LetExpression` | `makeLetExpression()` Make a LetExpression.
    `protected void` | `makeSimpleContent(Expression content, SimpleNodeConstructor inst, int offset)` Make the instructions for the children of a node with simple content (attribute, text, PI, etc)
    `static Expression` | `makeStringJoin(Expression exp, StaticContext env)` Make a string-join expression that concatenates the string-values of items in a sequence with intervening spaces.
    `protected Literal` | `makeStringLiteral(String token)` Method to make a string literal from a token identified as a string literal.
    `XQueryExpression` | `makeXQueryExpression(String query, QueryModule mainModule, Configuration config)` Create an XQueryExpression
    `QueryParser` | `newParser()` Create a new parser of the same kind
    `protected String` | `normalizeEQName(String s)` Convert a QName in expanded-name format "uri":local into Clark format
    `protected Expression` | `parseConstructor()` Parse a node constructor.
    `protected void` | `parseContextItemDeclaration()` Parse a context item declaration.
    `protected void` | `parseCountClause(List<Clause> clauseList)` Parse a count clause.
    `protected void` | `parseDecimalFormatDeclaration()` Parse the "declare decimal-format" declaration.
    `protected void` | `parseDefaultDecimalFormat()`
    `protected Expression` | `parseExtensionExpression()` Parse an Extension Expression.
    `protected Expression` | `parseFLWORExpression()` Parse a FLWOR expression.
    `protected void` | `parseFunctionDeclaration(Map<StructuredQName,Annotation> annotations)` Parse a function declaration.
    `protected void` | `parseGroupByClause(List<Clause> clauseList)` Parse a Group By clause.
    `void` | `parseLibraryModule(String queryString, QueryModule env)` Parse a library module.
    `protected Expression` | `parseNamedNamespaceConstructor(int offset)`
    `protected Expression` | `parseNamespaceConstructor(int offset)`
    `protected void` | `parseOutputDeclaration(StructuredQName varName, String value)`
    `protected void` | `parseRevalidationDeclaration()` Parse the "declare revalidation" declaration.
    `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 void` | `parseUpdatingFunctionDeclaration()` Parse an updating function declaration (allowed in XQuery Update only)
    `protected Expression` | `parseValidateExpression()` Parse a Validate Expression.
    `protected void` | `parseWindowClause(List<Clause> clauseList)` Parse a tumbling or sliding window clause.
    `protected String` | `readCollationName()`
    `Expression` | `setDefaultValue(String exp)` Parse the expression (inside a string literal) used to define default values for external variables.
    `void` | `setDisableCycleChecks(boolean disable)` Disable checks for certain kinds of cycle.
    `void` | `setExecutable(Executable exec)` Set the executable used for this query expression
    `static Expression` | `stringify(Expression exp, boolean noNodeIfEmpty, Configuration config)` Convert an expression so it generates a space-separated sequence of strings
    `protected void` | `testPermittedAxis(byte axis)`
    `String` | `URILiteral(String in)` Handle a URI literal.

    - ### Methods inherited from class net.sf.saxon.expr.parser.ExpressionParser

      `currentTokenDisplay, declareRangeVariable, disallowedAtStartOfRelativePath, expect, findRangeVariable, getCodeInjector, getDefaultContainer, getNameChecker, getRangeVariables, getStaticContext, getTokenizer, grumble, grumble, grumble, isKeyword, isNamespaceTestAllowed, isReservedInQuery, makeCurriedFunction, makeLocalNameTest, makeNameCode, makeNamespaceTest, makeNameTest, makeNodeName, makeStructuredQName, makeStructuredQNameSilently, makeTracer, nextToken, parse, parseAnnotations, parseBasicStep, parseBinaryExpression, parseDynamicFunctionCall, parseExpression, parseExprSingle, parseFunctionArgument, parseFunctionCall, parseFunctionItemType, parseInlineFunction, parseItemType, parseLiteralFunctionItem, parseMapExpression, parseMapItemType, parseNodeTest, parseNumericLiteral, parseParenthesizedItemType, parsePathExpression, parsePredicate, parseRelativePath, parseRemainingPath, parseSequenceType, parseSequenceType, parseSimpleMappingExpression, parseStepExpression, parseStringLiteral, parseSwitchExpression, parseTypePattern, parseVariableReference, reportMissingFunction, resolveFunctionName, setCodeInjector, setDefaultContainer, setLanguage, setLocation, setLocation, setLocation, setRangeVariables, setRangeVariableStack, setScanOnly, undeclareRangeVariable, warning`

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

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

- - ### Field Detail

    - #### XQUERY10

          public static final String XQUERY10

      See Also:
        Constant Field Values

    - #### XQUERY30

          public static final String XQUERY30

      See Also:
        Constant Field Values

    - #### queryVersion

          protected String queryVersion

    - #### executable

          protected Executable executable

    - #### importedModules

          public Set importedModules

  - ### Constructor Detail

    - #### QueryParser

          public QueryParser()

      Constructor for internal use: this class should be instantiated via the QueryModule

  - ### Method Detail

    - #### newParser

          public QueryParser newParser()

      Create a new parser of the same kind
      Returns:
        a new parser of the same kind as this one

    - #### makeXQueryExpression

          public XQueryExpression makeXQueryExpression(String query,
                                              QueryModule mainModule,
                                              Configuration config)
                                                throws XPathException

      Create an XQueryExpression
      Parameters:
        `query` - the source text of the query
        `mainModule` - the static context of the query
        `config` - the Saxon configuration
      Returns:
        the compiled XQuery expression
      Throws:
        `XPathException` - if the expression contains static errors

    - #### getPermittedFunctions

          public int getPermittedFunctions()

      Get the permitted set of standard functions in this environment
      Returns:
        a code indicating which system library functions are supported in this version of the language

    - #### getExecutable

          public Executable getExecutable()

      Get the executable containing this expression.
      Returns:
        the executable

    - #### setExecutable

          public void setExecutable(Executable exec)

      Set the executable used for this query expression
      Parameters:
        `exec` - the executable

    - #### setDisableCycleChecks

          public void setDisableCycleChecks(boolean disable)

      Disable checks for certain kinds of cycle. This is equivalent to

      `declare option saxon:allow-cycles "true"`

      Parameters:
        `disable` - true if checks for import cycles are to be suppressed, that is, if cycles should be allowed

    - #### customizeTokenizer

          protected void customizeTokenizer(Tokenizer t)

      Callback to tailor the tokenizer
      Overrides:
        `customizeTokenizer` in class `ExpressionParser`
      Parameters:
        `t` - the Tokenizer to be customized

    - #### parseLibraryModule

          public final void parseLibraryModule(String queryString,
                                QueryModule env)
                                        throws XPathException

      Parse a library module. Prolog? Expression
      Parameters:
        `queryString` - The text of the library module.
        `env` - The static context. The result of parsing a library module is that the static context is populated with a set of function declarations and variable declarations. Each library module must have its own static context objext.
      Throws:
        `XPathException` - if the expression contains a syntax error

    - #### grumble

          protected void grumble(String message,
                     StructuredQName errorCode,
                     int offset)
                          throws XPathException

      Report a static error
      Overrides:
        `grumble` in class `ExpressionParser`
      Parameters:
        `message` - the error message
        `offset` - the location in the source query
        `errorCode` - the error code
      Throws:
        `XPathException` - always thrown: an exception containing the supplied message

    - #### parseRevalidationDeclaration

          protected void parseRevalidationDeclaration()
                                               throws XPathException

      Parse the "declare revalidation" declaration. Syntax: not allowed unless XQuery update is in use
      Throws:
        `XPathException` - if the syntax is incorrect, or is not allowed in this XQuery processor

    - #### applyModuleImport

          public void applyModuleImport(net.sf.saxon.query.QueryParser.Import mImport)
                                 throws XPathException

      Throws:
        `XPathException`

    - #### parseDecimalFormatDeclaration

          protected void parseDecimalFormatDeclaration()
                                                throws XPathException

      Parse the "declare decimal-format" declaration. Allowed in XQuery 1.1 only
      Throws:
        `XPathException` - if parsing fails

    - #### parseDefaultDecimalFormat

          protected void parseDefaultDecimalFormat()
                                            throws XPathException

      Throws:
        `XPathException`

    - #### parseContextItemDeclaration

          protected void parseContextItemDeclaration()
                                              throws XPathException

      Parse a context item declaration. Allowed only in XQuery 3.0
      Throws:
        `XPathException` - if parsing fails

    - #### isReservedFunctionName

          protected boolean isReservedFunctionName(String reservedStr)

    - #### parseFunctionDeclaration

          protected void parseFunctionDeclaration(Map<StructuredQName,Annotation> annotations)
                                           throws XPathException

      Parse a function declaration.

      Syntax:
      <"declare" "function"> QName "(" ParamList? ")" ("as" SequenceType)? (EnclosedExpr | "external")

      On entry, the "declare function" has already been recognized

      Parameters:
        `annotations` - the list of annotations that have been encountered for this function declaration
      Throws:
        `XPathException` - if a syntax error is found

    - #### parseUpdatingFunctionDeclaration

          protected void parseUpdatingFunctionDeclaration()
                                                   throws XPathException

      Parse an updating function declaration (allowed in XQuery Update only)
      Throws:
        `XPathException` - if parsing fails or if updating functions are not allowed

    - #### parseOutputDeclaration

          protected void parseOutputDeclaration(StructuredQName varName,
                                    String value)
                                         throws XPathException

      Throws:
        `XPathException`

    - #### setDefaultValue

          public Expression setDefaultValue(String exp)

      Parse the expression (inside a string literal) used to define default values for external variables. This requires instantiating a nested XPath parser. (This is a Saxon extension for XQuery 1.0 which becomes obsolete with XQuery 3.0)
      Parameters:
        `exp` - holds the expression used to define a default value
      Returns:
        the compiled expression that computes the default value

    - #### parseFLWORExpression

          protected Expression parseFLWORExpression()
                                             throws XPathException

      Parse a FLWOR expression. This replaces the XPath "for" expression. Full syntax:

      [41] FLWORExpr ::= (ForClause | LetClause)+ WhereClause? OrderByClause? "return" ExprSingle [42] ForClause ::= <"for" "$"> VarName TypeDeclaration? PositionalVar? "in" ExprSingle ("," "$" VarName TypeDeclaration? PositionalVar? "in" ExprSingle)* [43] PositionalVar ::= "at" "$" VarName [44] LetClause ::= <"let" "$"> VarName TypeDeclaration? ":=" ExprSingle ("," "$" VarName TypeDeclaration? ":=" ExprSingle)* [45] WhereClause ::= "where" Expr [46] OrderByClause ::= (<"order" "by"> | <"stable" "order" "by">) OrderSpecList [47] OrderSpecList ::= OrderSpec ("," OrderSpec)* [48] OrderSpec ::= ExprSingle OrderModifier [49] OrderModifier ::= ("ascending" | "descending")? (<"empty" "greatest"> | <"empty" "least">)? ("collation" StringLiteral)?
      Overrides:
        `parseFLWORExpression` in class `ExpressionParser`
      Returns:
        the resulting subexpression
      Throws:
        `XPathException` - if any error is encountered

    - #### makeLetExpression

          protected LetExpression makeLetExpression()

      Make a LetExpression. This returns an ordinary LetExpression if tracing is off, and an EagerLetExpression if tracing is on. This is so that trace events occur in an order that the user can follow.
      Returns:
        the constructed "let" expression

    - #### checkForClauseAllowingEmpty

          protected void checkForClauseAllowingEmpty(ForClause clause)
                                              throws XPathException

      Check a ForClause for an "outer for"
      Parameters:
        `clause` - the clause to be checked
      Throws:
        `XPathException` - if invalid

    - #### parseCountClause

          protected void parseCountClause(List<Clause> clauseList)
                                   throws XPathException

      Parse a count clause. Not supported in 1.0; subclassed in the XQuery 3.0 parser
      Parameters:
        `clauseList` - the list of clauses for the expression, to which this clause will be added
      Throws:
        `XPathException` - if a static error is found

    - #### parseGroupByClause

          protected void parseGroupByClause(List<Clause> clauseList)
                                     throws XPathException

      Parse a Group By clause. Not supported in 1.0; subclassed in the XQuery 3.0 parser
      Parameters:
        `clauseList` - the list of clauses for the expression, to which this clause will be added
      Throws:
        `XPathException` - if a static error is found

    - #### parseWindowClause

          protected void parseWindowClause(List<Clause> clauseList)
                                    throws XPathException

      Parse a tumbling or sliding window clause. Not supported in 1.0; subclassed in the XQuery 3.0 parser
      Parameters:
        `clauseList` - the list of clauses for the expression, to which this clause will be added
      Throws:
        `XPathException` - if a static error is found

    - #### makeStringJoin

          public static Expression makeStringJoin(Expression exp,
                                  StaticContext env)

      Make a string-join expression that concatenates the string-values of items in a sequence with intervening spaces. This may be simplified later as a result of type-checking.
      Parameters:
        `exp` - the base expression, evaluating to a sequence
        `env` - the static context
      Returns:
        a call on string-join to create a string containing the representations of the items in the sequence separated by spaces.

    - #### readCollationName

          protected String readCollationName()
                                      throws XPathException

      Throws:
        `XPathException`

    - #### parseTypeswitchExpression

          protected Expression parseTypeswitchExpression()
                                                  throws XPathException

      Parse a Typeswitch Expression. This construct is XQuery-only. TypeswitchExpr ::= "typeswitch" "(" Expr ")" CaseClause+ "default" ("$" VarName)? "return" ExprSingle CaseClause ::= "case" ("$" VarName "as")? SequenceType "return" ExprSingle
      Overrides:
        `parseTypeswitchExpression` in class `ExpressionParser`
      Returns:
        the expression that results from the parsing
      Throws:
        `XPathException` - if parsing fails

    - #### parseValidateExpression

          protected Expression parseValidateExpression()
                                                throws XPathException

      Parse a Validate Expression. This construct is XQuery-only. The syntax allows: validate mode? { Expr } mode ::= "strict" | "lax"
      Overrides:
        `parseValidateExpression` in class `ExpressionParser`
      Returns:
        the parsed expression; except that this version of the method always throws an exception
      Throws:
        `XPathException` - if parsing fails

    - #### parseExtensionExpression

          protected Expression parseExtensionExpression()
                                                 throws XPathException

      Parse an Extension Expression. Syntax: "(#" QName arbitrary-text "#)")+ "{" expr? "}"
      Overrides:
        `parseExtensionExpression` in class `ExpressionParser`
      Returns:
        the parsed expression; except that this version of the method always throws an exception
      Throws:
        `XPathException` - if parsing fails

    - #### parseConstructor

          protected Expression parseConstructor()
                                         throws XPathException

      Parse a node constructor. This is allowed only in XQuery. This method handles both the XML-like "direct" constructors, and the XQuery-based "computed" constructors.
      Overrides:
        `parseConstructor` in class `ExpressionParser`
      Returns:
        an Expression for evaluating the parsed constructor
      Throws:
        `XPathException` - in the event of a syntax error.

    - #### parseTryCatchExpression

          protected Expression parseTryCatchExpression()
                                                throws XPathException

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

    - #### parseNamespaceConstructor

          protected Expression parseNamespaceConstructor(int offset)
                                                  throws XPathException

      Throws:
        `XPathException`

    - #### parseNamedNamespaceConstructor

          protected Expression parseNamedNamespaceConstructor(int offset)
                                                       throws XPathException

      Throws:
        `XPathException`

    - #### makeSimpleContent

          protected void makeSimpleContent(Expression content,
                               SimpleNodeConstructor inst,
                               int offset)
                                    throws XPathException

      Make the instructions for the children of a node with simple content (attribute, text, PI, etc)
      Parameters:
        `content` - the expression making up the simple content
        `inst` - the skeletal instruction for creating the node
        `offset` - the character position of this construct within the source query
      Throws:
        `XPathException` - if a static error is encountered

    - #### stringify

          public static Expression stringify(Expression exp,
                             boolean noNodeIfEmpty,
                             Configuration config)
                                      throws XPathException

      Convert an expression so it generates a space-separated sequence of strings
      Parameters:
        `exp` - the expression that calculates the content
        `noNodeIfEmpty` - if true, no node is produced when the value of the content expression is an empty sequence. If false, the effect of supplying an empty sequence is that a node is created whose string-value is a zero-length string. Set to true for text node constructors, false for other kinds of node.
        `config` - the Saxon configuration
      Returns:
        an expression that computes the content and converts the result to a character string
      Throws:
        `XPathException` - if parsing fails

    - #### makeStringLiteral

          protected Literal makeStringLiteral(String token)
                                       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
      Overrides:
        `makeStringLiteral` in class `ExpressionParser`
      Parameters:
        `token` - the string as written (or as returned by the tokenizer)
      Returns:
        The string value of the string literal, after dereferencing entity and character references
      Throws:
        `XPathException` - if parsing fails

    - #### URILiteral

          public String URILiteral(String in)
                            throws XPathException

      Handle a URI literal. This is whitespace-normalized as well as being unescaped
      Parameters:
        `in` - the string as written
      Returns:
        the URI after unescaping of entity and character references followed by whitespace normalization
      Throws:
        `XPathException` - if an error is found while unescaping the URI

    - #### normalizeEQName

          protected String normalizeEQName(String s)
                                    throws XPathException

      Convert a QName in expanded-name format "uri":local into Clark format
      Overrides:
        `normalizeEQName` in class `ExpressionParser`
      Parameters:
        `s` - the QName in expanded-name format
      Returns:
        the corresponding expanded name in Clark format
      Throws:
        `XPathException`

    - #### lookAhead

          protected void lookAhead()
                            throws XPathException

      Lookahead one token, catching any exception thrown by the tokenizer. This method is only called from the query parser when switching from character-at-a-time mode to tokenizing mode
      Throws:
        `XPathException` - if parsing fails

    - #### atStartOfRelativePath

          protected boolean atStartOfRelativePath()

      Description copied from class: `ExpressionParser`
      Test whether the current token is one that can start a RelativePathExpression
      Overrides:
        `atStartOfRelativePath` in class `ExpressionParser`
      Returns:
        the resulting subexpression

    - #### testPermittedAxis

          protected void testPermittedAxis(byte axis)
                                    throws XPathException

      Overrides:
        `testPermittedAxis` in class `ExpressionParser`
      Throws:
        `XPathException`

    - #### getLanguage

          protected String getLanguage()

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

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.