com.google.gdata.util.parser

Class Parser<T>

java.lang.Object

com.google.gdata.util.parser.Parser<T>

Type Parameters:

T -

Direct Known Subclasses:

Action, Alternative, Chset, Difference, Intersection, Repeat, Rule, Sequence, Strcaselit, Strlit

public abstract class Parser<T>
extends Object

The com.google.gdata.util.parser package provides a framework for creating recursive descent parsers. A fairly straightforward transformation exists between EBNF (extended Backus-Naur form) grammars and code used to construct a parser using this framework that will match the grammar. The intention of this package is to obviate the need to create small mini-parsers for tasks that don't feel large enough for a standard compiler-compiler (like JavaCC) but still need more formalism than simple string tokenization. The basic approach this framework takes to parsing is to define several types of leaf parsers which know how to parse a particular type of object (character set, string literal, etc.) and to then combine them together in interesting ways. For example, a parser for a comma separated list of integers would look like: Parser Chset.DIGIT.plus().list(new Chset(',')); The EBNF this represents is: sent: [0-9]+ ("," [0-9]+)* The Parser.list() functionality is sometimes represented as the '%' operator in EBNF extensions. It performs the transformation: a % b --> a (b a)* The leaf parsers that are currently defined are:

See Also:

Chset, Strlit, The operators which combine 1 or 2 parsers together are:, Action, Alternative, Difference, Intersection, Repeat, Rule, In general, it isn't necessary to create an operator-type parser directly as an appropriate member function usually exists in Parser for creating them. Note that these are purely convenience routines. In general, the parsers are greedy. For example, the Sequence parser will match as much as possible with the left sub-parser before trying the right sub-parser. This behavior can normally be avoided by using a recursive grammar. Consider the following grammar: token: foo* bar foo: [a-z]+ bar: foo [0-9]+ This grammar will fail to parse the string "aa0" because the 'foo*' rule will consume all of the letters and not leave one left for the 'bar' rule. An alternate definition of 'token' can prevent this behavior: token: (foo token) | bar The parsers created by this parser framework use infinite lookahead. In extreme cases, a parser can be constructed which scans over the parse buffer many times trying to find a match. In practice, this doesn't happen very often.

Field Summary

Fields

Modifier and Type	Field and Description
static int	NO_MATCH

Constructor Summary

Constructors

Constructor and Description
Parser()

Method Summary

Methods

Modifier and Type	Method and Description
<U extends T> Parser<U>	action(Callback<U> callback) Creates a Action that will fire and call Callback.handle whenever this matches.
static <T> Parser<T>	alternative(Parser<? super T> left, Parser<? super T> right) Creates an Alternative parser from the left and right sub-parsers.
static <T> Parser<T>	difference(Parser<? super T> left, Parser<? super T> right) Creates a Difference parser from the left and right sub-parsers.
static <T> Parser<T>	intersection(Parser<? super T> left, Parser<? super T> right) Creates an Intersection parser from the left and right sub-parsers.
Parser<T>	list(Parser<? super T> sep) Creates a Parser that matches a sequence of this parsers separated by sep parsers.
Parser<T>	optional() Creates a Repeat parser that matches this either 0 or 1 times.
abstract int	parse(char[] buf, int start, int end, T udata) The parse interface that subclasses must implement.
int	parse(char[] buf, T udata) Convenience routine to parse a character array.
int	parse(Reader reader, T udata) Convenience routine to parse a java.io.Reader.
int	parse(String str, T udata) Convenience routine to parse a string.
Parser<T>	plus() Creates a Repeat parser that matches this 1 or more times.
Parser<T>	repeat(int count) Creates a Repeat parser that matches this exactly count times.
Parser<T>	repeat(int min, int max) Creates a Repeat parser that matches this at least min times and not mroe than max times.
static <T> Parser<T>	sequence(Parser<? super T> left, Parser<? super T> right) Creates a Sequence parser from the left and right sub-parsers.
static <T> Parser<T>	sequence(Parser<? super T> one, Parser<? super T> two, Parser<? super T> three) Creates a Sequence parser from parsers one, two and three sub-parsers.
static <T> Parser<T>	sequence(Parser<? super T> one, Parser<? super T> two, Parser<? super T> three, Parser<? super T> four) Creates a sequence of four parsers.
static <T> Parser<T>	sequence(Parser<? super T> one, Parser<? super T> two, Parser<? super T> three, Parser<? super T> four, Parser<? super T> five) Creates a sequence of five parsers.
Parser<T>	star() Creates a Repeat parser that matches this 0 or more times.

