LLDB mainline
Language.h
Go to the documentation of this file.
1//===-- Language.h ---------------------------------------------------*- C++
2//-*-===//
3//
4// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5// See https://llvm.org/LICENSE.txt for license information.
6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef LLDB_TARGET_LANGUAGE_H
11#define LLDB_TARGET_LANGUAGE_H
12
13#include <functional>
14#include <memory>
15#include <set>
16#include <vector>
17
24#include "lldb/lldb-private.h"
25#include "lldb/lldb-public.h"
26
27namespace lldb_private {
28
30public:
32
33 static llvm::StringRef GetSettingName();
34
36};
37
38class Language : public PluginInterface {
39public:
41 public:
42 class Result {
43 public:
44 virtual bool IsValid() = 0;
45
46 virtual bool DumpToStream(Stream &stream,
47 bool print_help_if_available) = 0;
48
49 virtual ~Result() = default;
50 };
51
52 typedef std::set<std::unique_ptr<Result>> ResultSet;
53
54 virtual ~TypeScavenger() = default;
55
56 size_t Find(ExecutionContextScope *exe_scope, const char *key,
57 ResultSet &results, bool append = true);
58
59 protected:
60 TypeScavenger() = default;
61
62 virtual bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
63 ResultSet &results) = 0;
64 };
65
68 public:
70
71 bool IsValid() override { return m_compiler_type.IsValid(); }
72
73 bool DumpToStream(Stream &stream, bool print_help_if_available) override {
74 if (IsValid()) {
76 stream.EOL();
77 return true;
78 }
79 return false;
80 }
81
82 ~Result() override = default;
83
84 private:
86 };
87
88 protected:
90
91 ~ImageListTypeScavenger() override = default;
92
93 // is this type something we should accept? it's usually going to be a
94 // filter by language + maybe some sugar tweaking
95 // returning an empty type means rejecting this candidate entirely;
96 // any other result will be accepted as a valid match
98
99 bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
100 ResultSet &results) override;
101 };
102
103 template <typename... ScavengerTypes>
105 public:
107 for (std::shared_ptr<TypeScavenger> scavenger : { std::shared_ptr<TypeScavenger>(new ScavengerTypes())... }) {
108 if (scavenger)
109 m_scavengers.push_back(scavenger);
110 }
111 }
112 protected:
113 bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
114 ResultSet &results) override {
115 const bool append = false;
116 for (auto& scavenger : m_scavengers) {
117 if (scavenger && scavenger->Find(exe_scope, key, results, append))
118 return true;
119 }
120 return false;
121 }
122 private:
123 std::vector<std::shared_ptr<TypeScavenger>> m_scavengers;
124 };
125
126 template <typename... ScavengerTypes>
128 public:
130 for (std::shared_ptr<TypeScavenger> scavenger : { std::shared_ptr<TypeScavenger>(new ScavengerTypes())... }) {
131 if (scavenger)
132 m_scavengers.push_back(scavenger);
133 }
134 }
135 protected:
136 bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
137 ResultSet &results) override {
138 const bool append = true;
139 bool success = false;
140 for (auto& scavenger : m_scavengers) {
141 if (scavenger)
142 success = scavenger->Find(exe_scope, key, results, append) || success;
143 }
144 return success;
145 }
146 private:
147 std::vector<std::shared_ptr<TypeScavenger>> m_scavengers;
148 };
149
151 eName,
154 };
155
156 ~Language() override;
157
158 static Language *FindPlugin(lldb::LanguageType language);
159
160 /// Returns the Language associated with the given file path or a nullptr
161 /// if there is no known language.
162 static Language *FindPlugin(llvm::StringRef file_path);
163
164 static Language *FindPlugin(lldb::LanguageType language,
165 llvm::StringRef file_path);
166
167 // return false from callback to stop iterating
168 static void ForEach(std::function<bool(Language *)> callback);
169
171
172 // Implement this function to return the user-defined entry point name
173 // for the language.
174 virtual llvm::StringRef GetUserEntryPointName() const { return {}; }
175
176 virtual bool IsTopLevelFunction(Function &function);
177
178 virtual bool IsSourceFile(llvm::StringRef file_path) const = 0;
179
180 virtual const Highlighter *GetHighlighter() const { return nullptr; }
181
183
185
187
190
191 virtual std::vector<FormattersMatchCandidate>
193 lldb::DynamicValueType use_dynamic);
194
195 virtual std::unique_ptr<TypeScavenger> GetTypeScavenger();
196
197 virtual const char *GetLanguageSpecificTypeLookupHelp();
198
201 lldb::FunctionNameType m_type;
202
203 public:
204 MethodNameVariant(ConstString name, lldb::FunctionNameType type)
205 : m_name(name), m_type(type) {}
206 ConstString GetName() const { return m_name; }
207 lldb::FunctionNameType GetType() const { return m_type; }
208 };
209 // If a language can have more than one possible name for a method, this
210 // function can be used to enumerate them. This is useful when doing name
211 // lookups.
212 virtual std::vector<Language::MethodNameVariant>
214 return std::vector<Language::MethodNameVariant>();
215 };
216
217 /// Returns true iff the given symbol name is compatible with the mangling
218 /// scheme of this language.
219 ///
220 /// This function should only return true if there is a high confidence
221 /// that the name actually belongs to this language.
222 virtual bool SymbolNameFitsToLanguage(Mangled name) const { return false; }
223
224 /// An individual data formatter may apply to several types and cross language
225 /// boundaries. Each of those languages may want to customize the display of
226 /// values of said types by appending proper prefix/suffix information in
227 /// language-specific ways. This function returns that prefix and suffix.
228 ///
229 /// \param[in] type_hint
230 /// A StringRef used to determine what the prefix and suffix should be. It
231 /// is called a hint because some types may have multiple variants for which
232 /// the prefix and/or suffix may vary.
233 ///
234 /// \return
235 /// A std::pair<StringRef, StringRef>, the first being the prefix and the
236 /// second being the suffix. They may be empty.
237 virtual std::pair<llvm::StringRef, llvm::StringRef>
238 GetFormatterPrefixSuffix(llvm::StringRef type_hint);
239
240 // When looking up functions, we take a user provided string which may be a
241 // partial match to the full demangled name and compare it to the actual
242 // demangled name to see if it matches as much as the user specified. An
243 // example of this is if the user provided A::my_function, but the
244 // symbol was really B::A::my_function. We want that to be
245 // a match. But we wouldn't want this to match AnotherA::my_function. The
246 // user is specifying a truncated path, not a truncated set of characters.
247 // This function does a language-aware comparison for those purposes.
248 virtual bool DemangledNameContainsPath(llvm::StringRef path,
249 ConstString demangled) const;
250
251 // if a language has a custom format for printing variable declarations that
252 // it wants LLDB to honor it should return an appropriate closure here
254
255 virtual LazyBool IsLogicalTrue(ValueObject &valobj, Status &error);
256
257 // for a ValueObject of some "reference type", if the value points to the
258 // nil/null object, this method returns true
259 virtual bool IsNilReference(ValueObject &valobj);
260
261 /// Returns the summary string for ValueObjects for which IsNilReference() is
262 /// true.
263 virtual llvm::StringRef GetNilReferenceSummaryString() { return {}; }
264
265 // for a ValueObject of some "reference type", if the language provides a
266 // technique to decide whether the reference has ever been assigned to some
267 // object, this method will return true if such detection is possible, and if
268 // the reference has never been assigned
269 virtual bool IsUninitializedReference(ValueObject &valobj);
270
271 virtual bool GetFunctionDisplayName(const SymbolContext *sc,
272 const ExecutionContext *exe_ctx,
273 FunctionNameRepresentation representation,
274 Stream &s);
275
276 virtual ConstString
278 if (ConstString demangled = mangled.GetDemangledName())
279 return demangled;
280
281 return mangled.GetMangledName();
282 }
283
285 return mangled.GetDemangledName();
286 }
287
288 virtual void GetExceptionResolverDescription(bool catch_on, bool throw_on,
289 Stream &s);
290
291 static void GetDefaultExceptionResolverDescription(bool catch_on,
292 bool throw_on, Stream &s);
293
294 // These are accessors for general information about the Languages lldb knows
295 // about:
296
297 static lldb::LanguageType
298 GetLanguageTypeFromString(const char *string) = delete;
299 static lldb::LanguageType GetLanguageTypeFromString(llvm::StringRef string);
300
301 static const char *GetNameForLanguageType(lldb::LanguageType language);
302
303 static void PrintAllLanguages(Stream &s, const char *prefix,
304 const char *suffix);
305
306 /// Prints to the specified stream 's' each language type that the
307 /// current target supports for expression evaluation.
308 ///
309 /// \param[out] s Stream to which the language types are written.
310 /// \param[in] prefix String that is prepended to the language type.
311 /// \param[in] suffix String that is appended to the language type.
313 llvm::StringRef prefix,
314 llvm::StringRef suffix);
315
316 // return false from callback to stop iterating
317 static void ForAllLanguages(std::function<bool(lldb::LanguageType)> callback);
318
319 static bool LanguageIsCPlusPlus(lldb::LanguageType language);
320
321 static bool LanguageIsObjC(lldb::LanguageType language);
322
323 static bool LanguageIsC(lldb::LanguageType language);
324
325 /// Equivalent to \c LanguageIsC||LanguageIsObjC||LanguageIsCPlusPlus.
326 static bool LanguageIsCFamily(lldb::LanguageType language);
327
328 static bool LanguageIsPascal(lldb::LanguageType language);
329
330 // return the primary language, so if LanguageIsC(l), return eLanguageTypeC,
331 // etc.
333
334 static std::set<lldb::LanguageType> GetSupportedLanguages();
335
339
341
342 // Given a mangled function name, calculates some alternative manglings since
343 // the compiler mangling may not line up with the symbol we are expecting.
344 virtual std::vector<ConstString>
346 return std::vector<ConstString>();
347 }
348
349 virtual ConstString
351 const SymbolContext &sym_ctx) const {
352 return ConstString();
353 }
354
355 virtual llvm::StringRef GetInstanceVariableName() { return {}; }
356
357 /// Returns true if this SymbolContext should be ignored when setting
358 /// breakpoints by line (number or regex). Helpful for languages that create
359 /// artificial functions without meaningful user code associated with them
360 /// (e.g. code that gets expanded in late compilation stages, like by
361 /// CoroSplitter).
362 virtual bool IgnoreForLineBreakpoints(const SymbolContext &) const {
363 return false;
364 }
365
366protected:
367 // Classes that inherit from Language can see and modify these
368
370
371private:
372 Language(const Language &) = delete;
373 const Language &operator=(const Language &) = delete;
374};
375
376} // namespace lldb_private
377
378#endif // LLDB_TARGET_LANGUAGE_H
static llvm::raw_ostream & error(Stream &strm)
Generic representation of a type in a programming language.
Definition: CompilerType.h:36
void DumpTypeDescription(lldb::DescriptionLevel level=lldb::eDescriptionLevelFull) const
Dump to stdout.
A uniqued constant string class.
Definition: ConstString.h:40
std::function< bool(ConstString, ConstString, const DumpValueObjectOptions &, Stream &)> DeclPrintingHelper
"lldb/Target/ExecutionContextScope.h" Inherit from this if your object can reconstruct its execution ...
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
A class that describes a function.
Definition: Function.h:399
HardcodedFormatterFinders< SyntheticChildren > HardcodedSyntheticFinder
Definition: FormatClasses.h:42
HardcodedFormatterFinders< TypeSummaryImpl > HardcodedSummaryFinder
Definition: FormatClasses.h:41
HardcodedFormatterFinders< TypeFormatImpl > HardcodedFormatFinder
Definition: FormatClasses.h:40
Annotates source code with color attributes.
Definition: Highlighter.h:91
static llvm::StringRef GetSettingName()
Definition: Language.cpp:45
bool GetEnableFilterForLineBreakpoints() const
Definition: Language.cpp:55
bool Find_Impl(ExecutionContextScope *exe_scope, const char *key, ResultSet &results) override
Definition: Language.h:113
std::vector< std::shared_ptr< TypeScavenger > > m_scavengers
Definition: Language.h:123
bool DumpToStream(Stream &stream, bool print_help_if_available) override
Definition: Language.h:73
virtual CompilerType AdjustForInclusion(CompilerType &candidate)=0
bool Find_Impl(ExecutionContextScope *exe_scope, const char *key, ResultSet &results) override
Definition: Language.cpp:461
MethodNameVariant(ConstString name, lldb::FunctionNameType type)
Definition: Language.h:204
lldb::FunctionNameType GetType() const
Definition: Language.h:207
virtual bool DumpToStream(Stream &stream, bool print_help_if_available)=0
std::set< std::unique_ptr< Result > > ResultSet
Definition: Language.h:52
virtual bool Find_Impl(ExecutionContextScope *exe_scope, const char *key, ResultSet &results)=0
size_t Find(ExecutionContextScope *exe_scope, const char *key, ResultSet &results, bool append=true)
Definition: Language.cpp:442
std::vector< std::shared_ptr< TypeScavenger > > m_scavengers
Definition: Language.h:147
bool Find_Impl(ExecutionContextScope *exe_scope, const char *key, ResultSet &results) override
Definition: Language.h:136
virtual bool IsSourceFile(llvm::StringRef file_path) const =0
static void PrintSupportedLanguagesForExpressions(Stream &s, llvm::StringRef prefix, llvm::StringRef suffix)
Prints to the specified stream 's' each language type that the current target supports for expression...
Definition: Language.cpp:273
static LanguageSet GetLanguagesSupportingREPLs()
Definition: Language.cpp:432
static LanguageSet GetLanguagesSupportingTypeSystems()
Definition: Language.cpp:424
virtual ConstString GetDisplayDemangledName(Mangled mangled) const
Definition: Language.h:284
virtual std::vector< FormattersMatchCandidate > GetPossibleFormattersMatches(ValueObject &valobj, lldb::DynamicValueType use_dynamic)
Definition: Language.cpp:179
virtual lldb::TypeCategoryImplSP GetFormatters()
Definition: Language.cpp:163
virtual bool IgnoreForLineBreakpoints(const SymbolContext &) const
Returns true if this SymbolContext should be ignored when setting breakpoints by line (number or rege...
Definition: Language.h:362
virtual llvm::StringRef GetInstanceVariableName()
Definition: Language.h:355
static Language * FindPlugin(lldb::LanguageType language)
Definition: Language.cpp:84
static const char * GetNameForLanguageType(lldb::LanguageType language)
Definition: Language.cpp:266
virtual DumpValueObjectOptions::DeclPrintingHelper GetDeclPrintingHelper()
Definition: Language.cpp:501
static LanguageProperties & GetGlobalLanguageProperties()
Definition: Language.cpp:40
virtual LazyBool IsLogicalTrue(ValueObject &valobj, Status &error)
Definition: Language.cpp:505
virtual ConstString GetDemangledFunctionNameWithoutArguments(Mangled mangled) const
Definition: Language.h:277
virtual const char * GetLanguageSpecificTypeLookupHelp()
Definition: Language.cpp:440
virtual std::pair< llvm::StringRef, llvm::StringRef > GetFormatterPrefixSuffix(llvm::StringRef type_hint)
An individual data formatter may apply to several types and cross language boundaries.
Definition: Language.cpp:489
static bool LanguageIsC(lldb::LanguageType language)
Definition: Language.cpp:324
virtual lldb::LanguageType GetLanguageType() const =0
virtual HardcodedFormatters::HardcodedSummaryFinder GetHardcodedSummaries()
Definition: Language.cpp:169
virtual std::vector< Language::MethodNameVariant > GetMethodNameVariants(ConstString method_name) const
Definition: Language.h:213
static void GetDefaultExceptionResolverDescription(bool catch_on, bool throw_on, Stream &s)
Definition: Language.cpp:525
virtual bool DemangledNameContainsPath(llvm::StringRef path, ConstString demangled) const
Definition: Language.cpp:493
virtual std::vector< ConstString > GenerateAlternateFunctionManglings(const ConstString mangled) const
Definition: Language.h:345
static bool LanguageIsCPlusPlus(lldb::LanguageType language)
Definition: Language.cpp:299
static lldb::LanguageType GetPrimaryLanguage(lldb::LanguageType language)
Definition: Language.cpp:365
const Language & operator=(const Language &)=delete
virtual ConstString FindBestAlternateFunctionMangledName(const Mangled mangled, const SymbolContext &sym_ctx) const
Definition: Language.h:350
static bool LanguageIsPascal(lldb::LanguageType language)
Definition: Language.cpp:356
virtual bool IsNilReference(ValueObject &valobj)
Definition: Language.cpp:509
static void ForAllLanguages(std::function< bool(lldb::LanguageType)> callback)
Definition: Language.cpp:291
virtual bool IsUninitializedReference(ValueObject &valobj)
Definition: Language.cpp:511
virtual bool GetFunctionDisplayName(const SymbolContext *sc, const ExecutionContext *exe_ctx, FunctionNameRepresentation representation, Stream &s)
Definition: Language.cpp:513
virtual llvm::StringRef GetNilReferenceSummaryString()
Returns the summary string for ValueObjects for which IsNilReference() is true.
Definition: Language.h:263
static void PrintAllLanguages(Stream &s, const char *prefix, const char *suffix)
Definition: Language.cpp:284
virtual HardcodedFormatters::HardcodedSyntheticFinder GetHardcodedSynthetics()
Definition: Language.cpp:174
virtual const Highlighter * GetHighlighter() const
Definition: Language.h:180
virtual std::unique_ptr< TypeScavenger > GetTypeScavenger()
Definition: Language.cpp:436
static LanguageSet GetLanguagesSupportingTypeSystemsForExpressions()
Definition: Language.cpp:428
virtual llvm::StringRef GetUserEntryPointName() const
Definition: Language.h:174
virtual bool IsTopLevelFunction(Function &function)
Definition: Language.cpp:161
virtual void GetExceptionResolverDescription(bool catch_on, bool throw_on, Stream &s)
Definition: Language.cpp:520
static lldb::LanguageType GetLanguageTypeFromString(const char *string)=delete
static void ForEach(std::function< bool(Language *)> callback)
Definition: Language.cpp:131
Language(const Language &)=delete
static bool LanguageIsCFamily(lldb::LanguageType language)
Equivalent to LanguageIsC||LanguageIsObjC||LanguageIsCPlusPlus.
Definition: Language.cpp:336
static std::set< lldb::LanguageType > GetSupportedLanguages()
Definition: Language.cpp:415
virtual HardcodedFormatters::HardcodedFormatFinder GetHardcodedFormats()
Definition: Language.cpp:165
static bool LanguageIsObjC(lldb::LanguageType language)
Definition: Language.cpp:314
virtual bool SymbolNameFitsToLanguage(Mangled name) const
Returns true iff the given symbol name is compatible with the mangling scheme of this language.
Definition: Language.h:222
A class that handles mangled names.
Definition: Mangled.h:33
ConstString GetDemangledName() const
Demangled name get accessor.
Definition: Mangled.cpp:262
ConstString & GetMangledName()
Mangled name get accessor.
Definition: Mangled.h:145
An error handling class.
Definition: Status.h:44
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
size_t EOL()
Output and End of Line character to the stream.
Definition: Stream.cpp:155
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:34
A class that represents a running process on the host machine.
LanguageType
Programming language type.
std::shared_ptr< lldb_private::TypeCategoryImpl > TypeCategoryImplSP
Definition: lldb-forward.h:454
A SmallBitVector that represents a set of source languages (lldb::LanguageType).
Definition: Type.h:38