XPathCompiler

java.lang.Object
- uk.ac.sheffield.jast.xpath.XPathCompiler

```
public class XPathCompiler
extends java.lang.Object
```
XPathCompiler is a parser that compiles an XPath query pattern into rules. When a new XPath object is created, it uses an XPathCompiler to parse the String supplied as the query-pattern. If the XPathCompiler accepts the pattern String, it compiles this into a list of XPathRules, each representing one step along the search path. The compiled list of rules is installed in the XPath object. If the query pattern is not accepted, XPathCompiler raises a SyntaxError.
The programmer does not have to construct an XPathCompiler, since this is handled internally by XPath, and the compiler is released when the XPath no longer has need for it. XPathCompiler uses a StringReader to scan the XPath query pattern one character at a time. It parses the query pattern in segments, creating one pattern-matching XPathRule for each segment. Later, when asked to match() itself against some XML Content, the XPath object will invoke these rules.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields
Modifier and Type	Field and Description
`private int`	`lastChar` The last character read from the XPath query pattern, as an integer.
`private java.io.StringReader`	`scanner` The StringReader that reads characters one at a time from the XPath query pattern.
`private java.util.LinkedList<XPathRule>`	`xpathRules` The compiled XPath pattern, as a list of XPathRule objects.
`private java.lang.String`	`xpathString` The original XPath query pattern, as a String.

Constructor Summary

Constructors
Constructor and Description

XPathCompiler()
Creates an XPathCompiler.

Constructors
Constructor and Description
`XPathCompiler()` Creates an XPathCompiler.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`private void`	`addFilter(Filter filter)` Adds an extra restricting Filter to the last XPathRule that was compiled.
`private void`	`addRule(XPathRule rule)` Adds an extra XPathRule rule to the current list of XPathRules, representing the next segment of the XPath.
`private void`	`compileAttribute()` Compiles an attribute-axis pattern.
`private void`	`compileChildOrContent()` Compiles a child-axis pattern for a child element or some other kind of content.
`private void`	`compileContent(java.lang.String selector)` Compiles a child-axis pattern for general kinds of content.
`private void`	`compileDescendantsOrSelf()` Compiles a descendants-or-self-axis pattern.
`private void`	`compileNestedXPath(java.lang.String pattern)` Compiles a nested XPath query pattern embedded in an XPath predicate expression.
`private void`	`compileNextSegment()` Compiles the next segment of the XPath query pattern.
`private void`	`compileParentOrSelf()` Compiles a parent-axis or self-axis pattern.
`void`	`compilePattern(java.lang.String pattern)` Compiles a fresh XPath query pattern, storing the result as a list of XPathRules.
`private void`	`compilePosition(java.lang.String selector)` Compiles a position predicate to select the element at an index.
`private void`	`compilePredicate()` Compiles an XPath predicate expression in [...] brackets.
`java.lang.String`	`getPattern()` Returns the last XPath query pattern submitted to this compiler.
`java.util.List<XPathRule>`	`getRules()` Returns the last list of XPathRules compiled by this compiler.
`private int`	`parseDigitToken()` Parses a positive or negative digit token.
`private java.lang.String`	`parseNameToken()` Parses an XML name token.
`private java.lang.String`	`parseNestedPattern(java.lang.String token)` Extracts a nested query pattern that was enclosed in "[...]" brackets.
`private java.lang.String`	`parseOperatorToken()` Parses an operator symbol, one of six supported comparison operators.
`private java.lang.String`	`parseValueString()` Parses a value expression.
`private void`	`skipSpace()` Skips whitespace characters.
`private void`	`syntaxError(java.lang.String message)` Reports a syntax error, when badly-formed XPath syntax is detected.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - xpathString
```
private java.lang.String xpathString
```
    The original XPath query pattern, as a String.
  - xpathRules
```
private java.util.LinkedList<XPathRule> xpathRules
```
    The compiled XPath pattern, as a list of XPathRule objects.
    
    See Also:
    
    XPathRule.
  - scanner
```
private java.io.StringReader scanner
```
    The StringReader that reads characters one at a time from the XPath query pattern.
  - lastChar
```
private int lastChar
```
    The last character read from the XPath query pattern, as an integer.
- Constructor Detail
  - XPathCompiler
```
public XPathCompiler()
```
    Creates an XPathCompiler. Initialises the query pattern to an empty String and the compiled rules to an empty list, as a purely defensive measure.
- Method Detail
  - getPattern
```
public java.lang.String getPattern()
```
    Returns the last XPath query pattern submitted to this compiler.
    
    Returns:
    
    the last query pattern.
  - getRules
```
public java.util.List<XPathRule> getRules()
```
    Returns the last list of XPathRules compiled by this compiler.
    
    Returns:
    
    the last list of XPathRules.
  - compilePattern
