xtc.parser
Class ParserBase

java.lang.Object
  xtc.parser.ParserBase

public abstract class ParserBase
extends java.lang.Object

The base class for packrat parsers.

Version:

$Revision: 1.17 $

Author:

Robert Grimm

Field Summary

static int	FIRST_COLUMN The start index for columns.
static int	FIRST_LINE The start index for lines.
static int	INCR_SIZE The increment for the arrays storing the memoization table's columns.
static int	INIT_SIZE The default size for the arrays storing the memoization table's columns.
static java.lang.String	NEWLINE The platform's line separator.
protected Column[]	yyColumns The memoization table columns.
protected int	yyCount The number of characters consumed from the character stream.
protected char[]	yyData The characters consumed so far.
protected boolean	yyEOF The flag for whether the end-of-file has been reached.
protected java.io.Reader	yyReader The reader for the character stream to be parsed.

Constructor Summary

ParserBase(java.io.Reader reader, java.lang.String file)
Create a new parser base.

ParserBase(java.io.Reader reader, java.lang.String file, int size)
Create a new parser base.

Method Summary

protected <T> T	apply(Pair<Action<T>> actions, T seed) Apply the specified actions on the specified seed.
protected <T extends Locatable> T	apply(Pair<Action<T>> actions, T seed, int index) Apply the specified actions on the specified seed while also setting the results' locations.
protected static <T> T	cast(java.lang.Object o) Cast the specified object.
protected static <T> Pair<T>	cast(Pair<?> p) Cast the list starting at the specified pair.
protected int	character(int index) Parse a character at the specified index.
protected Column	column(int index) Get the column at the specified index.
protected java.lang.String	difference(int start, int end) Get the difference between the specified indices.
java.lang.String	format(ParseError error) Format the specified parse error.
boolean	isEOF(int index) Determine whether the specified index represents the end-of-file.
java.lang.String	lineAt(int index) Get the line at the specified index.
Location	location(int index) Get the location for the specified index.
protected abstract Column	newColumn() Create a new column.
protected java.lang.String	peek(int index) Get the next few characters from the specified index.
void	resetTo(int index) Reset this parser to the specified index.
protected void	setLocation(int index, java.lang.String file, int line, int column) Set the location for the specified index.
void	setLocation(Locatable locatable, int index) Set the location for the specified locatable object.
void	signal(ParseError error) Signal the specified parse error as a parse exception.
java.lang.Object	value(Result r) Extract the specified result's value.

Methods inherited from class java.lang.Object

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

Field Detail

NEWLINE

public static final java.lang.String NEWLINE

The platform's line separator.

FIRST_LINE

public static final int FIRST_LINE

The start index for lines. Note that this constant mirrors xtc.Constants#FIRST_LINE to avoid parsers depending on that class.

See Also:

Constant Field Values

FIRST_COLUMN

public static final int FIRST_COLUMN

The start index for columns. Note that this constant mirrors xtc.Constants#FIRST_COLUMN to avoid parsers depending on that class.

See Also:

Constant Field Values

INIT_SIZE

public static final int INIT_SIZE

The default size for the arrays storing the memoization table's columns.

See Also:

Constant Field Values

INCR_SIZE

public static final int INCR_SIZE

The increment for the arrays storing the memoization table's columns.

See Also:

Constant Field Values

yyReader

protected java.io.Reader yyReader

The reader for the character stream to be parsed.

yyCount

protected int yyCount

The number of characters consumed from the character stream.

yyEOF

protected boolean yyEOF

The flag for whether the end-of-file has been reached.

yyData

protected char[] yyData

The characters consumed so far.

yyColumns

protected Column[] yyColumns

The memoization table columns.

Constructor Detail

ParserBase

public ParserBase(java.io.Reader reader,
                  java.lang.String file)

Create a new parser base.

Parameters:

reader - The reader for the character stream to be parsed.

file - The name of the file backing the character stream.

Throws:

java.lang.NullPointerException - Signals a null file name.

ParserBase

public ParserBase(java.io.Reader reader,
                  java.lang.String file,
                  int size)

Create a new parser base.

Parameters:

reader - The reader for the character stream to be parsed.

file - The name of the file backing the character stream.

size - The length of the character stream.

Throws:

java.lang.NullPointerException - Signals a null file name.

java.lang.IllegalArgumentException - Signals a negative file size.

Method Detail

resetTo

public final void resetTo(int index)

Reset this parser to the specified index. This method discards the input and all memoized intermediate results up to and excluding the specified index. The index should be determined by accessing Result.index from a previous, successful parse (i.e., the result must be a semantic value).

Parameters:

index - The index.

Throws:

java.lang.IndexOutOfBoundsException - Signals an invalid index.

newColumn

protected abstract Column newColumn()

Create a new column. A concrete implementation of this method should simply return a new memoization table column.

Returns:

A new memoization table column.

column

protected final Column column(int index)

Get the column at the specified index. If the column at the specified index has not been created yet, it is created as a side-effect of calling this method.

