clang 19.0.0git
Classes | Public Types | Public Attributes | List of all members
clang::tooling::IncludeStyle Struct Reference

Style for sorting and grouping C++ #include directives. More...

#include "clang/Tooling/Inclusions/IncludeStyle.h"

Classes

struct  IncludeCategory
 See documentation of IncludeCategories. More...
 

Public Types

enum  IncludeBlocksStyle { IBS_Preserve , IBS_Merge , IBS_Regroup }
 Styles for sorting multiple #include blocks. More...
 
enum  MainIncludeCharDiscriminator : int8_t { MICD_Quote , MICD_AngleBracket , MICD_Any }
 Character to consider in the include directives for the main header. More...
 

Public Attributes

IncludeBlocksStyle IncludeBlocks
 Dependent on the value, multiple #include blocks can be sorted as one and divided based on category.
 
std::vector< IncludeCategoryIncludeCategories
 Regular expressions denoting the different #include categories used for ordering #includes.
 
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 the file-to-main-include mapping.
 
MainIncludeCharDiscriminator MainIncludeChar
 When guessing whether a #include is the "main" include, only the include directives that use the specified character are considered.
 

Detailed Description

Style for sorting and grouping C++ #include directives.

Definition at line 20 of file IncludeStyle.h.

Member Enumeration Documentation

◆ IncludeBlocksStyle

Styles for sorting multiple #include blocks.

Enumerator
IBS_Preserve 

Sort each #include block separately.

#include "b.h" into #include "b.h"
#include <lib/main.h> #include "a.h"
#include "a.h" #include <lib/main.h>
int main(int argc, const char **argv)
IBS_Merge 

Merge multiple #include blocks together and sort as one.

#include "b.h" into #include "a.h"
#include "b.h"
#include <lib/main.h> #include <lib/main.h>
#include "a.h"
IBS_Regroup 

Merge multiple #include blocks together and sort as one.

Then split into groups based on category priority. See IncludeCategories.

#include "b.h" into #include "a.h"
#include "b.h"
#include <lib/main.h>
#include "a.h" #include <lib/main.h>

Definition at line 22 of file IncludeStyle.h.

◆ MainIncludeCharDiscriminator

Character to consider in the include directives for the main header.

Enumerator
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.

Definition at line 156 of file IncludeStyle.h.

Member Data Documentation

◆ IncludeBlocks

IncludeBlocksStyle clang::tooling::IncludeStyle::IncludeBlocks

Dependent on the value, multiple #include blocks can be sorted as one and divided based on category.

Version
6

Definition at line 54 of file IncludeStyle.h.

Referenced by clang::format::getChromiumStyle(), clang::format::getGoogleStyle(), clang::format::getLLVMStyle(), llvm::yaml::MappingTraits< FormatStyle >::mapping(), clang::format::FormatStyle::operator==(), and clang::format::sortCppIncludes().

◆ IncludeCategories

std::vector<IncludeCategory> clang::tooling::IncludeStyle::IncludeCategories

Regular expressions denoting the different #include categories used for ordering #includes.

POSIX extended <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>_ regular expressions are supported.

These regular expressions are matched against the filename of an include (including the <> or "") in order. The value belonging to the first matching regular expression is assigned and #includes are sorted first according to increasing category number and then alphabetically within each category.

If none of the regular expressions match, INT_MAX is assigned as category. The main header for a source file automatically gets category 0. so that it is generally kept at the beginning of the #includes (https://llvm.org/docs/CodingStandards.html#include-style). However, you can also assign negative priorities if you have certain headers that always need to be first.

There is a third and optional field SortPriority which can used while IncludeBlocks = IBS_Regroup to define the priority in which #includes should be ordered. The value of Priority defines the order of #include blocks and also allows the grouping of #includes of different priority. SortPriority is set to the value of Priority as default if it is not assigned.

Each regular expression can be marked as case sensitive with the field CaseSensitive, per default it is not.

To configure this in the .clang-format file, use:

IncludeCategories:
- Regex: '^"(llvm|llvm-c|clang|clang-c)/'
Priority: 2
SortPriority: 2
CaseSensitive: true
- Regex: '^((<|")(gtest|gmock|isl|json)/)'
Priority: 3
- Regex: '<[[:alnum:].]+>'
Priority: 4
- Regex: '.*'
Priority: 1
SortPriority: 0
Version
3.8

Definition at line 118 of file IncludeStyle.h.

Referenced by clang::format::getGoogleStyle(), clang::format::getLLVMStyle(), llvm::yaml::MappingTraits< FormatStyle >::mapping(), and clang::format::FormatStyle::operator==().

◆ IncludeIsMainRegex

std::string clang::tooling::IncludeStyle::IncludeIsMainRegex

Specify a regular expression of suffixes that are allowed in the file-to-main-include mapping.

When guessing whether a #include is the "main" include (to assign category 0, see above), use this regex of allowed suffixes to the header stem. A partial match is done, so that:

  • "" means "arbitrary suffix"
  • "$" means "no suffix"

For example, if configured to "(_test)?$", then a header a.h would be seen as the "main" include in both a.cc and a_test.cc.

Version
3.9

Definition at line 132 of file IncludeStyle.h.

Referenced by clang::format::getGoogleStyle(), clang::format::getLLVMStyle(), llvm::yaml::MappingTraits< FormatStyle >::mapping(), and clang::format::FormatStyle::operator==().

◆ IncludeIsMainSourceRegex

std::string clang::tooling::IncludeStyle::IncludeIsMainSourceRegex

Specify a regular expression for files being formatted that are allowed to be considered "main" in the file-to-main-include mapping.

By default, clang-format considers files as "main" only when they end with: .c, .cc, .cpp, .c++, .cxx, .m or .mm extensions. For these files a guessing of "main" include takes place (to assign category 0, see above). This config option allows for additional suffixes and extensions for files to be considered as "main".

For example, if this option is configured to (Impl\.hpp)$, then a file ClassImpl.hpp is considered "main" (in addition to Class.c, Class.cc, Class.cpp and so on) and "main include file" logic will be executed (with IncludeIsMainRegex setting also being respected in later phase). Without this option set, ClassImpl.hpp would not have the main include file put on top before any other include.

Version
10

Definition at line 153 of file IncludeStyle.h.

Referenced by llvm::yaml::MappingTraits< FormatStyle >::mapping(), and clang::format::FormatStyle::operator==().

◆ MainIncludeChar

MainIncludeCharDiscriminator clang::tooling::IncludeStyle::MainIncludeChar

When guessing whether a #include is the "main" include, only the include directives that use the specified character are considered.

Version
19

Definition at line 168 of file IncludeStyle.h.

Referenced by clang::format::getLLVMStyle(), llvm::yaml::MappingTraits< FormatStyle >::mapping(), and clang::format::FormatStyle::operator==().


The documentation for this struct was generated from the following file: