clang-tools 20.0.0git
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/StringMap.h"
14#include "llvm/ADT/StringRef.h"
15#include "llvm/Support/ErrorOr.h"
16#include "llvm/Support/MemoryBufferRef.h"
17#include "llvm/Support/VirtualFileSystem.h"
18#include <functional>
19#include <optional>
20#include <string>
21#include <system_error>
22#include <utility>
23#include <vector>
24
25namespace clang::tidy {
26
27/// Contains a list of line ranges in a single file.
28struct FileFilter {
29 /// File name.
30 std::string Name;
31
32 /// LineRange is a pair<start, end> (inclusive).
33 using LineRange = std::pair<unsigned int, unsigned int>;
34
35 /// A list of line ranges in this file, for which we show warnings.
36 std::vector<LineRange> LineRanges;
37};
38
39/// Global options. These options are neither stored nor read from
40/// configuration files.
42 /// 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/// Contains options for clang-tidy. These options may be read from
48/// configuration files, and may be different for different translation units.
50 /// 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 /// Overwrites all fields in here by the fields of \p Other that have a value.
59 /// \p Order specifies precedence of \p Other option.
60 ClangTidyOptions &mergeWith(const ClangTidyOptions &Other, unsigned Order);
61
62 /// Creates a new \c ClangTidyOptions instance combined from all fields
63 /// of this instance overridden by the fields of \p Other that have a value.
64 /// \p Order specifies precedence of \p Other option.
65 [[nodiscard]] ClangTidyOptions merge(const ClangTidyOptions &Other,
66 unsigned Order) const;
67
68 /// Checks filter.
69 std::optional<std::string> Checks;
70
71 /// WarningsAsErrors filter.
72 std::optional<std::string> WarningsAsErrors;
73
74 /// File extensions to consider to determine if a given diagnostic is located
75 /// in a header file.
76 std::optional<std::vector<std::string>> HeaderFileExtensions;
77
78 /// File extensions to consider to determine if a given diagnostic is located
79 /// is located in an implementation file.
80 std::optional<std::vector<std::string>> ImplementationFileExtensions;
81
82 /// Output warnings from headers matching this filter. Warnings from
83 /// main files will always be displayed.
84 std::optional<std::string> HeaderFilterRegex;
85
86 /// \brief Exclude warnings from headers matching this filter, even if they
87 /// match \c HeaderFilterRegex.
88 std::optional<std::string> ExcludeHeaderFilterRegex;
89
90 /// Output warnings from system headers matching \c HeaderFilterRegex.
91 std::optional<bool> SystemHeaders;
92
93 /// Format code around applied fixes with clang-format using this
94 /// style.
95 ///
96 /// Can be one of:
97 /// * 'none' - don't format code around applied fixes;
98 /// * 'llvm', 'google', 'mozilla' or other predefined clang-format style
99 /// names;
100 /// * 'file' - use the .clang-format file in the closest parent directory of
101 /// each source file;
102 /// * '{inline-formatting-style-in-yaml-format}'.
103 ///
104 /// See clang-format documentation for more about configuring format style.
105 std::optional<std::string> FormatStyle;
106
107 /// Specifies the name or e-mail of the user running clang-tidy.
108 ///
109 /// This option is used, for example, to place the correct user name in TODO()
110 /// comments in the relevant check.
111 std::optional<std::string> User;
112
113 /// Helper structure for storing option value with priority of the value.
115 ClangTidyValue() = default;
116 ClangTidyValue(const char *Value) : Value(Value) {}
117 ClangTidyValue(llvm::StringRef Value, unsigned Priority = 0)
119
120 std::string Value;
121 /// Priority stores relative precedence of the value loaded from config
122 /// files to disambiguate local vs global value from different levels.
123 unsigned Priority = 0;
124 };
125 using StringPair = std::pair<std::string, std::string>;
126 using OptionMap = llvm::StringMap<ClangTidyValue>;
127
128 /// Key-value mapping used to store check-specific options.
130
131 using ArgList = std::vector<std::string>;
132
133 /// Add extra compilation arguments to the end of the list.
134 std::optional<ArgList> ExtraArgs;
135
136 /// Add extra compilation arguments to the start of the list.
137 std::optional<ArgList> ExtraArgsBefore;
138
139 /// Only used in the FileOptionsProvider and ConfigOptionsProvider. If true
140 /// and using a FileOptionsProvider, it will take a configuration file in the
141 /// parent directory (if any exists) and apply this config file on top of the
142 /// parent one. IF true and using a ConfigOptionsProvider, it will apply this
143 /// config on top of any configuration file it finds in the directory using
144 /// the same logic as FileOptionsProvider. If false or missing, only this
145 /// configuration file will be used.
146 std::optional<bool> InheritParentConfig;
147
148 /// Use colors in diagnostics. If missing, it will be auto detected.
149 std::optional<bool> UseColor;
150};
151
152/// Abstract interface for retrieving various ClangTidy options.
154public:
158
160
161 /// Returns global options, which are independent of the file.
163
164 /// ClangTidyOptions and its source.
165 //
166 /// clang-tidy has 3 types of the sources in order of increasing priority:
167 /// * clang-tidy binary.
168 /// * '-config' commandline option or a specific configuration file. If the
169 /// commandline option is specified, clang-tidy will ignore the
170 /// configuration file.
171 /// * '-checks' commandline option.
172 using OptionsSource = std::pair<ClangTidyOptions, std::string>;
173
174 /// Returns an ordered vector of OptionsSources, in order of increasing
175 /// priority.
176 virtual std::vector<OptionsSource>
177 getRawOptions(llvm::StringRef FileName) = 0;
178
179 /// Returns options applying to a specific translation unit with the
180 /// specified \p FileName.
181 ClangTidyOptions getOptions(llvm::StringRef FileName);
182};
183
184/// Implementation of the \c ClangTidyOptionsProvider interface, which
185/// returns the same options for all files.
187public:
189 ClangTidyOptions Options)
190 : GlobalOptions(std::move(GlobalOptions)),
191 DefaultOptions(std::move(Options)) {}
193 return GlobalOptions;
194 }
195 std::vector<OptionsSource> getRawOptions(llvm::StringRef FileName) override;
196
197private:
198 ClangTidyGlobalOptions GlobalOptions;
199 ClangTidyOptions DefaultOptions;
200};
201
203protected:
204 // A pair of configuration file base name and a function parsing
205 // configuration from text in the corresponding format.
206 using ConfigFileHandler = std::pair<std::string, std::function<llvm::ErrorOr<ClangTidyOptions> (llvm::MemoryBufferRef)>>;
207
208 /// Configuration file handlers listed in the order of priority.
209 ///
210 /// Custom configuration file formats can be supported by constructing the
211 /// list of handlers and passing it to the appropriate \c FileOptionsProvider
212 /// constructor. E.g. initialization of a \c FileOptionsProvider with support
213 /// of a custom configuration file format for files named ".my-tidy-config"
214 /// could look similar to this:
215 /// \code
216 /// FileOptionsProvider::ConfigFileHandlers ConfigHandlers;
217 /// ConfigHandlers.emplace_back(".my-tidy-config", parseMyConfigFormat);
218 /// ConfigHandlers.emplace_back(".clang-tidy", parseConfiguration);
219 /// return std::make_unique<FileOptionsProvider>(
220 /// GlobalOptions, DefaultOptions, OverrideOptions, ConfigHandlers);
221 /// \endcode
222 ///
223 /// With the order of handlers shown above, the ".my-tidy-config" file would
224 /// take precedence over ".clang-tidy" if both reside in the same directory.
225 using ConfigFileHandlers = std::vector<ConfigFileHandler>;
226
228 ClangTidyOptions DefaultOptions,
230 llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> FS);
231
233 ClangTidyOptions DefaultOptions,
236
237 void addRawFileOptions(llvm::StringRef AbsolutePath,
238 std::vector<OptionsSource> &CurOptions);
239
240 /// Try to read configuration files from \p Directory using registered
241 /// \c ConfigHandlers.
242 std::optional<OptionsSource> tryReadConfigFile(llvm::StringRef Directory);
243
244 llvm::StringMap<OptionsSource> CachedOptions;
247 llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> FS;
248};
249
250/// Implementation of ClangTidyOptions interface, which is used for
251/// '-config' command-line option.
253public:
255 ClangTidyGlobalOptions GlobalOptions, ClangTidyOptions DefaultOptions,
257 llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> FS = nullptr);
258 std::vector<OptionsSource> getRawOptions(llvm::StringRef FileName) override;
259
260private:
261 ClangTidyOptions ConfigOptions;
262};
263
264/// Implementation of the \c ClangTidyOptionsProvider interface, which
265/// tries to find a configuration file in the closest parent directory of each
266/// source file.
267///
268/// By default, files named ".clang-tidy" will be considered, and the
269/// \c clang::tidy::parseConfiguration function will be used for parsing, but a
270/// custom set of configuration file names and parsing functions can be
271/// specified using the appropriate constructor.
273public:
274 /// Initializes the \c FileOptionsProvider instance.
275 ///
276 /// \param GlobalOptions are just stored and returned to the caller of
277 /// \c getGlobalOptions.
278 ///
279 /// \param DefaultOptions are used for all settings not specified in a
280 /// configuration file.
281 ///
282 /// If any of the \param OverrideOptions fields are set, they will override
283 /// whatever options are read from the configuration file.
285 ClangTidyGlobalOptions GlobalOptions, ClangTidyOptions DefaultOptions,
287 llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> FS = nullptr);
288
289 /// Initializes the \c FileOptionsProvider instance with a custom set
290 /// of configuration file handlers.
291 ///
292 /// \param GlobalOptions are just stored and returned to the caller of
293 /// \c getGlobalOptions.
294 ///
295 /// \param DefaultOptions are used for all settings not specified in a
296 /// configuration file.
297 ///
298 /// If any of the \param OverrideOptions fields are set, they will override
299 /// whatever options are read from the configuration file.
300 ///
301 /// \param ConfigHandlers specifies a custom set of configuration file
302 /// handlers. Each handler is a pair of configuration file name and a function
303 /// that can parse configuration from this file type. The configuration files
304 /// in each directory are searched for in the order of appearance in
305 /// \p ConfigHandlers.
307 ClangTidyOptions DefaultOptions,
310
311 std::vector<OptionsSource> getRawOptions(llvm::StringRef FileName) override;
312};
313
314/// Parses LineFilter from JSON and stores it to the \p Options.
315std::error_code parseLineFilter(llvm::StringRef LineFilter,
316 ClangTidyGlobalOptions &Options);
317
318/// Parses configuration from JSON and returns \c ClangTidyOptions or an
319/// error.
320llvm::ErrorOr<ClangTidyOptions>
321parseConfiguration(llvm::MemoryBufferRef Config);
322
323using DiagCallback = llvm::function_ref<void(const llvm::SMDiagnostic &)>;
324
325llvm::ErrorOr<ClangTidyOptions>
326parseConfigurationWithDiags(llvm::MemoryBufferRef Config, DiagCallback Handler);
327
328/// Serializes configuration to a YAML-encoded string.
329std::string configurationAsText(const ClangTidyOptions &Options);
330
331} // namespace clang::tidy
332
333#endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_TIDY_CLANGTIDYOPTIONS_H
static cl::opt< std::string > Config("config", desc(R"( Specifies a configuration in YAML/JSON format: -config="{Checks:' *', CheckOptions:{x: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))
static cl::opt< std::string > LineFilter("line-filter", 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))
StringRef FileName
llvm::StringRef Directory
Abstract interface for retrieving various ClangTidy options.
ClangTidyOptions getOptions(llvm::StringRef FileName)
Returns options applying to a specific translation unit with the specified FileName.
static const char OptionsSourceTypeCheckCommandLineOption[]
virtual std::vector< OptionsSource > getRawOptions(llvm::StringRef FileName)=0
Returns an ordered vector of OptionsSources, in order of increasing priority.
std::pair< ClangTidyOptions, std::string > OptionsSource
ClangTidyOptions and its source.
static const char OptionsSourceTypeConfigCommandLineOption[]
static const char OptionsSourceTypeDefaultBinary[]
virtual const ClangTidyGlobalOptions & getGlobalOptions()=0
Returns global options, which are independent of the file.
Implementation of ClangTidyOptions interface, which is used for '-config' command-line option.
std::vector< OptionsSource > getRawOptions(llvm::StringRef FileName) override
Returns an ordered vector of OptionsSources, in order of increasing priority.
Implementation of the ClangTidyOptionsProvider interface, which returns the same options for all file...
const ClangTidyGlobalOptions & getGlobalOptions() override
Returns global options, which are independent of the file.
DefaultOptionsProvider(ClangTidyGlobalOptions GlobalOptions, ClangTidyOptions Options)
std::vector< OptionsSource > getRawOptions(llvm::StringRef FileName) override
Returns an ordered vector of OptionsSources, in order of increasing priority.
std::optional< OptionsSource > tryReadConfigFile(llvm::StringRef Directory)
Try to read configuration files from Directory using registered ConfigHandlers.
llvm::StringMap< OptionsSource > CachedOptions
llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > FS
std::vector< ConfigFileHandler > ConfigFileHandlers
Configuration file handlers listed in the order of priority.
void addRawFileOptions(llvm::StringRef AbsolutePath, std::vector< OptionsSource > &CurOptions)
std::pair< std::string, std::function< llvm::ErrorOr< ClangTidyOptions >(llvm::MemoryBufferRef)> > ConfigFileHandler
Implementation of the ClangTidyOptionsProvider interface, which tries to find a configuration file in...
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::function_ref< void(const llvm::SMDiagnostic &)> DiagCallback
llvm::ErrorOr< ClangTidyOptions > parseConfigurationWithDiags(llvm::MemoryBufferRef Config, DiagCallback Handler)
std::string configurationAsText(const ClangTidyOptions &Options)
Serializes configuration to a YAML-encoded string.
llvm::ErrorOr< ClangTidyOptions > parseConfiguration(llvm::MemoryBufferRef Config)
Parses configuration from JSON and returns ClangTidyOptions or an error.
std::vector< FileFilter > LineFilter
Output warnings from certain line ranges of certain files only.
Helper structure for storing option value with priority of the value.
ClangTidyValue(llvm::StringRef Value, unsigned Priority=0)
unsigned Priority
Priority stores relative precedence of the value loaded from config files to disambiguate local vs gl...
Contains options for clang-tidy.
std::pair< std::string, std::string > StringPair
OptionMap CheckOptions
Key-value mapping used to store check-specific options.
ClangTidyOptions merge(const ClangTidyOptions &Other, unsigned Order) const
Creates a new ClangTidyOptions instance combined from all fields of this instance overridden by the f...
llvm::StringMap< ClangTidyValue > OptionMap
std::optional< bool > InheritParentConfig
Only used in the FileOptionsProvider and ConfigOptionsProvider.
std::vector< std::string > ArgList
std::optional< std::string > HeaderFilterRegex
Output warnings from headers matching this filter.
std::optional< std::string > Checks
Checks filter.
std::optional< std::string > WarningsAsErrors
WarningsAsErrors filter.
std::optional< std::vector< std::string > > ImplementationFileExtensions
File extensions to consider to determine if a given diagnostic is located is located in an implementa...
ClangTidyOptions & mergeWith(const ClangTidyOptions &Other, unsigned Order)
Overwrites all fields in here by the fields of Other that have a value.
std::optional< std::string > User
Specifies the name or e-mail of the user running clang-tidy.
std::optional< std::vector< std::string > > HeaderFileExtensions
File extensions to consider to determine if a given diagnostic is located in a header file.
std::optional< bool > UseColor
Use colors in diagnostics. If missing, it will be auto detected.
std::optional< bool > SystemHeaders
Output warnings from system headers matching HeaderFilterRegex.
static ClangTidyOptions getDefaults()
These options are used for all settings that haven't been overridden by the OptionsProvider.
std::optional< std::string > ExcludeHeaderFilterRegex
Exclude warnings from headers matching this filter, even if they match HeaderFilterRegex.
std::optional< ArgList > ExtraArgsBefore
Add extra compilation arguments to the start of the list.
std::optional< std::string > FormatStyle
Format code around applied fixes with clang-format using this style.
std::optional< ArgList > ExtraArgs
Add extra compilation arguments to the end of the list.
Contains a list of line ranges in a single file.
std::pair< unsigned int, unsigned int > LineRange
LineRange is a pair<start, end> (inclusive).
std::string Name
File name.
std::vector< LineRange > LineRanges
A list of line ranges in this file, for which we show warnings.