xtc.parser
Class Annotator

java.lang.Object
  xtc.tree.Visitor
      xtc.parser.Annotator

public class Annotator
extends Visitor

Visitor to inject source code annotations into a grammar.

This visitor distinguishes between bindable elements, i.e., elements that would contribute to the value of a generic production, and valuable element, i.e., elements that can be rewritten to have a semantic value. The latter include voided elements and references to void productions that consume the input.

For directly left-recursive alternatives in generic productions, this visitor may annotate the last sequence with the Properties.FORMATTING property, indicating valuable elements that need to be captured in the promise generated by DirectLeftRecurser.

This visitor assumes that the entire grammar is contained in a single module, that the grammar has been tokenized, and that productions that may consume the input have been marked.

Version:

$Revision: 1.33 $

Author:

Robert Grimm

See Also:

Tokenizer, Analyzer.consumesInput(Element)

Nested Class Summary

class	Annotator.Detector A visitor to detect whether productions need to be rewritten.
static class	Annotator.Index A mutable boxed integer.
static class	Annotator.IndexPair A pair of indices.
class	Annotator.Rewriter A visitor to rewrite productions.

Field Summary

protected java.util.List<java.util.List<Binding>>	after The list of bindings for valuable elements after the regular, bindable value, organized as a stack of copies.
protected Analyzer	analyzer The analyzer.
protected java.util.List<java.util.List<Binding>>	before The list of bindings for valuable elements before the regular, bindable value, organized as a stack of copies.
protected java.util.List<Annotator.Index>	elementIdx The index of the regular, bindable value, organized as a stack of copies.
protected boolean	isGeneric The flag for whether the current production is generic.
protected boolean	isList The flag for whether the current production is list-valued.
protected boolean	isRecursive The flag for whether the current production or sequence is directly left-recursive.
protected boolean	isTopLevel The flag for whether the current choice is top-level.
static java.lang.String	MARKER The marker for synthetic variables.
protected Runtime	runtime The runtime.
protected java.util.List<Annotator.Index>	sequenceIdx The index of the sequence with the regular, bindable value, organized as a stack of copies.
protected java.util.List<Sequence>	sequences The elements as a list of sequences.
protected int	toProcessIdx The index of the next sequence to process.

Constructor Summary

Annotator(Runtime runtime, Analyzer analyzer)
Create a new annotator.

Method Summary

protected java.util.List<Binding>	after() Get the current list of bindings after the regular value.
protected void	annotate() Process all elements in the current list of sequences.
protected java.util.List<Binding>	before() Get the current list of bindings before the regular value.
protected Binding	bindAndVoid() Bind and void the current regular, bindable element.
protected VoidedElement	bindAndVoid(Element e) Bind and void the specified element.
protected Annotator.Index	elementIndex() Get the current element index of the regular value.
protected boolean	hasBindable() Determine whether a bindable element has been processed.
protected boolean	hasValuable() Determine whether any valuable elements have been processed.
protected boolean	isBoundAndVoided(Element e) Determine whether the specified element already is bound and voided.
static boolean	isGeneric(FullProduction p) Determine whether the specified production effectively is generic.
static boolean	isList(Type type) Determine whether the specified type is a list type that can be processed by this visitor.
protected boolean	isParseTreeNode(Element e) Determine whether the specified element is a possibly bound or voided parse tree node.
static boolean	isSingleRepetition(FullProduction p) Determine whether the specified production recognizes only a single repetition.
protected boolean	isValuable(Element e) Determine whether the specified element is valuable.
static boolean	isValuable(FullProduction p) Determine whether the specified production can have a semantic value.
protected void	pop() Pop the top elements from the state for tracking bindable and valuable elements.
protected void	push() Push a copy of the state for tracking bindable and valuable elements.
protected void	recurse(Element e) Recursively process the specified element.
protected void	reset() Reset the current state for tracking bindable and valuable elements.
protected Annotator.Index	sequenceIndex() Get the current sequence index of the regular value.
void	visit(FullProduction p) Visit the specified production.
void	visit(Module m) Visit the specified grammar.
void	visit(OrderedChoice c) Visit the specified choice.
void	visit(Sequence s) Visit the specified sequence.

Methods inherited from class xtc.tree.Visitor

dispatch, equals, hashCode, iterate, map, mapInPlace, unableToVisit, visit

Methods inherited from class java.lang.Object

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

Field Detail

MARKER

public static final java.lang.String MARKER

The marker for synthetic variables.

See Also:

Constant Field Values

runtime

protected final Runtime runtime

The runtime.

analyzer

protected final Analyzer analyzer

The analyzer.

isGeneric

protected boolean isGeneric

The flag for whether the current production is generic.

isList

protected boolean isList

The flag for whether the current production is list-valued.

isRecursive

protected boolean isRecursive

The flag for whether the current production or sequence is directly left-recursive.

isTopLevel

protected boolean isTopLevel

The flag for whether the current choice is top-level.

toProcessIdx

protected int toProcessIdx

The index of the next sequence to process. The stacks capturing the state for tracking bindable and valuable must have as many elements as indicated by this index.

sequences

