org.eclipse.cdt.internal.ui.text
Class CHeuristicScanner

java.lang.Object
  extended by org.eclipse.cdt.internal.ui.text.CHeuristicScanner
All Implemented Interfaces:
Symbols

public final class CHeuristicScanner
extends java.lang.Object
implements Symbols

Utility methods for heuristic based C manipulations in an incomplete C source file.

An instance holds some internal position in the document and is therefore not threadsafe.


Field Summary
static int NOT_FOUND
          Returned by all methods when the requested position could not be found, or if a BadLocationException was thrown while scanning.
static int UNBOUND
          Special bound parameter that means either -1 (backward scanning) or fDocument.getLength() (forward scanning).
 
Fields inherited from interface org.eclipse.cdt.internal.ui.text.Symbols
TokenARROW, TokenBREAK, TokenCASE, TokenCATCH, TokenCLASS, TokenCOLON, TokenCOMMA, TokenDEFAULT, TokenDELETE, TokenDO, TokenDOT, TokenDOUBLECOLON, TokenELSE, TokenENUM, TokenEOF, TokenEQUAL, TokenFOR, TokenGOTO, TokenGREATERTHAN, TokenIDENT, TokenIF, TokenLBRACE, TokenLBRACKET, TokenLESSTHAN, TokenLPAREN, TokenMINUS, TokenNAMESPACE, TokenNEW, TokenOTHER, TokenPRIVATE, TokenPROTECTED, TokenPUBLIC, TokenQUESTIONMARK, TokenRBRACE, TokenRBRACKET, TokenRETURN, TokenRPAREN, TokenSEMICOLON, TokenSHIFTRIGHT, TokenSTATIC, TokenSTRUCT, TokenSWITCH, TokenTILDE, TokenTRY, TokenUNION, TokenVIRTUAL, TokenWHILE
 
Constructor Summary
CHeuristicScanner(org.eclipse.jface.text.IDocument document)
          Calls this(document, ICPartitions.C_PARTITIONING, IDocument.DEFAULT_CONTENT_TYPE).
CHeuristicScanner(org.eclipse.jface.text.IDocument document, java.lang.String partitioning, java.lang.String partition)
          Creates a new instance.
 
Method Summary
 int findClosingPeer(int start, char openingPeer, char closingPeer)
          Returns the position of the closing peer character (forward search).
 int findNonWhitespaceBackward(int position, int bound)
          Finds the highest position in fDocument such that the position is <= position and > bound and Character.isWhitespace(fDocument.getChar(pos)) evaluates to false and the position is in the default partition.
 int findNonWhitespaceForward(int position, int bound)
          Finds the smallest position in fDocument such that the position is >= position and < bound and Character.isWhitespace(fDocument.getChar(pos)) evaluates to false and the position is in the default partition.
 int findNonWhitespaceForwardInAnyPartition(int position, int bound)
          Finds the smallest position in fDocument such that the position is >= position and < bound and Character.isWhitespace(fDocument.getChar(pos)) evaluates to false.
 int findOpeningPeer(int start, char openingPeer, char closingPeer)
          Returns the position of the opening peer character (backward search).
 int findOpeningPeer(int start, int bound, char openingPeer, char closingPeer)
          Returns the position of the opening peer character (backward search).
 org.eclipse.jface.text.IRegion findSurroundingBlock(int offset)
          Computes the surrounding block around offset.
 int getPosition()
          Returns the most recent internal scan position.
 boolean isBracelessBlockStart(int position, int bound)
          Checks if the line seems to be an open condition not followed by a block (i.e. an if, while, or for statement with just one following statement, see example below).
 boolean isDefaultPartition(int position)
          Checks whether position resides in a default (C) partition of fDocument.
 boolean looksLikeClassInstanceCreationBackward(int start, int bound)
          Returns true if the document, when scanned backwards from start appears to contain a class instance creation, i.e. a possibly qualified name preceded by a new keyword.
 boolean looksLikeCompositeTypeDefinitionBackward(int start, int bound)
          Returns true if the document, when scanned backwards from start appears to be a composite type (class, struct, union) or enum definition.
 boolean looksLikeFieldReferenceBackward(int start, int bound)
          Returns true if the document, when scanned backwards from start appears to contain a field reference, i.e. a (optional) name preceded by a .
 int nextToken(int start, int bound)
          Returns the next token in forward direction, starting at start, and not extending further than bound.
 int previousToken(int start, int bound)
          Returns the next token in backward direction, starting at start, and not extending further than bound.
 int scanBackward(int position, int bound, char ch)
          Finds the highest position in fDocument such that the position is <= position and > bound and fDocument.getChar(position) == ch evaluates to true and the position is in the default partition.
 int scanBackward(int position, int bound, char[] chars)
          Finds the highest position in fDocument such that the position is <= position and > bound and fDocument.getChar(position) == ch evaluates to true for at least one ch in chars and the position is in the default partition.
 int scanBackward(int start, int bound, org.eclipse.cdt.internal.ui.text.CHeuristicScanner.StopCondition condition)
          Finds the highest position p in fDocument such that bound < p <= start and condition.stop(fDocument.getChar(p), p) evaluates to true.
 int scanForward(int position, int bound, char ch)
          Finds the lowest position in fDocument such that the position is >= position and < bound and fDocument.getChar(position) == ch evaluates to true and the position is in the default partition.
 int scanForward(int position, int bound, char[] chars)
          Finds the lowest position in fDocument such that the position is >= position and < bound and fDocument.getChar(position) == ch evaluates to true for at least one ch in chars and the position is in the default partition.
 int scanForward(int start, int bound, org.eclipse.cdt.internal.ui.text.CHeuristicScanner.StopCondition condition)
          Finds the lowest position p in fDocument such that start <= p < bound and condition.stop(fDocument.getChar(p), p) evaluates to true.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

