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