```
public void compilePattern(java.lang.String pattern)
                    throws SyntaxError
```
    Compiles a fresh XPath query pattern, storing the result as a list of XPathRules. Assumes that the query pattern is a non-null and non-empty String (which is checked in XPath before invoking this method).
    
    Parameters:
    
    pattern - an XPath query pattern.
    
    Throws:
    
    SyntaxError - if the XPath query pattern syntax is faulty.
  - syntaxError
```
private void syntaxError(java.lang.String message)
                  throws SyntaxError
```
    Reports a syntax error, when badly-formed XPath syntax is detected. If the end of input has not been reached, prepends further diagnostic information about the current character and the XPath context to the error message.
    
    Parameters:
    
    message - the error message.
    
    Throws:
    
    SyntaxError - always.
  - addFilter
```
private void addFilter(Filter filter)
```
    Adds an extra restricting Filter to the last XPathRule that was compiled. Should only be called if there is at least one XPathRule in the list; otherwise takes no action.
    
    Parameters:
    
    filter - the Filter.
  - addRule
```
private void addRule(XPathRule rule)
```
    Adds an extra XPathRule rule to the current list of XPathRules, representing the next segment of the XPath. May choose to optimise the number of rule-steps. If there is an existing XPathRule, then if the added rule is a SelfAxisRule, this can be merged with the previous rule. If the existing rule is a SubtreeAxisRule and the added rule is a ContentAxisRule, likewise the added rule can be merged with the previous rule.
    
    Parameters:
    
    rule - the XPathRule to add.
  - compileNextSegment
```
private void compileNextSegment()
                         throws SyntaxError,
                                java.io.IOException
```
    Compiles the next segment of the XPath query pattern. Assumes that any path separator has just been skipped. The segment may begin with a '/' indicating a descendants-or-self-axis, or with a '.' indicating either a self-axis, or parent-axis, or with a '@' indicating an attribute-axis step. Otherwise, it begins with an alpha-character indicating either a child-axis, or a content-axis step.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - compileDescendantsOrSelf
```
private void compileDescendantsOrSelf()
```
    Compiles a descendants-or-self-axis pattern. Adds a SubtreeAxisRule that will select the current node and every node underneath it. This method raises no exceptions, since it does not alter the scanner input stream. The second forward-slash in "//" is not skipped, but instead is treated as a path separator.
  - compileParentOrSelf
```
private void compileParentOrSelf()
                          throws SyntaxError,
                                 java.io.IOException
```
    Compiles a parent-axis or self-axis pattern. Skips the first '.' indicator and if the next character is '.', adds a ParentAxisRule; otherwise adds a SelfAxisRule (matching the current context node). Checks for further predicate restrictions on the SelfAxisRule or ParentAxisRule.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - compileAttribute
```
private void compileAttribute()
                       throws SyntaxError,
                              java.io.IOException
```
    Compiles an attribute-axis pattern. Skips the '@' attribute indicator and parses the attribute's name token. If this is the wildcard '*', adds an AttributeAxisRule that selects any attribute, otherwise adds an AttributeAxisRule with a NameFilter that selects only attributes with a given name token. Checks for further predicate restrictions on the AttributeAxisRule.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - compileChildOrContent
```
private void compileChildOrContent()
                            throws SyntaxError,
                                   java.io.IOException
```
    Compiles a child-axis pattern for a child element or some other kind of content. Parses the next name token. If this is followed by '(', indicating a content-selector, adds a ChildAxisRule selecting the specified content. Otherwise, adds a ChildAxisRule selecting a child element. If the name token is the wildcard '*', the rule will select any child element. Otherwise, adds a NameFilter that only selects children with the given name. Checks for further restrictions on the ChildAxisRule.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - compileContent
```
private void compileContent(java.lang.String selector)
                     throws SyntaxError,
                            java.io.IOException
```
    Compiles a child-axis pattern for general kinds of content. Parses a general selector-function. Supported functions include: "node()" selecting any node, "text()" selecting either text or data, "comment()" selecting a comment and "processing-instruction()" selecting a processing instruction. Anything else raises an exception.
    
    Parameters:
    
    selector - the name of the selector-function.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - compilePosition
```
private void compilePosition(java.lang.String selector)
                      throws SyntaxError,
                             java.io.IOException
```
    Compiles a position predicate to select the element at an index. If no selector is supplied, parses an integer and adds an IndexFilter2 to select at this position. If the selector is "last" or "position", checks that function parentheses "()" follow. If the selector is "last", adds an IndexFilter2 to select a the last position; but if the selector is followed by a negative integer, adds an IndexFilter2 to select backwards from last position. If the selector is "position", parses a comparison operator and a positive index and adds a PositionFilter to select all elements whose index satisfies the position constraint.
    
    Parameters:
    
    selector - a position-selector.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - compilePredicate
