org.eclipse.ptp.pldt.common.analysis
Class PldtAstVisitor

java.lang.Object
  CASTVisitor
      org.eclipse.ptp.pldt.common.analysis.PldtAstVisitor

public abstract class PldtAstVisitor
extends CASTVisitor

This dom-walker helper collects interesting constructs (currently function calls and constants), and adds markers to the source file for C/C++ code.
This base class encapsulates the common behaviors for both C and C++ code and for visitors looking for MPI, OpenMP, LAPI, etc. etc. types of artifacts

Since:

4.0

Field Summary

protected boolean	allowPrefixOnlyMatch
static String	ARTIFACT_CALL
static String	ARTIFACT_CONSTANT
protected static String	ARTIFACT_NAME
protected static String	PREFIX

Constructor Summary

PldtAstVisitor(List<String> includes, String fileName, boolean prefixOnlyMatch, ScanReturn scanReturn)

PldtAstVisitor(List<String> includes, String fileName, ScanReturn scanReturn)
Constructor without prefixOnlyMatch arg, assumes false

Method Summary

boolean	addIncludePath(IPath path, String name, boolean dontAskAgain) Add an include path to the prefs - probably found dynamically during analysis and requested to be added by the user Note that the path will be to the actual file in which the name was found; the path that will be added to the prefs is the parent directory of that file.
boolean	allowIncludePathAdd() allow dynamic adding to include path?
boolean[]	askUI(String title, String message, boolean dontAskAgain) Dialog to ask a question in the UI thread, and return its answer plus a persistent setting for not asking the same question again.
protected String	chooseName(String bindingName, String rawSignature) Choose how to distinguish between binding name, and raw signature.
List	convertToList(String stringList) Convert a string to a list with given delimiters
protected String	getIncludesPrefID() needs to be overrridden for derived classes that need to dynamically update the pref store e.g. for the includes path
protected IPreferenceStore	getPreferenceStore() needs to be overrridden for derived classes that need to dynamically update the pref store e.g. for the includes path
protected String	getTypeName() needs to be overrridden for derived classes that need to dynamically update the pref store e.g. for the includes path.
protected boolean	isArtifact(IASTName funcName) Determines if the funcName is an instance of the type of artifact in which we are interested.
abstract boolean	matchesPrefix(String name) will be overridden where needed; note that for C code, the test for if the prefix matches has already been done before this is called so this test isn't necessary.
void	processExprWithConstant(IASTExpression astExpr) Look for artifacts in an IASTExpression
void	processFuncName(IASTName funcName, IASTExpression astExpr) Process a function name from an expression and determine if it should be marked as an Artifact.
void	processIdExprAsLiteral(IASTIdExpression expression) Look for artifacts within a IASTIdExpression
void	processMacroLiteral(IASTLiteralExpression expression)
protected void	replaceIncludes(String includes) Replace the includes list in this visitor so the change will be recognized.
int	visit(IASTDeclaration declaration) Skip decls that are included.
int	visit(IASTExpression expression) Visit an ast node of type IASTExpression.
int	visit(IASTStatement statement) Skip statements that are included.

Methods inherited from class java.lang.Object

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

Field Detail

ARTIFACT_CALL

public static String ARTIFACT_CALL

Since:

4.0

ARTIFACT_CONSTANT

public static String ARTIFACT_CONSTANT

Since:

4.0

ARTIFACT_NAME

protected static String ARTIFACT_NAME

PREFIX

protected static String PREFIX

allowPrefixOnlyMatch

protected boolean allowPrefixOnlyMatch

Constructor Detail

PldtAstVisitor

public PldtAstVisitor(List<String> includes,
                      String fileName,
                      boolean prefixOnlyMatch,
                      ScanReturn scanReturn)

Parameters:

includes - list of include paths that we'll probably want to consider in the work that this visitor does

fileName - the name of the file that this visitor is visiting(?)

prefixOnlyMatch - if true, then artifact is recognized if it starts with the plugin-specific prefix (e.g. "MPI_" etc.) instead of forcing a lookup of the location of the header file in which the API is found. This proves to be difficult for users to get right, so prefix-only recognition of artifacts is allowed here.