Methods inherited from class java.lang.Object

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

Field Detail

NO_MATCH

public static final int NO_MATCH

See Also:

Constant Field Values

Constructor Detail

Parser

public Parser()

Method Detail

parse

public abstract int parse(char[] buf,
        int start,
        int end,
        T udata)

The parse interface that subclasses must implement.

Parameters:

buf - The character array to match against.

start - The start offset of data within the character array to match against.

end - The end offset of data within the character array to match against.

udata - User defined object that is passed to Callback.handle when an Action fires.

parse

public final int parse(char[] buf,
        T udata)

Convenience routine to parse a character array.

parse

public final int parse(String str,
        T udata)

Convenience routine to parse a string.

parse

public final int parse(Reader reader,
        T udata)

Convenience routine to parse a java.io.Reader.

repeat

public final Parser<T> repeat(int count)

Creates a Repeat parser that matches this exactly count times. this{count}

Parameters:

count - The number of times this must match in sequence.

repeat

public final Parser<T> repeat(int min,
               int max)

Creates a Repeat parser that matches this at least min times and not mroe than max times. this{min,max}

Parameters:

min - The minimum number of times this must match in sequence.

max - The maximum number of times this is allowed to match in sequence.

star

public final Parser<T> star()

Creates a Repeat parser that matches this 0 or more times. this*

plus

public final Parser<T> plus()

Creates a Repeat parser that matches this 1 or more times. this+

optional

public final Parser<T> optional()

Creates a Repeat parser that matches this either 0 or 1 times. this?

list

public final Parser<T> list(Parser<? super T> sep)

Creates a Parser that matches a sequence of this parsers separated by sep parsers. These sequences occur often: space separated words, comma separated words, etc.

Parameters:

sep - The parser which separates instances of this.

action

public final <U extends T> Parser<U> action(Callback<U> callback)

Creates a Action that will fire and call Callback.handle whenever this matches.

Parameters:

callback - The Callback to call when this matches.

alternative

public static <T> Parser<T> alternative(Parser<? super T> left,
                        Parser<? super T> right)

Creates an Alternative parser from the left and right sub-parsers. left | right

intersection

public static <T> Parser<T> intersection(Parser<? super T> left,
                         Parser<? super T> right)

Creates an Intersection parser from the left and right sub-parsers. left & right

difference

public static <T> Parser<T> difference(Parser<? super T> left,
                       Parser<? super T> right)

Creates a Difference parser from the left and right sub-parsers. left - right

sequence

public static <T> Parser<T> sequence(Parser<? super T> left,
                     Parser<? super T> right)

Creates a Sequence parser from the left and right sub-parsers. left right

sequence

public static <T> Parser<T> sequence(Parser<? super T> one,
                     Parser<? super T> two,
                     Parser<? super T> three)

Creates a Sequence parser from parsers one, two and three sub-parsers. Equivalent to calling Parser.sequence(one, Parser.sequence(two, three)).

sequence

public static <T> Parser<T> sequence(Parser<? super T> one,
                     Parser<? super T> two,
                     Parser<? super T> three,
                     Parser<? super T> four)

Creates a sequence of four parsers.

See Also:

sequence(Parser,Parser,Parser)

sequence

public static <T> Parser<T> sequence(Parser<? super T> one,
                     Parser<? super T> two,
                     Parser<? super T> three,
                     Parser<? super T> four,
                     Parser<? super T> five)

Creates a sequence of five parsers.

See Also:

sequence(Parser,Parser,Parser)