```
private void compilePredicate()
                       throws SyntaxError,
                              java.io.IOException
```
    Compiles an XPath predicate expression in [...] brackets. This could be a simple index, or a position selector; or it could be a nested XPath query pattern, or even a compound predicate consisting of two patterns joined with "and" or "or". We assume that selectors cannot be compounded, but query patterns may be. Skips the opening '[' and then adds a suitable IndexFilter2, PositionFilter, XPathFilter or compound AndFilter or OrFilter wrapping XPathFilters. Checks that a closing ']' is present before skipping it.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - compileNestedXPath
```
private void compileNestedXPath(java.lang.String pattern)
```
    Compiles a nested XPath query pattern embedded in an XPath predicate expression. The query pattern may be simple, or may be a compound, consisting of two patterns joined by "and" or "or". If the pattern is simple, adds an XPathFilter. If the pattern is compound, splits the pattern and adds either an AndFilter, or an OrFilter containing two XPathFilters.
    
    Parameters:
    
    pattern - the nested query pattern.
  - parseNestedPattern
```
private java.lang.String parseNestedPattern(java.lang.String token)
                                     throws SyntaxError,
                                            java.io.IOException
```
    Extracts a nested query pattern that was enclosed in "[...]" brackets. The opening '[' bracket has been skipped; and the first name token has optionally been read. Stores this, and reads further characters into a buffer until the corresponding ']' bracket is encountered. Returns the contained text, without the enclosing brackets.
    
    Parameters:
    
    token - the first token of the nested pattern.
    
    Returns:
    
    a nested query pattern.
    
    Throws:
    
    SyntaxError - if the XPath syntax is faulty.
    
    java.io.IOException - if the String scanner fails.
  - parseOperatorToken
```
private java.lang.String parseOperatorToken()
                                     throws SyntaxError,
                                            java.io.IOException
```
    Parses an operator symbol, one of six supported comparison operators. The operator symbol must be one of the six standard equality and inequality relations. It may be surrounded by whitespace.
    
    Returns:
    
    an operator symbol as a String.
    
    Throws:
    
    SyntaxError - if the operator token is malformed.
    
    java.io.IOException - if the String scanner fails.
  - parseNameToken
```
private java.lang.String parseNameToken()
                                 throws SyntaxError,
                                        java.io.IOException
```
    Parses an XML name token. A name token is a sequence of characters starting with a letter or underscore, and continuing with any mix of letter, digit, hyphen, underscore or period characters. A name token may also contain a namespace prefix, separated from the main name by a colon. A name token is parsed by accumulating legal constituent characters until a non-legal character is encountered. If this is a legitimate terminator, the name token is returned; otherwise a syntax error is reported.
    
    Returns:
    
    a name token as a String.
    
    Throws:
    
    SyntaxError - if the name token is malformed.
    
    java.io.IOException - if the String scanner fails.
  - parseDigitToken
```
private int parseDigitToken()
                     throws SyntaxError,
                            java.io.IOException
```
    Parses a positive or negative digit token. Parses an optional minus sign, followed by a sequence of digits, until no more digits remain.
    
    Returns:
    
    an integer value.
    
    Throws:
    
    SyntaxError - if the digit token is malformed.
    
    java.io.IOException - if the String scanner fails.
  - parseValueString
```
private java.lang.String parseValueString()
                                   throws SyntaxError,
                                          java.io.IOException
```
    Parses a value expression. The expression is a literal pattern value to match, optionally enclosed in single or double quotes (according to W3C practice). W3C practice seems to allow integer values unquoted, but puts matching quotes around other string tokens! So, we detect the quoteChar, if any exists, and seek to match up quotes by the end of the value expression. If there are no quotes, stop at the first space or end of constraint.
    
    Returns:
    
    the value-string.
    
    Throws:
    
    SyntaxError - if the operator token is malformed.
    
    java.io.IOException - if the String scanner fails.
  - skipSpace
```
private void skipSpace()
                throws java.io.IOException
```
    Skips whitespace characters. Advances the read-point to the next non-whitespace character.
    
    Throws:
    
    java.io.IOException - if the String scanner fails.

Class XPathCompiler

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

xpathString

xpathRules

scanner

lastChar

Constructor Detail

XPathCompiler

Method Detail

getPattern

getRules

compilePattern

syntaxError

addFilter

addRule

compileNextSegment

compileDescendantsOrSelf

compileParentOrSelf

compileAttribute

compileChildOrContent

compileContent

compilePosition

compilePredicate

compileNestedXPath

parseNestedPattern

parseOperatorToken

parseNameToken

parseDigitToken

parseValueString

skipSpace