scanReturn - the ScanReturn object to which the artifacts that we find will be appended.

PldtAstVisitor

public PldtAstVisitor(List<String> includes,
                      String fileName,
                      ScanReturn scanReturn)

Constructor without prefixOnlyMatch arg, assumes false

Method Detail

visit

public int visit(IASTStatement statement)

Skip statements that are included.

visit

public int visit(IASTExpression expression)

Visit an ast node of type IASTExpression. Most things tend to fall into this visit method.
Version from MPI originally that seems best for all. Handles recognition within macro expansions

visit

public int visit(IASTDeclaration declaration)

Skip decls that are included.

Parameters:

declaration -

Returns:

processFuncName

public void processFuncName(IASTName funcName,
                            IASTExpression astExpr)

Process a function name from an expression and determine if it should be marked as an Artifact. If so, append it to the scanReturn object that this visitor is populating. An artifact is a function name (or other identifier) that was found in the include path, or matched with prefix, as defined in the preferences.

Parameters:

astExpr -

funcName -

processExprWithConstant

public void processExprWithConstant(IASTExpression astExpr)

Look for artifacts in an IASTExpression

Parameters:

astExpr -

isArtifact

protected boolean isArtifact(IASTName funcName)

Determines if the funcName is an instance of the type of artifact in which we are interested.
An artifact is a function name that was found in the include path (e.g. MPI or OpenMP), (or identified by prefix-only match, which is now the default) as defined in the PLDT preferences.

Parameters:

funcName -

chooseName

protected String chooseName(String bindingName,
                            String rawSignature)

Choose how to distinguish between binding name, and raw signature.
Could be overridden by subclasses if, for example, a name with a prefix e.g. "MPI::foo" should be preferred over "foo".
Here, the default case is that we always choose the regular/binding name, unless it's empty, in which case we choose the rawSignature.

Parameters:

bindingName -

rawSignature -

Returns:

processMacroLiteral

public void processMacroLiteral(IASTLiteralExpression expression)

processIdExprAsLiteral

public void processIdExprAsLiteral(IASTIdExpression expression)

Look for artifacts within a IASTIdExpression

Parameters:

expression -

allowIncludePathAdd

public boolean allowIncludePathAdd()

allow dynamic adding to include path? Can be overridden by derived classes.

Returns:

replaceIncludes

protected void replaceIncludes(String includes)

Replace the includes list in this visitor so the change will be recognized.

Parameters:

includes -

convertToList

public List convertToList(String stringList)

Convert a string to a list with given delimiters

Parameters:

stringList -

Returns:

addIncludePath

public boolean addIncludePath(IPath path,
                              String name,
                              boolean dontAskAgain)

Add an include path to the prefs - probably found dynamically during analysis and requested to be added by the user
Note that the path will be to the actual file in which the name was found; the path that will be added to the prefs is the parent directory of that file.

Parameters:

path -

name - the name (function etc) that was found in the path

dontAskAgain - initial value of toggle "don't ask again"

getTypeName

protected String getTypeName()

needs to be overrridden for derived classes that need to dynamically update the pref store e.g. for the includes path. This type name is used for messages, etc.

Returns:

artifact type name such as "MPI", "OpenMP" etc.

getIncludesPrefID

protected String getIncludesPrefID()

needs to be overrridden for derived classes that need to dynamically update the pref store e.g. for the includes path

Returns:

getPreferenceStore

protected IPreferenceStore getPreferenceStore()

needs to be overrridden for derived classes that need to dynamically update the pref store e.g. for the includes path

Returns:

askUI

public boolean[] askUI(String title,
                       String message,
                       boolean dontAskAgain)

Dialog to ask a question in the UI thread, and return its answer plus a persistent setting for not asking the same question again. Users get tired of the same old question!

Parameters:

title -

message -

dontAskAgain - allows persistent setting to not ask this question again

Returns:

matchesPrefix

public abstract boolean matchesPrefix(String name)

will be overridden where needed; note that for C code, the test for if the prefix matches has already been done before this is called so this test isn't necessary. In this case the subclass should implement it and always return true, but with increased use of "recognize artifact by prefix only" this becomes more important. FIXME improve this convoluted logic

Parameters:

name -

Returns:

Since:

4.0