Annotator (Rats! Parser Generator 2.4.0 API)

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

Nested Classes
Modifier and Type	Class and Description
`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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description

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

Constructors
Constructor and Description
`Annotator(Runtime runtime, Analyzer analyzer)` Create a new annotator.

Method Summary

Methods
Modifier and Type	Method and Description
`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.

Class Annotator

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class xtc.tree.Visitor

Methods inherited from class java.lang.Object

Field Detail

MARKER

runtime

analyzer

isGeneric

isList

isRecursive

isTopLevel

toProcessIdx

sequences

before

sequenceIdx

elementIdx

after

Constructor Detail

Annotator

Method Detail

push

pop

reset

before

sequenceIndex

elementIndex

after

isValuable

isParseTreeNode

hasBindable

hasValuable

isBoundAndVoided

bindAndVoid

bindAndVoid

annotate

recurse

visit

visit

visit

visit

isGeneric

isValuable

isList

isSingleRepetition