NOT_FOUND

public static final int NOT_FOUND
Returned by all methods when the requested position could not be found, or if a BadLocationException was thrown while scanning.

See Also:
Constant Field Values

UNBOUND

public static final int UNBOUND
Special bound parameter that means either -1 (backward scanning) or fDocument.getLength() (forward scanning).

See Also:
Constant Field Values
Constructor Detail

CHeuristicScanner

public CHeuristicScanner(org.eclipse.jface.text.IDocument document,
                         java.lang.String partitioning,
                         java.lang.String partition)
Creates a new instance.

Parameters:
document - the document to scan
partitioning - the partitioning to use for scanning
partition - the partition to scan in

CHeuristicScanner

public CHeuristicScanner(org.eclipse.jface.text.IDocument document)
Calls this(document, ICPartitions.C_PARTITIONING, IDocument.DEFAULT_CONTENT_TYPE).

Parameters:
document - the document to scan.
Method Detail

getPosition

public int getPosition()
Returns the most recent internal scan position.

Returns:
the most recent internal scan position.

nextToken

public int nextToken(int start,
                     int bound)
Returns the next token in forward direction, starting at start, and not extending further than bound. The return value is one of the constants defined in Symbols. After a call, getPosition() will return the position just after the scanned token (i.e. the next position that will be scanned).

Parameters:
start - the first character position in the document to consider
bound - the first position not to consider any more
Returns:
a constant from Symbols describing the next token

previousToken

public int previousToken(int start,
                         int bound)
Returns the next token in backward direction, starting at start, and not extending further than bound. The return value is one of the constants defined in Symbols. After a call, getPosition() will return the position just before the scanned token starts (i.e. the next position that will be scanned).

Parameters:
start - the first character position in the document to consider
bound - the first position not to consider any more
Returns:
a constant from Symbols describing the previous token

findClosingPeer

public int findClosingPeer(int start,
                           char openingPeer,
                           char closingPeer)
Returns the position of the closing peer character (forward search). Any scopes introduced by opening peers are skipped. All peers accounted for must reside in the default partition.

Note that start must not point to the opening peer, but to the first character being searched.

Parameters:
start - the start position
openingPeer - the opening peer character (e.g. '{')
closingPeer - the closing peer character (e.g. '}')
Returns:
the matching peer character position, or NOT_FOUND

