1 //===--- Selection.h - What's under the cursor? -------------------*-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 // Many features are triggered at locations/ranges and operate on AST nodes. 9 // (e.g. go-to-definition or code tweaks). 10 // At a high level, such features need to work out which node is the correct 11 // target. 12 // 13 // There are a few levels of ambiguity here: 14 // 15 // Which tokens are included: 16 // int x = one + two; // what should "go to definition" do? 17 // ^^^^^^ 18 // 19 // Same token means multiple things: 20 // string("foo") // class string, or a constructor? 21 // ^ 22 // 23 // Which level of the AST is interesting? 24 // if (err) { // reference to 'err', or operator bool(), 25 // ^ // or the if statement itself? 26 // 27 // Here we build and expose a data structure that allows features to resolve 28 // these ambiguities in an appropriate way: 29 // - we determine which low-level nodes are partly or completely covered 30 // by the selection. 31 // - we expose a tree of the selected nodes and their lexical parents. 32 // 33 // Sadly LSP specifies locations as being between characters, and this causes 34 // some ambiguities we cannot cleanly resolve: 35 // lhs+rhs // targeting '+' or 'lhs'? 36 // ^ // in GUI editors, double-clicking 'lhs' yields this position! 37 // 38 // The best we can do in these cases is try both, which leads to the awkward 39 // SelectionTree::createEach() API. 40 //===----------------------------------------------------------------------===// 41 42 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SELECTION_H 43 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SELECTION_H 44 #include "clang/AST/ASTTypeTraits.h" 45 #include "clang/AST/PrettyPrinter.h" 46 #include "clang/Tooling/Syntax/Tokens.h" 47 #include "llvm/ADT/SmallVector.h" 48 #include <stack> 49 50 namespace clang { 51 namespace clangd { 52 53 // A selection can partially or completely cover several AST nodes. 54 // The SelectionTree contains nodes that are covered, and their parents. 55 // SelectionTree does not contain all AST nodes, rather only: 56 // Decl, Stmt, TypeLoc, NestedNamespaceSpecifierLoc, CXXCtorInitializer. 57 // (These are the nodes with source ranges that fit in DynTypedNode). 58 // 59 // Usually commonAncestor() is the place to start: 60 // - it's the simplest answer to "what node is under the cursor" 61 // - the selected Expr (for example) can be found by walking up the parent 62 // chain and checking Node->ASTNode. 63 // - if you want to traverse the selected nodes, they are all under 64 // commonAncestor() in the tree. 65 // 66 // SelectionTree tries to behave sensibly in the presence of macros, but does 67 // not model any preprocessor concepts: the output is a subset of the AST. 68 // When a macro argument is specifically selected, only its first expansion is 69 // selected in the AST. (Returning a selection forest is unreasonably difficult 70 // for callers to handle correctly.) 71 // 72 // Comments, directives and whitespace are completely ignored. 73 // Semicolons are also ignored, as the AST generally does not model them well. 74 // 75 // The SelectionTree owns the Node structures, but the ASTNode attributes 76 // point back into the AST it was constructed with. 77 class SelectionTree { 78 public: 79 // Create selection trees for the given range, and pass them to Func. 80 // 81 // There may be multiple possible selection trees: 82 // - if the range is empty and borders two tokens, a tree for the right token 83 // and a tree for the left token will be yielded. 84 // - Func should return true on success (stop) and false on failure (continue) 85 // 86 // Always yields at least one tree. If no tokens are touched, it is empty. 87 static bool createEach(ASTContext &AST, const syntax::TokenBuffer &Tokens, 88 unsigned Begin, unsigned End, 89 llvm::function_ref<bool(SelectionTree)> Func); 90 91 // Create a selection tree for the given range. 92 // 93 // Where ambiguous (range is empty and borders two tokens), prefer the token 94 // on the right. 95 static SelectionTree createRight(ASTContext &AST, 96 const syntax::TokenBuffer &Tokens, 97 unsigned Begin, unsigned End); 98 99 // Copies are no good - contain pointers to other nodes. 100 SelectionTree(const SelectionTree &) = delete; 101 SelectionTree &operator=(const SelectionTree &) = delete; 102 // Moves are OK though - internal storage is pointer-stable when moved. 103 SelectionTree(SelectionTree &&) = default; 104 SelectionTree &operator=(SelectionTree &&) = default; 105 106 // Describes to what extent an AST node is covered by the selection. 107 enum Selection : unsigned char { 108 // The AST node owns no characters covered by the selection. 109 // Note that characters owned by children don't count: 110 // if (x == 0) scream(); 111 // ^^^^^^ 112 // The IfStmt would be Unselected because all the selected characters are 113 // associated with its children. 114 // (Invisible nodes like ImplicitCastExpr are always unselected). 115 Unselected, 116 // The AST node owns selected characters, but is not completely covered. 117 Partial, 118 // The AST node owns characters, and is covered by the selection. 119 Complete, 120 }; 121 // An AST node that is implicated in the selection. 122 // (Either selected directly, or some descendant is selected). 123 struct Node { 124 // The parent within the selection tree. nullptr for TranslationUnitDecl. 125 Node *Parent; 126 // Direct children within the selection tree. 127 llvm::SmallVector<const Node *> Children; 128 // The corresponding node from the full AST. 129 DynTypedNode ASTNode; 130 // The extent to which this node is covered by the selection. 131 Selection Selected; 132 // Walk up the AST to get the lexical DeclContext of this Node, which is not 133 // the node itself. 134 const DeclContext &getDeclContext() const; 135 // Printable node kind, like "CXXRecordDecl" or "AutoTypeLoc". 136 std::string kind() const; 137 // If this node is a wrapper with no syntax (e.g. implicit cast), return 138 // its contents. (If multiple wrappers are present, unwraps all of them). 139 const Node &ignoreImplicit() const; 140 // If this node is inside a wrapper with no syntax (e.g. implicit cast), 141 // return that wrapper. (If multiple are present, unwraps all of them). 142 const Node &outerImplicit() const; 143 }; 144 // The most specific common ancestor of all the selected nodes. 145 // Returns nullptr if the common ancestor is the root. 146 // (This is to avoid accidentally traversing the TUDecl and thus preamble). 147 const Node *commonAncestor() const; 148 // The selection node corresponding to TranslationUnitDecl. root()149 const Node &root() const { return *Root; } 150 151 private: 152 // Creates a selection tree for the given range in the main file. 153 // The range includes bytes [Start, End). 154 SelectionTree(ASTContext &AST, const syntax::TokenBuffer &Tokens, 155 unsigned Start, unsigned End); 156 157 std::deque<Node> Nodes; // Stable-pointer storage. 158 const Node *Root; 159 clang::PrintingPolicy PrintPolicy; 160 161 void print(llvm::raw_ostream &OS, const Node &N, int Indent) const; 162 friend llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, 163 const SelectionTree &T) { 164 T.print(OS, T.root(), 1); 165 return OS; 166 } 167 }; 168 169 } // namespace clangd 170 } // namespace clang 171 #endif 172