TokenStreamRewriter (ANTLR 4 Runtime 4.0-rc-1 API)

java.lang.Object
- org.antlr.v4.runtime.TokenStreamRewriter

```
public class TokenStreamRewriter
extends Object
```
Useful for rewriting out a buffered input token stream after doing some augmentation or other manipulations on it. You can insert stuff, replace, and delete chunks. Note that the operations are done lazily--only if you convert the buffer to a String with getText(). This is very efficient because you are not moving data around all the time. As the buffer of tokens is converted to strings, the getText() method(s) scan the input token stream and check to see if there is an operation at the current index. If so, the operation is done and then normal String rendering continues on the buffer. This is like having multiple Turing machine instruction streams (programs) operating on a single input tape. :) This rewriter makes no modifications to the token stream. It does not ask the stream to fill itself up nor does it advance the input cursor. The token stream index() will return the same value before and after any getText() call. The rewriter only works on tokens that you have in the buffer and ignores the current input cursor. If you are buffering tokens on-demand, calling getText() halfway through the input will only do rewrites for those tokens in the first half of the file. Since the operations are done lazily at getText-time, operations do not screw up the token index values. That is, an insert operation at token index i does not change the index values for tokens i+1..n-1. Because operations never actually alter the buffer, you may always get the original token stream back without undoing anything. Since the instructions are queued up, you can easily simulate transactions and roll back any changes if there is an error just by removing instructions. For example, CharStream input = new ANTLRFileStream("input"); TLexer lex = new TLexer(input); CommonTokenStream tokens = new CommonTokenStream(lex); T parser = new T(tokens); TokenStreamRewriter rewriter = new TokenStreamRewriter(tokens); parser.startRule(); Then in the rules, you can execute (assuming rewriter is visible): Token t,u; ... rewriter.insertAfter(t, "text to put after t");} rewriter.insertAfter(u, "text after u");} System.out.println(tokens.toString()); You can also have multiple "instruction streams" and get multiple rewrites from a single pass over the input. Just name the instruction streams and use that name again when printing the buffer. This could be useful for generating a C file and also its header file--all from the same buffer: tokens.insertAfter("pass1", t, "text to put after t");} tokens.insertAfter("pass2", u, "text after u");} System.out.println(tokens.toString("pass1")); System.out.println(tokens.toString("pass2")); If you don't use named rewrite streams, a "default" stream is used as the first example shows.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class TokenStreamRewriter.RewriteOperation