protected java.util.List<Sequence> sequences

The elements as a list of sequences.

before

protected java.util.List<java.util.List<Binding>> before

The list of bindings for valuable elements before the regular, bindable value, organized as a stack of copies.

See Also:

toProcessIdx

sequenceIdx

protected java.util.List<Annotator.Index> sequenceIdx

The index of the sequence with the regular, bindable value, organized as a stack of copies. A value of -1 indicates no bindable value.

See Also:

toProcessIdx

elementIdx

protected java.util.List<Annotator.Index> elementIdx

The index of the regular, bindable value, organized as a stack of copies. A value of -1 indicates no bindable value.

See Also:

toProcessIdx

after

protected java.util.List<java.util.List<Binding>> after

The list of bindings for valuable elements after the regular, bindable value, organized as a stack of copies.

See Also:

toProcessIdx

Constructor Detail

Annotator

public Annotator(Runtime runtime,
                 Analyzer analyzer)

Create a new annotator.

Parameters:

runtime - The runtime.

analyzer - The analyzer utility.

Method Detail

push

protected void push()

Push a copy of the state for tracking bindable and valuable elements. This method pushes copies of the top elemens of the tracking state onto the respective stacks. If the stacks are empty, it initializes the lists of bindings with empty lists and the indices with -1.

pop

protected void pop()

Pop the top elements from the state for tracking bindable and valuable elements.

reset

protected void reset()

Reset the current state for tracking bindable and valuable elements. This method replaces the current lists of bindings with new, empty lists and sets the current indices to -1.

before

protected java.util.List<Binding> before()

Get the current list of bindings before the regular value.

Returns:

The current list of bindings.

sequenceIndex

protected Annotator.Index sequenceIndex()

Get the current sequence index of the regular value.

Returns:

The current sequence index.

elementIndex

protected Annotator.Index elementIndex()

Get the current element index of the regular value.

Returns:

The current element index.

after

protected java.util.List<Binding> after()

Get the current list of bindings after the regular value.

Returns:

The current list of bindings.

isValuable

protected boolean isValuable(Element e)

Determine whether the specified element is valuable. This method returns true if the specified element has a semantic value or can be rewritten to yield a semantic value. Rewriting includes eliminating any voided element or converting a void production into a production returning a semantic value.

Parameters:

e - The element.

Returns:

true if the specified element is valuable.

isParseTreeNode

protected boolean isParseTreeNode(Element e)

Determine whether the specified element is a possibly bound or voided parse tree node.

Parameters:

e - The element.

Returns:

true if the specified element is a parse tree node.

hasBindable

protected boolean hasBindable()

Determine whether a bindable element has been processed.

Returns:

true if a bindable element has been processed.

See Also:

Analyzer.isBindable(Element)

hasValuable

protected boolean hasValuable()

Determine whether any valuable elements have been processed.

Returns:

true if any valuable elements have been processed.

See Also:

isValuable(Element)

isBoundAndVoided

protected boolean isBoundAndVoided(Element e)

Determine whether the specified element already is bound and voided.

Parameters:

e - The element.

Returns:

true if the specified element already is bound and voided.

bindAndVoid

protected VoidedElement bindAndVoid(Element e)

Bind and void the specified element. The specified element must be valuable, i.e., can be rewritten to yield a semantic value.

Parameters:

e - The element.

Returns:

The voided, bound element.

See Also:

isValuable(Element)

bindAndVoid

protected Binding bindAndVoid()

Bind and void the current regular, bindable element.

Returns:

The binding.

annotate

protected void annotate()

Process all elements in the current list of sequences.

recurse

protected void recurse(Element e)

Recursively process the specified element.

Parameters:

e - The element.

visit

public void visit(Module m)

Visit the specified grammar.

visit

public void visit(FullProduction p)

Visit the specified production.

visit

public void visit(OrderedChoice c)

Visit the specified choice.

visit

public void visit(Sequence s)

Visit the specified sequence.

isGeneric

public static boolean isGeneric(FullProduction p)

Determine whether the specified production effectively is generic. This method returns true if the specified production is, in fact, generic or it is a void production that also is non-lexical and consumes the input.

Parameters:

p - The production.

Returns:

true if the specified production should be treated as generic.

See Also:

Generifier.isGeneric(FullProduction)

isValuable

public static boolean isValuable(FullProduction p)

Determine whether the specified production can have a semantic value. Any production that is not void or that consumes the input can have a semantic value. This method assumes that productions have been correctly annotated with the Properties.CONSUMER property.

Parameters:

p - The production.

Returns:

true if the specified production can have a semantic value.

isList

public static boolean isList(Type type)

Determine whether the specified type is a list type that can be processed by this visitor.

Parameters:

type - The type.

Returns:

true if the specified type is a list type that can be processed by this visitor.

isSingleRepetition

public static boolean isSingleRepetition(FullProduction p)

Determine whether the specified production recognizes only a single repetition. This method returns true if the specified production returns a list of objects, nodes, generic nodes, tokens, or strings and each alternative consists of only a single, optionally bound repetition.

Parameters:

p - The production.

Returns:

true if the specified production recognizes only a single repetition.