Parameters:

index - The index.

Returns:

The corresponding column.

Throws:

java.lang.IndexOutOfBoundsException - Signals an invalid index.

character

protected final int character(int index)
                       throws java.io.IOException

Parse a character at the specified index.

Parameters:

index - The index.

Returns:

The character or -1 if the end-of-file has been reached.

Throws:

java.io.IOException - Signals an exceptional condition while accessing the character stream.

difference

protected final java.lang.String difference(int start,
                                            int end)

Get the difference between the specified indices.

Parameters:

start - The start index.

end - The end index.

Returns:

The difference as a string.

isEOF

public final boolean isEOF(int index)

Determine whether the specified index represents the end-of-file.

Parameters:

index - The index.

Returns:

true if the specified index represents EOF.

lineAt

public final java.lang.String lineAt(int index)
                              throws java.io.IOException

Get the line at the specified index.

Parameters:

index - The index.

Returns:

The corresponding line, without any line terminating characters.

Throws:

java.lang.IndexOutOfBoundsException - Signals an invalid index.

java.io.IOException - Signals an I/O error.

location

public final Location location(int index)

Get the location for the specified index.

Parameters:

index - The index.

Returns:

The corresponding location.

setLocation

protected final void setLocation(int index,
                                 java.lang.String file,
                                 int line,
                                 int column)

Set the location for the specified index. This method updates the internal location based on, for example, a line marker recognized by the parser.

This method must be called before any nodes are created for positions at or beyond the specified index — unless the specified file, line, and column are the same as the internal location for the index. The line number may be one less than the start index for lines (FIRST_LINE), to account for a line marker being present in the input. The column number is generally be expected to be the start index for columns (FIRST_COLUMN), again accounting for a line marker being present in the input.

Parameters:

index - The index.

file - The new file name.

line - The new line number.

column - The new column number.

Throws:

java.lang.NullPointerException - Signals a null file name.

java.lang.IllegalArgumentException - Signals an invalid line or column number.

java.lang.IndexOutOfBoundsException - Signals an invalid index.

java.lang.IllegalStateException - Signals that the index comes at or before any memoized results.

setLocation

public final void setLocation(Locatable locatable,
                              int index)

Set the location for the specified locatable object. This method is equivalent to:

   if ((null != locatable) && (! locatable.hasLocation())) {
     locatable.setLocation(location(index));
   }
 

Parameters:

locatable - The locatable object.

index - The index.

apply

protected final <T> T apply(Pair<Action<T>> actions,
                            T seed)

Apply the specified actions on the specified seed. This method applies all actions on the specified list, using the result of the previous action as the argument to the next action. The argument to the first action is the specified seed. If the specified list is empty, this method simply returns the specified seed.

Parameters:

actions - The actions to apply.

seed - The initial argument.

Returns:

The result of applying the actions.

apply

protected final <T extends Locatable> T apply(Pair<Action<T>> actions,
                                              T seed,
                                              int index)

Apply the specified actions on the specified seed while also setting the results' locations. This method applies all actions on the specified list, using the result of the previous action as the argument to the next action. For the result of each application, it also sets the location. The argument to the first action is the specified seed. If the specified list is empty, this method simply returns the specified seed.

Parameters:

actions - The actions to apply.

seed - The initial argument.

index - The index representing the current parser location.

Returns:

The result of applying the actions.

format

public final java.lang.String format(ParseError error)
                              throws java.io.IOException

Format the specified parse error. The specified error must have been created by this parser.

Parameters:

error - The error.

Returns:

The corresponding error message.

Throws:

java.io.IOException - Signals an I/O error while creating the error message.

signal

public final void signal(ParseError error)
                  throws ParseException,
                         java.io.IOException

Signal the specified parse error as a parse exception. The specified error must have been created by this parser.

Parameters:

error - The parse error.

Throws:

ParseException - Signals the error.

java.io.IOException - Signals an I/O error while creating the exception's detail message.

value

public final java.lang.Object value(Result r)
                             throws ParseException,
                                    java.io.IOException

Extract the specified result's value. If the result is a SemanticValue, this method returns the actual value; if it is a ParseError, it signals a parse exception with the corresponding message. The specified result must have been created by this parser.

Parameters:

r - The result.

Returns:

The corresponding value.

Throws:

ParseException - Signals that the result represents a parse error.

java.io.IOException - Signals an I/O error while creating the parse error's detail message.

peek

protected final java.lang.String peek(int index)

Get the next few characters from the specified index.

Parameters:

index - The index.

Returns:

The next few characters.

cast

protected static final <T> T cast(java.lang.Object o)

Cast the specified object. This method is used to avoid spurious compiler warnings for parsers utilizing generic types.

Parameters:

o - The object.

Returns:

The cast object.

cast

protected static final <T> Pair<T> cast(Pair<?> p)

Cast the list starting at the specified pair. This method is used to avoid spurious compiler warnings for parsers utilizing generic types.

Parameters:

p - The list.

Returns:

The cast list.