Nested Classes
Modifier and Type	Class and Description
`class`	`TokenStreamRewriter.RewriteOperation`

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_PROGRAM_NAME`
`protected Map<String,Integer>`	`lastRewriteTokenIndexes` Map String (program name) -> Integer index
`static int`	`MIN_TOKEN_INDEX`
`static int`	`PROGRAM_INIT_SIZE`
`protected Map<String,List<TokenStreamRewriter.RewriteOperation>>`	`programs` You may have multiple, named streams of rewrite operations.
`protected TokenStream`	`tokens` Our source stream

Constructor Summary

Constructors
Constructor and Description

TokenStreamRewriter(TokenStream tokens)

Constructors
Constructor and Description
`TokenStreamRewriter(TokenStream tokens)`

Method Summary

Methods
Modifier and Type	Method and Description
`protected String`	`catOpText(Object a, Object b)`
`void`	`delete(int index)`
`void`	`delete(int from, int to)`
`void`	`delete(String programName, int from, int to)`
`void`	`delete(String programName, Token from, Token to)`
`void`	`delete(Token indexT)`
`void`	`delete(Token from, Token to)`
`void`	`deleteProgram()`
`void`	`deleteProgram(String programName)` Reset the program so that no instructions exist
`protected <T extends TokenStreamRewriter.RewriteOperation> List<? extends T>`	`getKindOfOps(List<? extends TokenStreamRewriter.RewriteOperation> rewrites, Class<T> kind, int before)` Get all operations before an index of a particular kind
`int`	`getLastRewriteTokenIndex()`
`protected int`	`getLastRewriteTokenIndex(String programName)`
`protected List<TokenStreamRewriter.RewriteOperation>`	`getProgram(String name)`
`String`	`getText()` Return the text from the original tokens altered per the instructions given to this rewriter.
`String`	`getText(Interval interval)` Return the text associated with the tokens in the interval from the original token stream but with the alterations given to this rewriter.
`String`	`getText(String programName, Interval interval)`
`TokenStream`	`getTokenStream()`
`void`	`insertAfter(int index, Object text)`
`void`	`insertAfter(String programName, int index, Object text)`
`void`	`insertAfter(String programName, Token t, Object text)`
`void`	`insertAfter(Token t, Object text)`
`void`	`insertBefore(int index, Object text)`
`void`	`insertBefore(String programName, int index, Object text)`
`void`	`insertBefore(String programName, Token t, Object text)`
`void`	`insertBefore(Token t, Object text)`
`protected Map<Integer,TokenStreamRewriter.RewriteOperation>`	`reduceToSingleOperationPerIndex(List<TokenStreamRewriter.RewriteOperation> rewrites)` We need to combine operations and report invalid operations (like overlapping replaces that are not completed nested).
`void`	`replace(int from, int to, Object text)`
`void`	`replace(int index, Object text)`
`void`	`replace(String programName, int from, int to, Object text)`
`void`	`replace(String programName, Token from, Token to, Object text)`
`void`	`replace(Token indexT, Object text)`
`void`	`replace(Token from, Token to, Object text)`
`void`	`rollback(int instructionIndex)`
`void`	`rollback(String programName, int instructionIndex)` Rollback the instruction stream for a program so that the indicated instruction (via instructionIndex) is no longer in the stream.
`protected void`	`setLastRewriteTokenIndex(String programName, int i)`

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

- Field Detail
  - DEFAULT_PROGRAM_NAME
```
public static final String DEFAULT_PROGRAM_NAME
```
    See Also:
    Constant Field Values
  - PROGRAM_INIT_SIZE
```
public static final int PROGRAM_INIT_SIZE
```
    See Also:
    Constant Field Values
  - MIN_TOKEN_INDEX
```
public static final int MIN_TOKEN_INDEX
```
    See Also:
    Constant Field Values
  - tokens
```
protected final TokenStream tokens
```
    Our source stream
  - programs
```
protected final Map<String,List<TokenStreamRewriter.RewriteOperation>> programs
```
    You may have multiple, named streams of rewrite operations. I'm calling these things "programs." Maps String (name) -> rewrite (List)
  - lastRewriteTokenIndexes
```
protected final Map<String,Integer> lastRewriteTokenIndexes
```
    Map String (program name) -> Integer index
- Constructor Detail
  - TokenStreamRewriter
```
public TokenStreamRewriter(TokenStream tokens)
```
- Method Detail
  - getTokenStream
```
public final TokenStream getTokenStream()
```
  - rollback
```
public void rollback(int instructionIndex)
```
  - rollback
```
public void rollback(String programName,
            int instructionIndex)
```
    Rollback the instruction stream for a program so that the indicated instruction (via instructionIndex) is no longer in the stream. UNTESTED!
  - deleteProgram
```
public void deleteProgram()
```
  - deleteProgram
```
public void deleteProgram(String programName)
```
    Reset the program so that no instructions exist
  - insertAfter
```
public void insertAfter(Token t,
               Object text)
```
  - insertAfter
```
public void insertAfter(int index,
               Object text)
```
  - insertAfter
```
public void insertAfter(String programName,
               Token t,
               Object text)
```
  - insertAfter
```
public void insertAfter(String programName,
               int index,
               Object text)
```
  - insertBefore
```
public void insertBefore(Token t,
                Object text)
```
  - insertBefore
```
public void insertBefore(int index,
                Object text)
```
  - insertBefore
```
public void insertBefore(String programName,
                Token t,
                Object text)
```
  - insertBefore
```
public void insertBefore(String programName,
                int index,
                Object text)
```
  - replace
```
public void replace(int index,
           Object text)
```
  - replace
```
public void replace(int from,
           int to,
           Object text)
```
  - replace
```
public void replace(Token indexT,
           Object text)
```
  - replace
```
public void replace(Token from,
           Token to,
           Object text)
```
  - replace
```
public void replace(String programName,
           int from,
           int to,
           @Nullable
           Object text)
```
  - replace
```
public void replace(String programName,
           Token from,
           Token to,
           @Nullable
           Object text)
```
  - delete
```
public void delete(int index)
```
  - delete
```
public void delete(int from,
          int to)
```
  - delete
```
public void delete(Token indexT)
```
  - delete
```
public void delete(Token from,
          Token to)
