99 lines · c
1//===--- Analysis.h - Analyze symbol references in AST ------------- C++-*-===//2//3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.4// See https://llvm.org/LICENSE.txt for license information.5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception6//7//===----------------------------------------------------------------------===//8/// A library that provides usage analysis for symbols based on AST analysis.9//===----------------------------------------------------------------------===//10 11#ifndef CLANG_INCLUDE_CLEANER_ANALYSIS_H12#define CLANG_INCLUDE_CLEANER_ANALYSIS_H13 14#include "clang-include-cleaner/Record.h"15#include "clang-include-cleaner/Types.h"16#include "clang/Format/Format.h"17#include "clang/Lex/HeaderSearch.h"18#include "clang/Lex/Preprocessor.h"19#include "llvm/ADT/ArrayRef.h"20#include "llvm/ADT/STLFunctionalExtras.h"21#include "llvm/ADT/SmallVector.h"22#include "llvm/ADT/StringRef.h"23#include <string>24#include <utility>25 26namespace clang {27class SourceLocation;28class SourceManager;29class Decl;30class FileEntry;31class HeaderSearch;32namespace tooling {33class Replacements;34struct IncludeStyle;35} // namespace tooling36namespace include_cleaner {37 38/// A UsedSymbolCB is a callback invoked for each symbol reference seen.39///40/// References occur at a particular location, refer to a single symbol, and41/// that symbol may be provided by several headers.42/// FIXME: Provide signals about the providing headers so the caller can filter43/// and rank the results.44using UsedSymbolCB = llvm::function_ref<void(const SymbolReference &SymRef,45 llvm::ArrayRef<Header> Providers)>;46 47/// Find and report all references to symbols in a region of code.48/// It only reports references from main file.49///50/// The AST traversal is rooted at ASTRoots - typically top-level declarations51/// of a single source file.52/// The references to macros must be recorded separately and provided.53///54/// This is the main entrypoint of the include-cleaner library, and can be used:55/// - to diagnose missing includes: a referenced symbol is provided by56/// headers which don't match any #include in the main file57/// - to diagnose unused includes: an #include in the main file does not match58/// the headers for any referenced symbol59void walkUsed(llvm::ArrayRef<Decl *> ASTRoots,60 llvm::ArrayRef<SymbolReference> MacroRefs,61 const PragmaIncludes *PI, const Preprocessor &PP,62 UsedSymbolCB CB);63 64struct AnalysisResults {65 std::vector<const Include *> Unused;66 // Spellings, like "<vector>" paired with the Header that generated it.67 std::vector<std::pair<std::string, Header>> Missing;68};69 70/// Determine which headers should be inserted or removed from the main file.71/// This exposes conclusions but not reasons: use lower-level walkUsed for that.72///73/// The HeaderFilter is a predicate that receives absolute path or spelling74/// without quotes/brackets, when a phyiscal file doesn't exist.75/// No analysis will be performed for headers that satisfy the predicate.76AnalysisResults77analyze(llvm::ArrayRef<Decl *> ASTRoots,78 llvm::ArrayRef<SymbolReference> MacroRefs, const Includes &I,79 const PragmaIncludes *PI, const Preprocessor &PP,80 llvm::function_ref<bool(llvm::StringRef)> HeaderFilter = nullptr);81 82/// Removes unused includes and inserts missing ones in the main file.83/// Returns the modified main-file code.84/// The FormatStyle must be C++ or ObjC (to support include ordering).85std::string fixIncludes(const AnalysisResults &Results,86 llvm::StringRef FileName, llvm::StringRef Code,87 const format::FormatStyle &IncludeStyle);88 89/// Gets all the providers for a symbol by traversing each location.90/// Returned headers are sorted by relevance, first element is the most91/// likely provider for the symbol.92llvm::SmallVector<Header> headersForSymbol(const Symbol &S,93 const Preprocessor &PP,94 const PragmaIncludes *PI);95} // namespace include_cleaner96} // namespace clang97 98#endif99