clang  15.0.0git
DeclarationFragments.h
Go to the documentation of this file.
1 //===- ExtractAPI/DeclarationFragments.h ------------------------*- 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 /// \file
10 /// This file defines the Declaration Fragments related classes.
11 ///
12 /// Declaration Fragments represent parts of a symbol declaration tagged with
13 /// syntactic/semantic information.
14 /// See https://github.com/apple/swift-docc-symbolkit
15 ///
16 //===----------------------------------------------------------------------===//
17 
18 #ifndef LLVM_CLANG_EXTRACTAPI_DECLARATION_FRAGMENTS_H
19 #define LLVM_CLANG_EXTRACTAPI_DECLARATION_FRAGMENTS_H
20 
21 #include "clang/AST/ASTContext.h"
22 #include "clang/AST/Decl.h"
23 #include "clang/AST/DeclCXX.h"
24 #include "clang/AST/DeclObjC.h"
25 #include "clang/Lex/MacroInfo.h"
26 #include "llvm/ADT/StringRef.h"
27 #include <vector>
28 
29 namespace clang {
30 namespace extractapi {
31 
32 /// DeclarationFragments is a vector of tagged important parts of a symbol's
33 /// declaration.
34 ///
35 /// The fragments sequence can be joined to form spans of declaration text, with
36 /// attached information useful for purposes like syntax-highlighting etc.
37 /// For example:
38 /// \code
39 /// const -> keyword "const"
40 /// int -> type "int"
41 /// pi; -> identifier "pi"
42 /// \endcode
44 public:
45  DeclarationFragments() = default;
46 
47  /// The kind of a fragment.
48  enum class FragmentKind {
49  /// Unknown fragment kind.
50  None,
51 
52  Keyword,
53  Attribute,
56  Identifier,
57 
58  /// Identifier that refers to a type in the context.
60 
61  /// Parameter that's used as generics in the context. For example template
62  /// parameters.
64 
65  /// External parameters in Objective-C methods.
66  /// For example, \c forKey in
67  /// \code{.m}
68  /// - (void) setValue:(Value)value forKey(Key)key
69  /// \endcode
71 
72  /// Internal/local parameters in Objective-C methods.
73  /// For example, \c key in
74  /// \code{.m}
75  /// - (void) setValue:(Value)value forKey(Key)key
76  /// \endcode
78 
79  Text,
80  };
81 
82  /// Fragment holds information of a single fragment.
83  struct Fragment {
86 
87  /// The USR of the fragment symbol, if applicable.
89 
92  }
93  };
94 
95  const std::vector<Fragment> &getFragments() const { return Fragments; }
96 
97  /// Append a new Fragment to the end of the Fragments.
98  ///
99  /// \returns a reference to the DeclarationFragments object itself after
100  /// appending to chain up consecutive appends.
102  StringRef PreciseIdentifier = "") {
103  if (Kind == FragmentKind::Text && !Fragments.empty() &&
104  Fragments.back().Kind == FragmentKind::Text) {
105  // If appending a text fragment, and the last fragment is also text,
106  // merge into the last fragment.
107  Fragments.back().Spelling.append(Spelling.data(), Spelling.size());
108  } else {
109  Fragments.emplace_back(Spelling, Kind, PreciseIdentifier);
110  }
111  return *this;
112  }
113 
114  /// Append another DeclarationFragments to the end.
115  ///
116  /// Note: \p Other is moved from and cannot be used after a call to this
117  /// method.
118  ///
119  /// \returns a reference to the DeclarationFragments object itself after
120  /// appending to chain up consecutive appends.
122  Fragments.insert(Fragments.end(),
123  std::make_move_iterator(Other.Fragments.begin()),
124  std::make_move_iterator(Other.Fragments.end()));
125  Other.Fragments.clear();
126  return *this;
127  }
128 
129  /// Append a text Fragment of a space character.
130  ///
131  /// \returns a reference to the DeclarationFragments object itself after
132  /// appending to chain up consecutive appends.
134 
135  /// Get the string description of a FragmentKind \p Kind.
136  static StringRef getFragmentKindString(FragmentKind Kind);
137 
138  /// Get the corresponding FragmentKind from string \p S.
139  static FragmentKind parseFragmentKindFromString(StringRef S);
140 
141 private:
142  std::vector<Fragment> Fragments;
143 };
144 
145 /// Store function signature information with DeclarationFragments of the
146 /// return type and parameters.
148 public:
149  FunctionSignature() = default;
150 
151  /// Parameter holds the name and DeclarationFragments of a single parameter.
152  struct Parameter {
155 
157  : Name(Name), Fragments(Fragments) {}
158  };
159 
160  const std::vector<Parameter> &getParameters() const { return Parameters; }
161  const DeclarationFragments &getReturnType() const { return ReturnType; }
162 
164  DeclarationFragments Fragments) {
165  Parameters.emplace_back(Name, Fragments);
166  return *this;
167  }
168 
169  void setReturnType(DeclarationFragments RT) { ReturnType = RT; }
170 
171  /// Determine if the FunctionSignature is empty.
172  ///
173  /// \returns true if the return type DeclarationFragments is empty and there
174  /// is no parameter, otherwise false.
175  bool empty() const {
176  return Parameters.empty() && ReturnType.getFragments().empty();
177  }
178 
179 private:
180  std::vector<Parameter> Parameters;
181  DeclarationFragments ReturnType;
182 };
183 
184 /// A factory class to build DeclarationFragments for different kinds of Decl.
186 public:
187  /// Build DeclarationFragments for a variable declaration VarDecl.
189 
190  /// Build DeclarationFragments for a function declaration FunctionDecl.
192 
193  /// Build DeclarationFragments for an enum constant declaration
194  /// EnumConstantDecl.
195  static DeclarationFragments
197 
198  /// Build DeclarationFragments for an enum declaration EnumDecl.
200 
201  /// Build DeclarationFragments for a field declaration FieldDecl.
203 
204  /// Build DeclarationFragments for a struct record declaration RecordDecl.
206 
207  /// Build DeclarationFragments for an Objective-C category declaration
208  /// ObjCCategoryDecl.
209  static DeclarationFragments
211 
212  /// Build DeclarationFragments for an Objective-C interface declaration
213  /// ObjCInterfaceDecl.
214  static DeclarationFragments
216 
217  /// Build DeclarationFragments for an Objective-C method declaration
218  /// ObjCMethodDecl.
220 
221  /// Build DeclarationFragments for an Objective-C property declaration
222  /// ObjCPropertyDecl.
223  static DeclarationFragments
225 
226  /// Build DeclarationFragments for an Objective-C protocol declaration
227  /// ObjCProtocolDecl.
228  static DeclarationFragments
230 
231  /// Build DeclarationFragments for a macro.
232  ///
233  /// \param Name name of the macro.
234  /// \param MD the associated MacroDirective.
235  static DeclarationFragments getFragmentsForMacro(StringRef Name,
236  const MacroDirective *MD);
237 
238  /// Build DeclarationFragments for a typedef \p TypedefNameDecl.
239  static DeclarationFragments
241 
242  /// Build sub-heading fragments for a NamedDecl.
244 
245  /// Build sub-heading fragments for an Objective-C method.
247 
248  /// Build a sub-heading for macro \p Name.
249  static DeclarationFragments getSubHeadingForMacro(StringRef Name);
250 
251  /// Build FunctionSignature for a function-like declaration \c FunctionT like
252  /// FunctionDecl or ObjCMethodDecl.
253  ///
254  /// The logic and implementation of building a signature for a FunctionDecl
255  /// and an ObjCMethodDecl are exactly the same, but they do not share a common
256  /// base. This template helps reuse the code.
257  template <typename FunctionT>
258  static FunctionSignature getFunctionSignature(const FunctionT *);
259 
260 private:
261  DeclarationFragmentsBuilder() = delete;
262 
263  /// Build DeclarationFragments for a QualType.
264  static DeclarationFragments getFragmentsForType(const QualType, ASTContext &,
266 
267  /// Build DeclarationFragments for a Type.
268  static DeclarationFragments getFragmentsForType(const Type *, ASTContext &,
270 
271  /// Build DeclarationFragments for a NestedNameSpecifier.
272  static DeclarationFragments getFragmentsForNNS(const NestedNameSpecifier *,
273  ASTContext &,
275 
276  /// Build DeclarationFragments for Qualifiers.
277  static DeclarationFragments getFragmentsForQualifiers(const Qualifiers quals);
278 
279  /// Build DeclarationFragments for a parameter variable declaration
280  /// ParmVarDecl.
281  static DeclarationFragments getFragmentsForParam(const ParmVarDecl *);
282 };
283 
284 } // namespace extractapi
285 } // namespace clang
286 
287 #endif // LLVM_CLANG_EXTRACTAPI_DECLARATION_FRAGMENTS_H
clang::ObjCInterfaceDecl
Represents an ObjC class declaration.
Definition: DeclObjC.h:1150
clang::extractapi::DeclarationFragments::appendSpace
DeclarationFragments & appendSpace()
Append a text Fragment of a space character.
Definition: DeclarationFragments.cpp:22
clang::extractapi::DeclarationFragments::FragmentKind::TypeIdentifier
@ TypeIdentifier
Identifier that refers to a type in the context.
string
string(SUBSTRING ${CMAKE_CURRENT_BINARY_DIR} 0 ${PATH_LIB_START} PATH_HEAD) string(SUBSTRING $
Definition: CMakeLists.txt:22
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForEnum
static DeclarationFragments getFragmentsForEnum(const EnumDecl *)
Build DeclarationFragments for an enum declaration EnumDecl.
Definition: DeclarationFragments.cpp:454
clang::extractapi::DeclarationFragments::FragmentKind::NumberLiteral
@ NumberLiteral
clang::extractapi::FunctionSignature::getParameters
const std::vector< Parameter > & getParameters() const
Definition: DeclarationFragments.h:160
clang::NamedDecl
This represents a decl that may have a name.
Definition: Decl.h:247
clang::QualType
A (possibly-)qualified type.
Definition: Type.h:731
clang::NestedNameSpecifier
Represents a C++ nested name specifier, such as "\::std::vector<int>::".
Definition: NestedNameSpecifier.h:50
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForStruct
static DeclarationFragments getFragmentsForStruct(const RecordDecl *)
Build DeclarationFragments for a struct record declaration RecordDecl.
Definition: DeclarationFragments.cpp:485
clang::FieldDecl
Represents a member of a struct/union/class.
Definition: Decl.h:2862
clang::Qualifiers
The collection of all-type qualifiers we support.
Definition: Type.h:147
clang::ParmVarDecl
Represents a parameter to a function.
Definition: Decl.h:1680
DeclCXX.h
clang::extractapi::DeclarationFragments
DeclarationFragments is a vector of tagged important parts of a symbol's declaration.
Definition: DeclarationFragments.h:43
clang::extractapi::DeclarationFragmentsBuilder::getSubHeading
static DeclarationFragments getSubHeading(const NamedDecl *)
Build sub-heading fragments for a NamedDecl.
Definition: DeclarationFragments.cpp:771
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForObjCMethod
static DeclarationFragments getFragmentsForObjCMethod(const ObjCMethodDecl *)
Build DeclarationFragments for an Objective-C method declaration ObjCMethodDecl.
Definition: DeclarationFragments.cpp:569
clang::extractapi::FunctionSignature
Store function signature information with DeclarationFragments of the return type and parameters.
Definition: DeclarationFragments.h:147
clang::extractapi::DeclarationFragments::Fragment
Fragment holds information of a single fragment.
Definition: DeclarationFragments.h:83
clang::extractapi::FunctionSignature::FunctionSignature
FunctionSignature()=default
clang::EnumDecl
Represents an enum.
Definition: Decl.h:3635
clang::Type
The base class of the type hierarchy.
Definition: Type.h:1556
Decl.h
DeclObjC.h
clang::extractapi::DeclarationFragments::FragmentKind::ExternalParam
@ ExternalParam
External parameters in Objective-C methods.
clang::extractapi::DeclarationFragmentsBuilder
A factory class to build DeclarationFragments for different kinds of Decl.
Definition: DeclarationFragments.h:185
clang::extractapi::FunctionSignature::Parameter::Name
std::string Name
Definition: DeclarationFragments.h:153
clang::extractapi::FunctionSignature::Parameter::Fragments
DeclarationFragments Fragments
Definition: DeclarationFragments.h:154
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForField
static DeclarationFragments getFragmentsForField(const FieldDecl *)
Build DeclarationFragments for a field declaration FieldDecl.
Definition: DeclarationFragments.cpp:476
clang::extractapi::FunctionSignature::Parameter::Parameter
Parameter(StringRef Name, DeclarationFragments Fragments)
Definition: DeclarationFragments.h:156
clang::extractapi::DeclarationFragments::Fragment::Kind
FragmentKind Kind
Definition: DeclarationFragments.h:85
clang::extractapi::FunctionSignature::setReturnType
void setReturnType(DeclarationFragments RT)
Definition: DeclarationFragments.h:169
clang::ASTContext
Holds long-lived AST nodes (such as types and decls) that can be referred to throughout the semantic ...
Definition: ASTContext.h:209
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForObjCInterface
static DeclarationFragments getFragmentsForObjCInterface(const ObjCInterfaceDecl *)
Build DeclarationFragments for an Objective-C interface declaration ObjCInterfaceDecl.
Definition: DeclarationFragments.cpp:548
clang::extractapi::DeclarationFragments::getFragments
const std::vector< Fragment > & getFragments() const
Definition: DeclarationFragments.h:95
clang::extractapi::DeclarationFragmentsBuilder::getSubHeadingForMacro
static DeclarationFragments getSubHeadingForMacro(StringRef Name)
Build a sub-heading for macro Name.
Definition: DeclarationFragments.cpp:795
ASTContext.h
clang::VarDecl
Represents a variable declaration or definition.
Definition: Decl.h:874
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForTypedef
static DeclarationFragments getFragmentsForTypedef(const TypedefNameDecl *Decl)
Build DeclarationFragments for a typedef TypedefNameDecl.
Definition: DeclarationFragments.cpp:729
clang::EnumConstantDecl
An instance of this object exists for each enum constant that is defined.
Definition: Decl.h:3077
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForObjCProtocol
static DeclarationFragments getFragmentsForObjCProtocol(const ObjCProtocolDecl *)
Build DeclarationFragments for an Objective-C protocol declaration ObjCProtocolDecl.
Definition: DeclarationFragments.cpp:700
clang::ObjCCategoryDecl
ObjCCategoryDecl - Represents a category declaration.
Definition: DeclObjC.h:2276
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForVar
static DeclarationFragments getFragmentsForVar(const VarDecl *)
Build DeclarationFragments for a variable declaration VarDecl.
Definition: DeclarationFragments.cpp:353
clang::extractapi::DeclarationFragments::Fragment::Spelling
std::string Spelling
Definition: DeclarationFragments.h:84
clang::extractapi::DeclarationFragments::FragmentKind::Identifier
@ Identifier
clang::Decl
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:83
clang::extractapi::FunctionSignature::getReturnType
const DeclarationFragments & getReturnType() const
Definition: DeclarationFragments.h:161
clang::extractapi::FunctionSignature::empty
bool empty() const
Determine if the FunctionSignature is empty.
Definition: DeclarationFragments.h:175
clang::ObjCPropertyDecl
Represents one property declaration in an Objective-C interface.
Definition: DeclObjC.h:732
clang::extractapi::DeclarationFragments::append
DeclarationFragments & append(StringRef Spelling, FragmentKind Kind, StringRef PreciseIdentifier="")
Append a new Fragment to the end of the Fragments.
Definition: DeclarationFragments.h:101
clang::extractapi::DeclarationFragments::Fragment::Fragment
Fragment(StringRef Spelling, FragmentKind Kind, StringRef PreciseIdentifier)
Definition: DeclarationFragments.h:90
clang::extractapi::FunctionSignature::Parameter
Parameter holds the name and DeclarationFragments of a single parameter.
Definition: DeclarationFragments.h:152
clang::extractapi::DeclarationFragments::append
DeclarationFragments & append(DeclarationFragments &&Other)
Append another DeclarationFragments to the end.
Definition: DeclarationFragments.h:121
clang::extractapi::DeclarationFragments::FragmentKind::Keyword
@ Keyword
clang::extractapi::DeclarationFragments::FragmentKind::Text
@ Text
clang::ObjCPropertyAttribute::Kind
Kind
Definition: DeclObjCCommon.h:22
clang::ObjCMethodDecl
ObjCMethodDecl - Represents an instance or class method declaration.
Definition: DeclObjC.h:139
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForMacro
static DeclarationFragments getFragmentsForMacro(StringRef Name, const MacroDirective *MD)
Build DeclarationFragments for a macro.
Definition: DeclarationFragments.cpp:499
clang
Definition: CalledOnceCheck.h:17
clang::extractapi::DeclarationFragments::DeclarationFragments
DeclarationFragments()=default
clang::extractapi::DeclarationFragments::getFragmentKindString
static StringRef getFragmentKindString(FragmentKind Kind)
Get the string description of a FragmentKind Kind.
Definition: DeclarationFragments.cpp:39
MacroInfo.h
clang::MacroDirective
Encapsulates changes to the "macros namespace" (the location where the macro name became active,...
Definition: MacroInfo.h:314
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForEnumConstant
static DeclarationFragments getFragmentsForEnumConstant(const EnumConstantDecl *)
Build DeclarationFragments for an enum constant declaration EnumConstantDecl.
Definition: DeclarationFragments.cpp:446
clang::ObjCProtocolDecl
Represents an Objective-C protocol declaration.
Definition: DeclObjC.h:2052
clang::extractapi::DeclarationFragments::FragmentKind::None
@ None
Unknown fragment kind.
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForObjCCategory
static DeclarationFragments getFragmentsForObjCCategory(const ObjCCategoryDecl *)
Build DeclarationFragments for an Objective-C category declaration ObjCCategoryDecl.
Definition: DeclarationFragments.cpp:529
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForObjCProperty
static DeclarationFragments getFragmentsForObjCProperty(const ObjCPropertyDecl *)
Build DeclarationFragments for an Objective-C property declaration ObjCPropertyDecl.
Definition: DeclarationFragments.cpp:613
clang::TypedefNameDecl
Base class for declarations which introduce a typedef-name.
Definition: Decl.h:3207
clang::extractapi::DeclarationFragmentsBuilder::getFunctionSignature
static FunctionSignature getFunctionSignature(const FunctionT *)
Build FunctionSignature for a function-like declaration FunctionT like FunctionDecl or ObjCMethodDecl...
Definition: DeclarationFragments.cpp:745
clang::extractapi::DeclarationFragments::Fragment::PreciseIdentifier
std::string PreciseIdentifier
The USR of the fragment symbol, if applicable.
Definition: DeclarationFragments.h:88
clang::extractapi::DeclarationFragments::FragmentKind::GenericParameter
@ GenericParameter
Parameter that's used as generics in the context.
clang::extractapi::DeclarationFragments::FragmentKind
FragmentKind
The kind of a fragment.
Definition: DeclarationFragments.h:48
clang::extractapi::FunctionSignature::addParameter
FunctionSignature & addParameter(StringRef Name, DeclarationFragments Fragments)
Definition: DeclarationFragments.h:163
clang::extractapi::DeclarationFragments::FragmentKind::StringLiteral
@ StringLiteral
clang::extractapi::DeclarationFragments::FragmentKind::Attribute
@ Attribute
clang::extractapi::DeclarationFragments::FragmentKind::InternalParam
@ InternalParam
Internal/local parameters in Objective-C methods.
clang::FunctionDecl
Represents a function declaration or definition.
Definition: Decl.h:1872
clang::RecordDecl
Represents a struct/union/class.
Definition: Decl.h:3908
clang::extractapi::DeclarationFragments::parseFragmentKindFromString
static FragmentKind parseFragmentKindFromString(StringRef S)
Get the corresponding FragmentKind from string S.
Definition: DeclarationFragments.cpp:70
clang::extractapi::DeclarationFragmentsBuilder::getFragmentsForFunction
static DeclarationFragments getFragmentsForFunction(const FunctionDecl *)
Build DeclarationFragments for a function declaration FunctionDecl.
Definition: DeclarationFragments.cpp:404