clang-tools-extra/clangd/SemanticHighlighting.h

   1 //==-- SemanticHighlighting.h - Generating highlights from the AST-- 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 // This file supports semantic highlighting: categorizing tokens in the file so
  10 // that the editor can color/style them differently.
  11 // This is particularly valuable for C++: its complex and context-dependent
  12 // grammar is a challenge for simple syntax-highlighting techniques.
  13 //
  14 // Semantic highlightings are calculated for an AST by visiting every AST node
  15 // and classifying nodes that are interesting to highlight (variables/function
  16 // calls etc.).
  17 //
  18 //===----------------------------------------------------------------------===//
  19
  20 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SEMANTICHIGHLIGHTING_H
  21 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SEMANTICHIGHLIGHTING_H
  22
  23 #include "Protocol.h"
  24 #include "llvm/ADT/StringRef.h"
  25 #include "llvm/Support/raw_ostream.h"
  26
  27 namespace clang {
  28 namespace clangd {
  29 class ParsedAST;
  30
  31 enum class HighlightingKind {
  32   Variable = 0,
  33   LocalVariable,
  34   Parameter,
  35   Function,
  36   Method,
  37   StaticMethod,
  38   Field,
  39   StaticField,
  40   Class,
  41   Interface,
  42   Enum,
  43   EnumConstant,
  44   Typedef,
  45   Type,
  46   Unknown,
  47   Namespace,
  48   TemplateParameter,
  49   Concept,
  50   Primitive,
  51   Macro,
  52   Modifier,
  53   Operator,
  54   Bracket,
  55
  56   // This one is different from the other kinds as it's a line style
  57   // rather than a token style.
  58   InactiveCode,
  59
  60   LastKind = InactiveCode
  61 };
  62
  63 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, HighlightingKind K);
  64 std::optional<HighlightingKind>
  65 highlightingKindFromString(llvm::StringRef Name);
  66
  67 enum class HighlightingModifier {
  68   Declaration,
  69   Definition,
  70   Deprecated,
  71   Deduced,
  72   Readonly,
  73   Static,
  74   Abstract,
  75   Virtual,
  76   DependentName,
  77   DefaultLibrary,
  78   UsedAsMutableReference,
  79   UsedAsMutablePointer,
  80   ConstructorOrDestructor,
  81   UserDefined,
  82
  83   FunctionScope,
  84   ClassScope,
  85   FileScope,
  86   GlobalScope,
  87
  88   LastModifier = GlobalScope
  89 };
  90 static_assert(static_cast<unsigned>(HighlightingModifier::LastModifier) < 32,
  91               "Increase width of modifiers bitfield!");
  92 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, HighlightingModifier K);
  93 std::optional<HighlightingModifier>
  94 highlightingModifierFromString(llvm::StringRef Name);
  95
  96 // Contains all information needed for the highlighting a token.
  97 struct HighlightingToken {
  98   HighlightingKind Kind;
  99   uint32_t Modifiers = 0;
 100   Range R;
 101
 102   HighlightingToken &addModifier(HighlightingModifier M) {
 103     Modifiers |= 1 << static_cast<unsigned>(M);
 104     return *this;
 105   }
 106 };
 107
 108 bool operator==(const HighlightingToken &L, const HighlightingToken &R);
 109 bool operator<(const HighlightingToken &L, const HighlightingToken &R);
 110
 111 // Returns all HighlightingTokens from an AST. Only generates highlights for the
 112 // main AST.
 113 std::vector<HighlightingToken>
 114 getSemanticHighlightings(ParsedAST &AST, bool IncludeInactiveRegionTokens);
 115
 116 std::vector<SemanticToken> toSemanticTokens(llvm::ArrayRef<HighlightingToken>,
 117                                             llvm::StringRef Code);
 118 llvm::StringRef toSemanticTokenType(HighlightingKind Kind);
 119 llvm::StringRef toSemanticTokenModifier(HighlightingModifier Modifier);
 120 std::vector<SemanticTokensEdit> diffTokens(llvm::ArrayRef<SemanticToken> Before,
 121                                            llvm::ArrayRef<SemanticToken> After);
 122
 123 // Returns ranges of the file that are inside an inactive preprocessor branch.
 124 // The preprocessor directives at the beginning and end of a branch themselves
 125 // are not included.
 126 std::vector<Range> getInactiveRegions(ParsedAST &AST);
 127
 128 } // namespace clangd
 129 } // namespace clang
 130
 131 #endif