findOpeningPeer

public int findOpeningPeer(int start,
                           char openingPeer,
                           char closingPeer)
Returns the position of the opening peer character (backward search). Any scopes introduced by closing peers are skipped. All peers accounted for must reside in the default partition.

Note that start must not point to the closing peer, but to the first character being searched.

Parameters:
start - the start position
openingPeer - the opening peer character (e.g. '{')
closingPeer - the closing peer character (e.g. '}')
Returns:
the matching peer character position, or NOT_FOUND

findOpeningPeer

public int findOpeningPeer(int start,
                           int bound,
                           char openingPeer,
                           char closingPeer)
Returns the position of the opening peer character (backward search). Any scopes introduced by closing peers are skipped. All peers accounted for must reside in the default partition.

Note that start must not point to the closing peer, but to the first character being searched.

Parameters:
start - the start position
bound - the bound
openingPeer - the opening peer character (e.g. '{')
closingPeer - the closing peer character (e.g. '}')
Returns:
the matching peer character position, or NOT_FOUND

findSurroundingBlock

public org.eclipse.jface.text.IRegion findSurroundingBlock(int offset)
Computes the surrounding block around offset. The search is started at the beginning of offset, i.e. an opening brace at offset will not be part of the surrounding block, but a closing brace will.

Parameters:
offset - the offset for which the surrounding block is computed
Returns:
a region describing the surrounding block, or null if none can be found

findNonWhitespaceForward

public int findNonWhitespaceForward(int position,
                                    int bound)
Finds the smallest position in fDocument such that the position is >= position and < bound and Character.isWhitespace(fDocument.getChar(pos)) evaluates to false and the position is in the default partition.

Parameters:
position - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound > position, or UNBOUND
Returns:
the smallest position of a non-whitespace character in [position, bound) that resides in a C partition, or NOT_FOUND if none can be found

findNonWhitespaceForwardInAnyPartition

public int findNonWhitespaceForwardInAnyPartition(int position,
                                                  int bound)
Finds the smallest position in fDocument such that the position is >= position and < bound and Character.isWhitespace(fDocument.getChar(pos)) evaluates to false.

Parameters:
position - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound > position, or UNBOUND
Returns:
the smallest position of a non-whitespace character in [position, bound), or NOT_FOUND if none can be found

findNonWhitespaceBackward

public int findNonWhitespaceBackward(int position,
                                     int bound)
Finds the highest position in fDocument such that the position is <= position and > bound and Character.isWhitespace(fDocument.getChar(pos)) evaluates to false and the position is in the default partition.

Parameters:
position - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound < position, or UNBOUND
Returns:
the highest position of a non-whitespace character in (bound, position] that resides in a C partition, or NOT_FOUND if none can be found

scanForward

public int scanForward(int start,
                       int bound,
                       org.eclipse.cdt.internal.ui.text.CHeuristicScanner.StopCondition condition)
Finds the lowest position p in fDocument such that start <= p < bound and condition.stop(fDocument.getChar(p), p) evaluates to true.

Parameters:
start - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound > start, or UNBOUND
condition - the StopCondition to check
Returns:
the lowest position in [start, bound) for which condition holds, or NOT_FOUND if none can be found

scanForward

public int scanForward(int position,
                       int bound,
                       char ch)
Finds the lowest position in fDocument such that the position is >= position and < bound and fDocument.getChar(position) == ch evaluates to true and the position is in the default partition.

Parameters:
position - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound > position, or UNBOUND
ch - the char to search for
Returns:
the lowest position of ch in (bound, position] that resides in a C partition, or NOT_FOUND if none can be found

scanForward

public int scanForward(int position,
                       int bound,
                       char[] chars)
Finds the lowest position in fDocument such that the position is >= position and < bound and fDocument.getChar(position) == ch evaluates to true for at least one ch in chars and the position is in the default partition.

Parameters:
position - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound > position, or UNBOUND
chars - an array of char to search for
Returns:
the lowest position of a non-whitespace character in [position, bound) that resides in a C partition, or NOT_FOUND if none can be found

