clang 24.0.0git
IncludeStyle.h
Go to the documentation of this file.
1//===--- IncludeStyle.h - Style of C++ #include directives -------*- 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_TOOLING_INCLUSIONS_INCLUDESTYLE_H
10#define LLVM_CLANG_TOOLING_INCLUSIONS_INCLUDESTYLE_H
11
12#include "llvm/Support/YAMLTraits.h"
13#include <string>
14#include <vector>
15
16namespace clang {
17namespace tooling {
18
19/// Style for sorting and grouping C++ #include directives.
21 /// Styles for sorting multiple `#include` blocks.
23 /// Sort each `#include` block separately.
24 /// \code
25 /// #include "b.h" into #include "b.h"
26 ///
27 /// #include <lib/main.h> #include "a.h"
28 /// #include "a.h" #include <lib/main.h>
29 /// \endcode
31 /// Merge multiple `#include` blocks together and sort as one.
32 /// \code
33 /// #include "b.h" into #include "a.h"
34 /// #include "b.h"
35 /// #include <lib/main.h> #include <lib/main.h>
36 /// #include "a.h"
37 /// \endcode
39 /// Merge multiple `#include` blocks together and sort as one.
40 /// Then split into groups based on category priority. See
41 /// `IncludeCategories`.
42 /// \code
43 /// #include "b.h" into #include "a.h"
44 /// #include "b.h"
45 /// #include <lib/main.h>
46 /// #include "a.h" #include <lib/main.h>
47 /// \endcode
49 /// Merge multiple `#include` blocks together and sort as one.
50 /// It's first grouped by category priority, then by top-level directory
51 /// within each category.
52 /// \code
53 /// #include "b/b.h" into #include "a/a.h"
54 /// #include "a/b.h" #include "a/b.h"
55 /// #include "a/a.h"
56 /// #include "b/b.h"
57 /// \endcode
59 };
60
61 /// Dependent on the value, multiple `#include` blocks can be sorted
62 /// as one and divided based on category.
63 /// \version 6
65
66 /// See documentation of `IncludeCategories`.
68 /// The regular expression that this category matches.
69 std::string Regex;
70 /// The priority to assign to this category.
72 /// The custom priority to sort before grouping.
74 /// If the regular expression is case sensitive.
76 bool operator==(const IncludeCategory &Other) const {
77 return Regex == Other.Regex && Priority == Other.Priority &&
78 RegexIsCaseSensitive == Other.RegexIsCaseSensitive;
79 }
80 };
81
82 /// Regular expressions denoting the different `#include` categories
83 /// used for ordering `#includes`.
84 ///
85 /// [POSIX
86 /// extended](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html)
87 /// regular expressions are supported.
88 ///
89 /// These regular expressions are matched against the filename of an include
90 /// (including the <> or "") in order. The value belonging to the first
91 /// matching regular expression is assigned and `#includes` are sorted first
92 /// according to increasing category number and then alphabetically within
93 /// each category.
94 ///
95 /// If none of the regular expressions match, INT_MAX is assigned as
96 /// category. The main header for a source file automatically gets category 0.
97 /// so that it is generally kept at the beginning of the `#includes`
98 /// (see [LLVM
99 /// style](https://llvm.org/docs/CodingStandards.html#include-style)).
100 /// However, you can also assign negative priorities if you have certain
101 /// headers that always need to be first.
102 ///
103 /// There is a third and optional field `SortPriority` which can used while
104 /// `IncludeBlocks = IBS_Regroup` to define the priority in which
105 /// `#includes` should be ordered. The value of `Priority` defines the
106 /// order of `#include blocks` and also allows the grouping of `#includes`
107 /// of different priority. `SortPriority` is set to the value of
108 /// `Priority` as default if it is not assigned.
109 ///
110 /// Each regular expression can be marked as case sensitive with the field
111 /// `CaseSensitive`, per default it is not.
112 ///
113 /// To configure this in the .clang-format file, use:
114 /// \code{.yaml}
115 /// IncludeCategories:
116 /// - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
117 /// Priority: 2
118 /// SortPriority: 2
119 /// CaseSensitive: true
120 /// - Regex: '^((<|")(gtest|gmock|isl|json)/)'
121 /// Priority: 3
122 /// - Regex: '<[[:alnum:].]+>'
123 /// Priority: 4
124 /// - Regex: '.*'
125 /// Priority: 1
126 /// SortPriority: 0
127 /// \endcode
128 /// \version 3.8
129 std::vector<IncludeCategory> IncludeCategories;
130
131 /// Specify a regular expression of suffixes that are allowed in the
132 /// file-to-main-include mapping.
133 ///
134 /// When guessing whether a #include is the "main" include (to assign
135 /// category 0, see above), use this regex of allowed suffixes to the header
136 /// stem. A partial match is done, so that:
137 /// * `""` means "arbitrary suffix"
138 /// * `"$"` means "no suffix"
139 ///
140 /// For example, if configured to `"(_test)?$"`, then a header a.h would be
141 /// seen as the "main" include in both a.cc and a_test.cc.
142 /// \version 3.9
143 std::string IncludeIsMainRegex;
144
145 /// Specify a regular expression for files being formatted
146 /// that are allowed to be considered "main" in the
147 /// file-to-main-include mapping.
148 ///
149 /// By default, clang-format considers files as "main" only when they end
150 /// with: `.c`, `.cc`, `.cpp`, `.c++`, `.cxx`, `.m` or `.mm`
151 /// extensions.
152 /// For these files a guessing of "main" include takes place
153 /// (to assign category 0, see above). This config option allows for
154 /// additional suffixes and extensions for files to be considered as "main".
155 ///
156 /// For example, if this option is configured to `(Impl\.hpp)$`,
157 /// then a file `ClassImpl.hpp` is considered "main" (in addition to
158 /// `Class.c`, `Class.cc`, `Class.cpp` and so on) and "main
159 /// include file" logic will be executed (with *IncludeIsMainRegex* setting
160 /// also being respected in later phase). Without this option set,
161 /// `ClassImpl.hpp` would not have the main include file put on top
162 /// before any other include.
163 /// \version 10
164 std::string IncludeIsMainSourceRegex;
166 /// Character to consider in the include directives for the main header.
168 /// Main include uses quotes: `#include "foo.hpp"` (the default).
170 /// Main include uses angle brackets: `#include <foo.hpp>`.
172 /// Main include uses either quotes or angle brackets.
174 };
175
176 /// When guessing whether a #include is the "main" include, only the include
177 /// directives that use the specified character are considered.
178 /// \version 19
180};
181
182} // namespace tooling
183} // namespace clang
184
185LLVM_YAML_IS_SEQUENCE_VECTOR(clang::tooling::IncludeStyle::IncludeCategory)
186
187namespace llvm {
188namespace yaml {
189
190template <>
191struct MappingTraits<clang::tooling::IncludeStyle::IncludeCategory> {
192 static void mapping(IO &IO,
194};
195
196template <>
197struct ScalarEnumerationTraits<
198 clang::tooling::IncludeStyle::IncludeBlocksStyle> {
199 static void
201};
202
203template <>
204struct ScalarEnumerationTraits<
205 clang::tooling::IncludeStyle::MainIncludeCharDiscriminator> {
206 static void enumeration(
207 IO &IO,
209};
210
211} // namespace yaml
212} // namespace llvm
213
214#endif // LLVM_CLANG_TOOLING_INCLUSIONS_INCLUDESTYLE_H
Top level wrappers for InstallAPI frontend operations.
Diagnostic wrappers for TextAPI types for error reporting.
Definition Dominators.h:30
int32_t uint32_t uint32_t __builtin_riscv_mhracc_i32 __builtin_riscv_mhraccu_u32 __builtin_riscv_mhraccsu_i32 __builtin_riscv_mulqr_i32 __builtin_riscv_mqrwacc_i64 int8_t
See documentation of IncludeCategories.
int Priority
The priority to assign to this category.
bool RegexIsCaseSensitive
If the regular expression is case sensitive.
int SortPriority
The custom priority to sort before grouping.
bool operator==(const IncludeCategory &Other) const
std::string Regex
The regular expression that this category matches.
Style for sorting and grouping C++ include directives.
MainIncludeCharDiscriminator MainIncludeChar
When guessing whether a include is the "main" include, only the include directives that use the speci...
IncludeBlocksStyle
Styles for sorting multiple #include blocks.
@ IBS_Preserve
Sort each #include block separately.
@ IBS_RegroupByDirectory
Merge multiple #include blocks together and sort as one.
@ IBS_Regroup
Merge multiple #include blocks together and sort as one.
@ IBS_Merge
Merge multiple #include blocks together and sort as one.
std::string IncludeIsMainRegex
Specify a regular expression of suffixes that are allowed in the file-to-main-include mapping.
std::string IncludeIsMainSourceRegex
Specify a regular expression for files being formatted that are allowed to be considered "main" in th...
MainIncludeCharDiscriminator
Character to consider in the include directives for the main header.
@ MICD_Quote
Main include uses quotes: #include "foo.hpp" (the default).
@ MICD_AngleBracket
Main include uses angle brackets: #include <foo.hpp>.
@ MICD_Any
Main include uses either quotes or angle brackets.
IncludeBlocksStyle IncludeBlocks
Dependent on the value, multiple #include blocks can be sorted as one and divided based on category.
std::vector< IncludeCategory > IncludeCategories
Regular expressions denoting the different #include categories used for ordering #includes.
static void mapping(IO &IO, clang::tooling::IncludeStyle::IncludeCategory &Category)
static void enumeration(IO &IO, clang::tooling::IncludeStyle::IncludeBlocksStyle &Value)
static void enumeration(IO &IO, clang::tooling::IncludeStyle::MainIncludeCharDiscriminator &Value)