```
  - delete
```
public void delete(String programName,
          int from,
          int to)
```
  - delete
```
public void delete(String programName,
          Token from,
          Token to)
```
  - getLastRewriteTokenIndex
```
public int getLastRewriteTokenIndex()
```
  - getLastRewriteTokenIndex
```
protected int getLastRewriteTokenIndex(String programName)
```
  - setLastRewriteTokenIndex
```
protected void setLastRewriteTokenIndex(String programName,
                            int i)
```
  - getProgram
```
protected List<TokenStreamRewriter.RewriteOperation> getProgram(String name)
```
  - getText
```
public String getText()
```
    Return the text from the original tokens altered per the instructions given to this rewriter.
  - getText
```
public String getText(Interval interval)
```
    Return the text associated with the tokens in the interval from the original token stream but with the alterations given to this rewriter. The interval refers to the indexes in the original token stream. We do not alter the token stream in any way, so the indexes and intervals are still consistent. Includes any operations done to the first and last token in the interval. So, if you did an insertBefore on the first token, you would get that insertion. The same is true if you do an insertAfter the stop token.
  - getText
```
public String getText(String programName,
             Interval interval)
```
  - reduceToSingleOperationPerIndex
```
protected Map<Integer,TokenStreamRewriter.RewriteOperation> reduceToSingleOperationPerIndex(List<TokenStreamRewriter.RewriteOperation> rewrites)
```
    We need to combine operations and report invalid operations (like overlapping replaces that are not completed nested). Inserts to same index need to be combined etc... Here are the cases: I.i.u I.j.v leave alone, nonoverlapping I.i.u I.i.v combine: Iivu R.i-j.u R.x-y.v | i-j in x-y delete first R R.i-j.u R.i-j.v delete first R R.i-j.u R.x-y.v | x-y in i-j ERROR R.i-j.u R.x-y.v | boundaries overlap ERROR Delete special case of replace (text==null): D.i-j.u D.x-y.v | boundaries overlap combine to max(min)..max(right) I.i.u R.x-y.v | i in (x+1)-y delete I (since insert before we're not deleting i) I.i.u R.x-y.v | i not in (x+1)-y leave alone, nonoverlapping R.x-y.v I.i.u | i in x-y ERROR R.x-y.v I.x.u R.x-y.uv (combine, delete I) R.x-y.v I.i.u | i not in x-y leave alone, nonoverlapping I.i.u = insert u before op @ index i R.x-y.u = replace x-y indexed tokens with u First we need to examine replaces. For any replace op: 1. wipe out any insertions before op within that range. 2. Drop any replace op before that is contained completely within that range. 3. Throw exception upon boundary overlap with any previous replace. Then we can deal with inserts: 1. for any inserts to same index, combine even if not adjacent. 2. for any prior replace with same left boundary, combine this insert with replace and delete this replace. 3. throw exception if index in same range as previous replace Don't actually delete; make op null in list. Easier to walk list. Later we can throw as we add to index -> op map. Note that I.2 R.2-2 will wipe out I.2 even though, technically, the inserted stuff would be before the replace range. But, if you add tokens in front of a method body '{' and then delete the method body, I think the stuff before the '{' you added should disappear too. Return a map from token index to operation.
  - catOpText
```
protected String catOpText(Object a,
               Object b)
```
  - getKindOfOps
```
protected <T extends TokenStreamRewriter.RewriteOperation> List<? extends T> getKindOfOps(List<? extends TokenStreamRewriter.RewriteOperation> rewrites,
                                                                              Class<T> kind,
                                                                              int before)
```
    Get all operations before an index of a particular kind

Class TokenStreamRewriter

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_PROGRAM_NAME

PROGRAM_INIT_SIZE

MIN_TOKEN_INDEX

tokens

programs

lastRewriteTokenIndexes

Constructor Detail

TokenStreamRewriter

Method Detail

getTokenStream

rollback

rollback

deleteProgram

deleteProgram

insertAfter

insertAfter

insertAfter

insertAfter

insertBefore

insertBefore

insertBefore

insertBefore

replace

replace

replace

replace

replace

replace

delete

delete

delete

delete

delete

delete

getLastRewriteTokenIndex

getLastRewriteTokenIndex

setLastRewriteTokenIndex

getProgram

getText

getText

getText

reduceToSingleOperationPerIndex

catOpText

getKindOfOps