001/*-------------------------------------------------------------------------+
002|                                                                          |
003| Copyright (c) 2009-2018 CQSE GmbH                                        |
004|                                                                          |
005+-------------------------------------------------------------------------*/
006package eu.cqse.check.framework.core.phase;
007
008import java.util.List;
009import java.util.Optional;
010
011import eu.cqse.check.framework.core.CheckException;
012import eu.cqse.check.framework.core.ECheckParameter;
013import eu.cqse.check.framework.core.phase.ECodeViewOption.ETextViewOption;
014import eu.cqse.check.framework.preprocessor.IPreprocessor;
015import eu.cqse.check.framework.preprocessor.PreprocessorFactory;
016import eu.cqse.check.framework.scanner.ELanguage;
017import eu.cqse.check.framework.scanner.IToken;
018import eu.cqse.check.framework.shallowparser.framework.ShallowEntity;
019import eu.cqse.check.framework.typetracker.ITypeResolution;
020import eu.cqse.check.util.clang.ClangTranslationUnitWrapper;
021
022/**
023 * Context interface for accessing different views of a token element.
024 */
025public interface ITokenElementContext {
026
027        /**
028         * Returns the language of the analyzed token element.
029         */
030        ELanguage getLanguage();
031
032        /**
033         * Returns the uniform path of the analyzed token element.
034         */
035        String getUniformPath();
036
037        /**
038         * Returns the tokens in the given view. This method can be used, if the
039         * executing check requests the {@link ECheckParameter#ABSTRACT_SYNTAX_TREE}
040         * parameter.
041         */
042        List<IToken> getTokens(ECodeViewOption view) throws CheckException;
043
044        /**
045         * Returns the text content in the given view. For most checks the preferred
046         * form of content will be {@link ETextViewOption#FILTERED_CONTENT}, as usually
047         * no findings shall be generated for filtered code.
048         */
049        String getTextContent(ETextViewOption view) throws CheckException;
050
051        /**
052         * Returns the synthetic root entity of the abstract syntax tree based on the
053         * given view.
054         * <p>
055         * This method can be used, if the executing check requests the
056         * {@link ECheckParameter#ABSTRACT_SYNTAX_TREE} parameter.
057         */
058        ShallowEntity getRootEntity(ECodeViewOption view) throws CheckException;
059
060        /**
061         * Returns the abstract syntax tree of the analyzed token element as list of
062         * shallow entities based on the given view.
063         * <p>
064         * This method can be used, if the executing check requests the
065         * {@link ECheckParameter#ABSTRACT_SYNTAX_TREE} parameter.
066         */
067        List<ShallowEntity> getAbstractSyntaxTree(ECodeViewOption view) throws CheckException;
068
069        /**
070         * Returns a type resolution, which contains information about known variables
071         * and their types. This method can be used, if the executing check request the
072         * {@link ECheckParameter#TYPE_RESOLUTION} parameter. Based on the given
073         * {@link ECodeViewOption}.
074         */
075        ITypeResolution getTypeResolution(ECodeViewOption view) throws CheckException;
076
077        /**
078         * Calculates the pre-processed tokens (no global include resolution).
079         */
080        default List<IToken> calculateLocalPreprocessedTokens(List<IToken> tokens) {
081                Optional<IPreprocessor> preprocessor = PreprocessorFactory.createLocalPreprocessor(getLanguage());
082
083                if (preprocessor.isPresent()) {
084                        return preprocessor.get().preprocess(getUniformPath(), tokens);
085                }
086
087                return tokens;
088        }
089
090        /**
091         * Returns a {@link ClangTranslationUnitWrapper} containing the initialized JNI
092         * interface to Clang for the current file. To access this, specify the
093         * {@link ECheckParameter#CLANG} option in the custom check.
094         */
095        ClangTranslationUnitWrapper getClangTranslationUnitWrapper();
096}