contrib/llvm/tools/clang/include/clang/Tooling/Inclusions/IncludeStyle.h

   1 //===--- IncludeStyle.h - Style of C++ #include directives -------*- 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_TOOLING_INCLUSIONS_INCLUDESTYLE_H
  11 #define LLVM_CLANG_TOOLING_INCLUSIONS_INCLUDESTYLE_H
  12
  13 #include "llvm/Support/YAMLTraits.h"
  14 #include <string>
  15 #include <vector>
  16
  17 namespace clang {
  18 namespace tooling {
  19
  20 /// Style for sorting and grouping C++ #include directives.
  21 struct IncludeStyle {
  22   /// Styles for sorting multiple ``#include`` blocks.
  23   enum IncludeBlocksStyle {
  24     /// Sort each ``#include`` block separately.
  25     /// \code
  26     ///    #include "b.h"               into      #include "b.h"
  27     ///
  28     ///    #include <lib/main.h>                  #include "a.h"
  29     ///    #include "a.h"                         #include <lib/main.h>
  30     /// \endcode
  31     IBS_Preserve,
  32     /// Merge multiple ``#include`` blocks together and sort as one.
  33     /// \code
  34     ///    #include "b.h"               into      #include "a.h"
  35     ///                                           #include "b.h"
  36     ///    #include <lib/main.h>                  #include <lib/main.h>
  37     ///    #include "a.h"
  38     /// \endcode
  39     IBS_Merge,
  40     /// Merge multiple ``#include`` blocks together and sort as one.
  41     /// Then split into groups based on category priority. See
  42     /// ``IncludeCategories``.
  43     /// \code
  44     ///    #include "b.h"               into      #include "a.h"
  45     ///                                           #include "b.h"
  46     ///    #include <lib/main.h>
  47     ///    #include "a.h"                         #include <lib/main.h>
  48     /// \endcode
  49     IBS_Regroup,
  50   };
  51
  52   /// Dependent on the value, multiple ``#include`` blocks can be sorted
  53   /// as one and divided based on category.
  54   IncludeBlocksStyle IncludeBlocks;
  55
  56   /// See documentation of ``IncludeCategories``.
  57   struct IncludeCategory {
  58     /// The regular expression that this category matches.
  59     std::string Regex;
  60     /// The priority to assign to this category.
  61     int Priority;
  62     bool operator==(const IncludeCategory &Other) const {
  63       return Regex == Other.Regex && Priority == Other.Priority;
  64     }
  65   };
  66
  67   /// Regular expressions denoting the different ``#include`` categories
  68   /// used for ordering ``#includes``.
  69   ///
  70   /// `POSIX extended
  71   /// <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
  72   /// regular expressions are supported.
  73   ///
  74   /// These regular expressions are matched against the filename of an include
  75   /// (including the <> or "") in order. The value belonging to the first
  76   /// matching regular expression is assigned and ``#includes`` are sorted first
  77   /// according to increasing category number and then alphabetically within
  78   /// each category.
  79   ///
  80   /// If none of the regular expressions match, INT_MAX is assigned as
  81   /// category. The main header for a source file automatically gets category 0.
  82   /// so that it is generally kept at the beginning of the ``#includes``
  83   /// (http://llvm.org/docs/CodingStandards.html#include-style). However, you
  84   /// can also assign negative priorities if you have certain headers that
  85   /// always need to be first.
  86   ///
  87   /// To configure this in the .clang-format file, use:
  88   /// \code{.yaml}
  89   ///   IncludeCategories:
  90   ///     - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
  91   ///       Priority:        2
  92   ///     - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
  93   ///       Priority:        3
  94   ///     - Regex:           '<[[:alnum:].]+>'
  95   ///       Priority:        4
  96   ///     - Regex:           '.*'
  97   ///       Priority:        1
  98   /// \endcode
  99   std::vector<IncludeCategory> IncludeCategories;
 100
 101   /// Specify a regular expression of suffixes that are allowed in the
 102   /// file-to-main-include mapping.
 103   ///
 104   /// When guessing whether a #include is the "main" include (to assign
 105   /// category 0, see above), use this regex of allowed suffixes to the header
 106   /// stem. A partial match is done, so that:
 107   /// - "" means "arbitrary suffix"
 108   /// - "$" means "no suffix"
 109   ///
 110   /// For example, if configured to "(_test)?$", then a header a.h would be seen
 111   /// as the "main" include in both a.cc and a_test.cc.
 112   std::string IncludeIsMainRegex;
 113 };
 114
 115 } // namespace tooling
 116 } // namespace clang
 117
 118 LLVM_YAML_IS_SEQUENCE_VECTOR(clang::tooling::IncludeStyle::IncludeCategory)
 119
 120 namespace llvm {
 121 namespace yaml {
 122
 123 template <>
 124 struct MappingTraits<clang::tooling::IncludeStyle::IncludeCategory> {
 125   static void mapping(IO &IO,
 126                       clang::tooling::IncludeStyle::IncludeCategory &Category);
 127 };
 128
 129 template <>
 130 struct ScalarEnumerationTraits<
 131     clang::tooling::IncludeStyle::IncludeBlocksStyle> {
 132   static void
 133   enumeration(IO &IO, clang::tooling::IncludeStyle::IncludeBlocksStyle &Value);
 134 };
 135
 136 } // namespace yaml
 137 } // namespace llvm
 138
 139 #endif // LLVM_CLANG_TOOLING_INCLUSIONS_INCLUDESTYLE_H