172 lines · c
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-exception6//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 correct11// 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 resolve28// these ambiguities in an appropriate way:29// - we determine which low-level nodes are partly or completely covered30// 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 causes34// 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 awkward39// SelectionTree::createEach() API.40//===----------------------------------------------------------------------===//41 42#ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_SELECTION_H43#define LLVM_CLANG_TOOLS_EXTRA_CLANGD_SELECTION_H44#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 50namespace clang {51namespace 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 parent62// chain and checking Node->ASTNode.63// - if you want to traverse the selected nodes, they are all under64// commonAncestor() in the tree.65//66// SelectionTree tries to behave sensibly in the presence of macros, but does67// 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 is69// selected in the AST. (Returning a selection forest is unreasonably difficult70// 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 attributes76// point back into the AST it was constructed with.77class SelectionTree {78public: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 token83 // 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 token94 // 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 are113 // 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 not133 // 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), return138 // 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.149 const Node &root() const { return *Root; }150 151private: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 clangd170} // namespace clang171#endif172