scanBackward

public int scanBackward(int start,
                        int bound,
                        org.eclipse.cdt.internal.ui.text.CHeuristicScanner.StopCondition condition)
Finds the highest position p in fDocument such that bound < p <= start and condition.stop(fDocument.getChar(p), p) evaluates to true.

Parameters:
start - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound < start, or UNBOUND
condition - the StopCondition to check
Returns:
the highest position in (bound, start for which condition holds, or NOT_FOUND if none can be found

scanBackward

public int scanBackward(int position,
                        int bound,
                        char ch)
Finds the highest position in fDocument such that the position is <= position and > bound and fDocument.getChar(position) == ch evaluates to true and the position is in the default partition.

Parameters:
position - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound < position, or UNBOUND
ch - the char to search for
Returns:
the highest position of one element in chars in (bound, position] that resides in a C partition, or NOT_FOUND if none can be found

scanBackward

public int scanBackward(int position,
                        int bound,
                        char[] chars)
Finds the highest position in fDocument such that the position is <= position and > bound and fDocument.getChar(position) == ch evaluates to true for at least one ch in chars and the position is in the default partition.

Parameters:
position - the first character position in fDocument to be considered
bound - the first position in fDocument to not consider any more, with bound < position, or UNBOUND
chars - an array of char to search for
Returns:
the highest position of one element in chars in (bound, position] that resides in a C partition, or NOT_FOUND if none can be found

isDefaultPartition

public boolean isDefaultPartition(int position)
Checks whether position resides in a default (C) partition of fDocument.

Parameters:
position - the position to be checked
Returns:
true if position is in the default partition of fDocument, false otherwise

isBracelessBlockStart

public boolean isBracelessBlockStart(int position,
                                     int bound)
Checks if the line seems to be an open condition not followed by a block (i.e. an if, while, or for statement with just one following statement, see example below).
 if (condition)
     doStuff();
 

Algorithm: if the last non-WS, non-Comment code on the line is an if (condition), while (condition), for( expression), do, else, and there is no statement after that

Parameters:
position - the insert position of the new character
bound - the lowest position to consider
Returns:
true if the code is a conditional statement or loop without a block, false otherwise

looksLikeClassInstanceCreationBackward

public boolean looksLikeClassInstanceCreationBackward(int start,
                                                      int bound)
Returns true if the document, when scanned backwards from start appears to contain a class instance creation, i.e. a possibly qualified name preceded by a new keyword. The start must be at the end of the type name, and before any generic signature or constructor parameter list. The heuristic will return true if start is at the following positions (|):
  new std::vector<std::string>|(10)
  new str_vector |(10)
  new / * comment * / str_vector |(10)
 
but not the following:
  new std::vector<std::string>(10)|
  new std::vector<std::string>|(10)
  new vector (10)|
  vector |(10)
 

Parameters:
start - the position where the type name of the class instance creation supposedly ends
bound - the first position in fDocument to not consider any more, with bound < start, or UNBOUND
Returns:
true if the current position looks like after the type name of a class instance creation

looksLikeFieldReferenceBackward

public boolean looksLikeFieldReferenceBackward(int start,
                                               int bound)
Returns true if the document, when scanned backwards from start appears to contain a field reference, i.e. a (optional) name preceded by a . or -> or ::.

Parameters:
start - the position after the field reference operator.
bound - the first position in fDocument to not consider any more, with bound < start, or UNBOUND
Returns:
true if the current position looks like a field reference

looksLikeCompositeTypeDefinitionBackward

public boolean looksLikeCompositeTypeDefinitionBackward(int start,
                                                        int bound)
Returns true if the document, when scanned backwards from start appears to be a composite type (class, struct, union) or enum definition. Examples:
 class A {
 struct A {
 class A : B {
 class A : virtual public B, protected C<T> {
 enum E {
 

Parameters:
start - the position of the opening brace.
bound - the first position in fDocument to not consider any more, with bound < start, or UNBOUND
Returns:
true if the current position looks like a composite type definition