clang-tools  3.9.0
ClangTidyOptions.h
Go to the documentation of this file.
1 //===--- ClangTidyOptions.h - clang-tidy ------------------------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_CLANGTIDYOPTIONS_H
11 #define LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_CLANGTIDYOPTIONS_H
12 
13 #include "llvm/ADT/Optional.h"
14 #include "llvm/ADT/StringMap.h"
15 #include "llvm/ADT/StringRef.h"
16 #include "llvm/Support/ErrorOr.h"
17 #include <functional>
18 #include <map>
19 #include <string>
20 #include <system_error>
21 #include <utility>
22 #include <vector>
23 
24 namespace clang {
25 namespace tidy {
26 
27 /// \brief Contains a list of line ranges in a single file.
28 struct FileFilter {
29  /// \brief File name.
30  std::string Name;
31 
32  /// \brief LineRange is a pair<start, end> (inclusive).
33  typedef std::pair<unsigned, unsigned> LineRange;
34 
35  /// \brief A list of line ranges in this file, for which we show warnings.
36  std::vector<LineRange> LineRanges;
37 };
38 
39 /// \brief Global options. These options are neither stored nor read from
40 /// configuration files.
42  /// \brief Output warnings from certain line ranges of certain files only.
43  /// If empty, no warnings will be filtered.
44  std::vector<FileFilter> LineFilter;
45 };
46 
47 /// \brief Contains options for clang-tidy. These options may be read from
48 /// configuration files, and may be different for different translation units.
50  /// \brief These options are used for all settings that haven't been
51  /// overridden by the \c OptionsProvider.
52  ///
53  /// Allow no checks and no headers by default. This method initializes
54  /// check-specific options by calling \c ClangTidyModule::getModuleOptions()
55  /// of each registered \c ClangTidyModule.
57 
58  /// \brief Creates a new \c ClangTidyOptions instance combined from all fields
59  /// of this instance overridden by the fields of \p Other that have a value.
60  ClangTidyOptions mergeWith(const ClangTidyOptions &Other) const;
61 
62  /// \brief Checks filter.
63  llvm::Optional<std::string> Checks;
64 
65  /// \brief WarningsAsErrors filter.
66  llvm::Optional<std::string> WarningsAsErrors;
67 
68  /// \brief Output warnings from headers matching this filter. Warnings from
69  /// main files will always be displayed.
70  llvm::Optional<std::string> HeaderFilterRegex;
71 
72  /// \brief Output warnings from system headers matching \c HeaderFilterRegex.
73  llvm::Optional<bool> SystemHeaders;
74 
75  /// \brief Turns on temporary destructor-based analysis.
76  llvm::Optional<bool> AnalyzeTemporaryDtors;
77 
78  /// \brief Specifies the name or e-mail of the user running clang-tidy.
79  ///
80  /// This option is used, for example, to place the correct user name in TODO()
81  /// comments in the relevant check.
82  llvm::Optional<std::string> User;
83 
84  typedef std::pair<std::string, std::string> StringPair;
85  typedef std::map<std::string, std::string> OptionMap;
86 
87  /// \brief Key-value mapping used to store check-specific options.
89 
90  typedef std::vector<std::string> ArgList;
91 
92  /// \brief Add extra compilation arguments to the end of the list.
93  llvm::Optional<ArgList> ExtraArgs;
94 
95  /// \brief Add extra compilation arguments to the start of the list.
96  llvm::Optional<ArgList> ExtraArgsBefore;
97 };
98 
99 /// \brief Abstract interface for retrieving various ClangTidy options.
101 public:
102  static const char OptionsSourceTypeDefaultBinary[];
105 
107 
108  /// \brief Returns global options, which are independent of the file.
109  virtual const ClangTidyGlobalOptions &getGlobalOptions() = 0;
110 
111  /// \brief ClangTidyOptions and its source.
112  //
113  /// clang-tidy has 3 types of the sources in order of increasing priority:
114  /// * clang-tidy binary.
115  /// * '-config' commandline option or a specific configuration file. If the
116  /// commandline option is specified, clang-tidy will ignore the
117  /// configuration file.
118  /// * '-checks' commandline option.
119  typedef std::pair<ClangTidyOptions, std::string> OptionsSource;
120 
121  /// \brief Returns an ordered vector of OptionsSources, in order of increasing
122  /// priority.
123  virtual std::vector<OptionsSource>
124  getRawOptions(llvm::StringRef FileName) = 0;
125 
126  /// \brief Returns options applying to a specific translation unit with the
127  /// specified \p FileName.
128  ClangTidyOptions getOptions(llvm::StringRef FileName);
129 };
130 
131 /// \brief Implementation of the \c ClangTidyOptionsProvider interface, which
132 /// returns the same options for all files.
134 public:
136  const ClangTidyOptions &Options)
137  : GlobalOptions(GlobalOptions), DefaultOptions(Options) {}
139  return GlobalOptions;
140  }
141  std::vector<OptionsSource> getRawOptions(llvm::StringRef FileName) override;
142 
143 private:
144  ClangTidyGlobalOptions GlobalOptions;
145  ClangTidyOptions DefaultOptions;
146 };
147 
148 /// \brief Implementation of ClangTidyOptions interface, which is used for
149 /// '-config' command-line option.
151 public:
152  ConfigOptionsProvider(const ClangTidyGlobalOptions &GlobalOptions,
153  const ClangTidyOptions &DefaultOptions,
154  const ClangTidyOptions &ConfigOptions,
155  const ClangTidyOptions &OverrideOptions);
156  std::vector<OptionsSource> getRawOptions(llvm::StringRef FileName) override;
157 
158 private:
159  ClangTidyOptions ConfigOptions;
160  ClangTidyOptions OverrideOptions;
161 };
162 
163 /// \brief Implementation of the \c ClangTidyOptionsProvider interface, which
164 /// tries to find a configuration file in the closest parent directory of each
165 /// source file.
166 ///
167 /// By default, files named ".clang-tidy" will be considered, and the
168 /// \c clang::tidy::parseConfiguration function will be used for parsing, but a
169 /// custom set of configuration file names and parsing functions can be
170 /// specified using the appropriate constructor.
172 public:
173  // \brief A pair of configuration file base name and a function parsing
174  // configuration from text in the corresponding format.
175  typedef std::pair<std::string, std::function<llvm::ErrorOr<ClangTidyOptions>(
176  llvm::StringRef)>> ConfigFileHandler;
177 
178  /// \brief Configuration file handlers listed in the order of priority.
179  ///
180  /// Custom configuration file formats can be supported by constructing the
181  /// list of handlers and passing it to the appropriate \c FileOptionsProvider
182  /// constructor. E.g. initialization of a \c FileOptionsProvider with support
183  /// of a custom configuration file format for files named ".my-tidy-config"
184  /// could look similar to this:
185  /// \code
186  /// FileOptionsProvider::ConfigFileHandlers ConfigHandlers;
187  /// ConfigHandlers.emplace_back(".my-tidy-config", parseMyConfigFormat);
188  /// ConfigHandlers.emplace_back(".clang-tidy", parseConfiguration);
189  /// return llvm::make_unique<FileOptionsProvider>(
190  /// GlobalOptions, DefaultOptions, OverrideOptions, ConfigHandlers);
191  /// \endcode
192  ///
193  /// With the order of handlers shown above, the ".my-tidy-config" file would
194  /// take precedence over ".clang-tidy" if both reside in the same directory.
195  typedef std::vector<ConfigFileHandler> ConfigFileHandlers;
196 
197  /// \brief Initializes the \c FileOptionsProvider instance.
198  ///
199  /// \param GlobalOptions are just stored and returned to the caller of
200  /// \c getGlobalOptions.
201  ///
202  /// \param DefaultOptions are used for all settings not specified in a
203  /// configuration file.
204  ///
205  /// If any of the \param OverrideOptions fields are set, they will override
206  /// whatever options are read from the configuration file.
207  FileOptionsProvider(const ClangTidyGlobalOptions &GlobalOptions,
208  const ClangTidyOptions &DefaultOptions,
210 
211  /// \brief Initializes the \c FileOptionsProvider instance with a custom set
212  /// of configuration file handlers.
213  ///
214  /// \param GlobalOptions are just stored and returned to the caller of
215  /// \c getGlobalOptions.
216  ///
217  /// \param DefaultOptions are used for all settings not specified in a
218  /// configuration file.
219  ///
220  /// If any of the \param OverrideOptions fields are set, they will override
221  /// whatever options are read from the configuration file.
222  ///
223  /// \param ConfigHandlers specifies a custom set of configuration file
224  /// handlers. Each handler is a pair of configuration file name and a function
225  /// that can parse configuration from this file type. The configuration files
226  /// in each directory are searched for in the order of appearance in
227  /// \p ConfigHandlers.
228  FileOptionsProvider(const ClangTidyGlobalOptions &GlobalOptions,
229  const ClangTidyOptions &DefaultOptions,
232 
233  std::vector<OptionsSource> getRawOptions(llvm::StringRef FileName) override;
234 
235 protected:
236  /// \brief Try to read configuration files from \p Directory using registered
237  /// \c ConfigHandlers.
238  llvm::Optional<OptionsSource> tryReadConfigFile(llvm::StringRef Directory);
239 
240  llvm::StringMap<OptionsSource> CachedOptions;
243 };
244 
245 /// \brief Parses LineFilter from JSON and stores it to the \p Options.
246 std::error_code parseLineFilter(llvm::StringRef LineFilter,
247  ClangTidyGlobalOptions &Options);
248 
249 /// \brief Parses configuration from JSON and returns \c ClangTidyOptions or an
250 /// error.
251 llvm::ErrorOr<ClangTidyOptions> parseConfiguration(llvm::StringRef Config);
252 
253 /// \brief Serializes configuration to a YAML-encoded string.
254 std::string configurationAsText(const ClangTidyOptions &Options);
255 
256 } // end namespace tidy
257 } // end namespace clang
258 
259 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_CLANGTIDYOPTIONS_H
llvm::Optional< std::string > Checks
Checks filter.
std::vector< OptionsSource > getRawOptions(llvm::StringRef FileName) override
Returns an ordered vector of OptionsSources, in order of increasing priority.
llvm::Optional< ArgList > ExtraArgs
Add extra compilation arguments to the end of the list.
Implementation of the ClangTidyOptionsProvider interface, which tries to find a configuration file in...
llvm::Optional< std::string > User
Specifies the name or e-mail of the user running clang-tidy.
std::vector< std::string > ArgList
std::pair< std::string, std::string > StringPair
Implementation of ClangTidyOptions interface, which is used for '-config' command-line option...
virtual std::vector< OptionsSource > getRawOptions(llvm::StringRef FileName)=0
Returns an ordered vector of OptionsSources, in order of increasing priority.
llvm::Optional< std::string > HeaderFilterRegex
Output warnings from headers matching this filter.
static const char OptionsSourceTypeCheckCommandLineOption[]
Contains options for clang-tidy.
static const char OptionsSourceTypeConfigCommandLineOption[]
std::vector< OptionsSource > getRawOptions(llvm::StringRef FileName) override
Returns an ordered vector of OptionsSources, in order of increasing priority.
std::error_code parseLineFilter(StringRef LineFilter, clang::tidy::ClangTidyGlobalOptions &Options)
Parses -line-filter option and stores it to the Options.
llvm::ErrorOr< ClangTidyOptions > parseConfiguration(StringRef Config)
OptionMap CheckOptions
Key-value mapping used to store check-specific options.
llvm::Optional< bool > SystemHeaders
Output warnings from system headers matching HeaderFilterRegex.
llvm::Optional< ArgList > ExtraArgsBefore
Add extra compilation arguments to the start of the list.
static cl::opt< std::string > Directory(cl::Positional, cl::Required, cl::desc("<Search Root Directory>"))
static cl::opt< std::string > LineFilter("line-filter", cl::desc(R"( List of files with line ranges to filter the warnings. Can be used together with -header-filter. The format of the list is a JSON array of objects: [ {"name":"file1.cpp","lines":[[1,3],[5,7]]}, {"name":"file2.h"} ] )"), cl::init(""), cl::cat(ClangTidyCategory))
std::pair< unsigned, unsigned > LineRange
LineRange is a pair<start, end> (inclusive).
std::vector< OptionsSource > getRawOptions(llvm::StringRef FileName) override
Returns an ordered vector of OptionsSources, in order of increasing priority.
std::string configurationAsText(const ClangTidyOptions &Options)
Serializes configuration to a YAML-encoded string.
llvm::StringMap< OptionsSource > CachedOptions
std::map< std::string, std::string > OptionMap
std::vector< FileFilter > LineFilter
Output warnings from certain line ranges of certain files only.
ClangTidyOptions mergeWith(const ClangTidyOptions &Other) const
Creates a new ClangTidyOptions instance combined from all fields of this instance overridden by the f...
static cl::opt< std::string > Config("config", cl::desc(R"( Specifies a configuration in YAML/JSON format: -config="{Checks: '*', CheckOptions:[{key:x, value:y}]}" When the value is empty, clang-tidy will attempt to find a file named .clang-tidy for each source file in its parent directories. )"), cl::init(""), cl::cat(ClangTidyCategory))
std::pair< std::string, std::function< llvm::ErrorOr< ClangTidyOptions > llvm::StringRef)> > ConfigFileHandler
llvm::Optional< std::string > WarningsAsErrors
WarningsAsErrors filter.
virtual const ClangTidyGlobalOptions & getGlobalOptions()=0
Returns global options, which are independent of the file.
std::vector< ConfigFileHandler > ConfigFileHandlers
Configuration file handlers listed in the order of priority.
Contains a list of line ranges in a single file.
llvm::Optional< bool > AnalyzeTemporaryDtors
Turns on temporary destructor-based analysis.
DefaultOptionsProvider(const ClangTidyGlobalOptions &GlobalOptions, const ClangTidyOptions &Options)
std::pair< ClangTidyOptions, std::string > OptionsSource
ClangTidyOptions and its source.
std::vector< LineRange > LineRanges
A list of line ranges in this file, for which we show warnings.
static ClangTidyOptions getDefaults()
These options are used for all settings that haven't been overridden by the OptionsProvider.
ClangTidyOptions getOptions(llvm::StringRef FileName)
Returns options applying to a specific translation unit with the specified FileName.
Abstract interface for retrieving various ClangTidy options.
const ClangTidyGlobalOptions & getGlobalOptions() override
Returns global options, which are independent of the file.
FileOptionsProvider(const ClangTidyGlobalOptions &GlobalOptions, const ClangTidyOptions &DefaultOptions, const ClangTidyOptions &OverrideOptions)
Initializes the FileOptionsProvider instance.
std::string Name
File name.
llvm::Optional< OptionsSource > tryReadConfigFile(llvm::StringRef Directory)
Try to read configuration files from Directory using registered ConfigHandlers.
ConfigOptionsProvider(const ClangTidyGlobalOptions &GlobalOptions, const ClangTidyOptions &DefaultOptions, const ClangTidyOptions &ConfigOptions, const ClangTidyOptions &OverrideOptions)
Implementation of the ClangTidyOptionsProvider interface, which returns the same options for all file...
static const char OptionsSourceTypeDefaultBinary[]