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
18#include "lldb/Core/Highlighter.h"
19#include "lldb/Core/PluginInterface.h"
20#include "lldb/DataFormatters/DumpValueObjectOptions.h"
21#include "lldb/DataFormatters/FormatClasses.h"
22#include "lldb/DataFormatters/StringPrinter.h"
23#include "lldb/Symbol/TypeSystem.h"
24#include "lldb/lldb-private.h"
25#include "lldb/lldb-public.h"
26
27namespace lldb_private {
28
29class Language : public PluginInterface {
30public:
31 class TypeScavenger {
32 public:
33 class Result {
34 public:
35 virtual bool IsValid() = 0;
36
37 virtual bool DumpToStream(Stream &stream,
38 bool print_help_if_available) = 0;
39
40 virtual ~Result() = default;
41 };
42
43 typedef std::set<std::unique_ptr<Result>> ResultSet;
44
45 virtual ~TypeScavenger() = default;
46
47 size_t Find(ExecutionContextScope *exe_scope, const char *key,
48 ResultSet &results, bool append = true);
49
50 protected:
51 TypeScavenger() = default;
52
53 virtual bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
54 ResultSet &results) = 0;
55 };
56
57 class ImageListTypeScavenger : public TypeScavenger {
58 class Result : public Language::TypeScavenger::Result {
59 public:
60 Result(CompilerType type) : m_compiler_type(type) {}
61
62 bool IsValid() override { return m_compiler_type.IsValid(); }
63
64 bool DumpToStream(Stream &stream, bool print_help_if_available) override {
65 if (IsValid()) {
66 m_compiler_type.DumpTypeDescription(s: &stream);
67 stream.EOL();
68 return true;
69 }
70 return false;
71 }
72
73 ~Result() override = default;
74
75 private:
76 CompilerType m_compiler_type;
77 };
78
79 protected:
80 ImageListTypeScavenger() = default;
81
82 ~ImageListTypeScavenger() override = default;
83
84 // is this type something we should accept? it's usually going to be a
85 // filter by language + maybe some sugar tweaking
86 // returning an empty type means rejecting this candidate entirely;
87 // any other result will be accepted as a valid match
88 virtual CompilerType AdjustForInclusion(CompilerType &candidate) = 0;
89
90 bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
91 ResultSet &results) override;
92 };
93
94 template <typename... ScavengerTypes>
95 class EitherTypeScavenger : public TypeScavenger {
96 public:
97 EitherTypeScavenger() : TypeScavenger() {
98 for (std::shared_ptr<TypeScavenger> scavenger : { std::shared_ptr<TypeScavenger>(new ScavengerTypes())... }) {
99 if (scavenger)
100 m_scavengers.push_back(x: scavenger);
101 }
102 }
103 protected:
104 bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
105 ResultSet &results) override {
106 const bool append = false;
107 for (auto& scavenger : m_scavengers) {
108 if (scavenger && scavenger->Find(exe_scope, key, results, append))
109 return true;
110 }
111 return false;
112 }
113 private:
114 std::vector<std::shared_ptr<TypeScavenger>> m_scavengers;
115 };
116
117 template <typename... ScavengerTypes>
118 class UnionTypeScavenger : public TypeScavenger {
119 public:
120 UnionTypeScavenger() : TypeScavenger() {
121 for (std::shared_ptr<TypeScavenger> scavenger : { std::shared_ptr<TypeScavenger>(new ScavengerTypes())... }) {
122 if (scavenger)
123 m_scavengers.push_back(x: scavenger);
124 }
125 }
126 protected:
127 bool Find_Impl(ExecutionContextScope *exe_scope, const char *key,
128 ResultSet &results) override {
129 const bool append = true;
130 bool success = false;
131 for (auto& scavenger : m_scavengers) {
132 if (scavenger)
133 success = scavenger->Find(exe_scope, key, results, append) || success;
134 }
135 return success;
136 }
137 private:
138 std::vector<std::shared_ptr<TypeScavenger>> m_scavengers;
139 };
140
141 enum class FunctionNameRepresentation {
142 eName,
143 eNameWithArgs,
144 eNameWithNoArgs
145 };
146
147 ~Language() override;
148
149 static Language *FindPlugin(lldb::LanguageType language);
150
151 /// Returns the Language associated with the given file path or a nullptr
152 /// if there is no known language.
153 static Language *FindPlugin(llvm::StringRef file_path);
154
155 static Language *FindPlugin(lldb::LanguageType language,
156 llvm::StringRef file_path);
157
158 // return false from callback to stop iterating
159 static void ForEach(std::function<bool(Language *)> callback);
160
161 virtual lldb::LanguageType GetLanguageType() const = 0;
162
163 // Implement this function to return the user-defined entry point name
164 // for the language.
165 virtual llvm::StringRef GetUserEntryPointName() const { return {}; }
166
167 virtual bool IsTopLevelFunction(Function &function);
168
169 virtual bool IsSourceFile(llvm::StringRef file_path) const = 0;
170
171 virtual const Highlighter *GetHighlighter() const { return nullptr; }
172
173 virtual lldb::TypeCategoryImplSP GetFormatters();
174
175 virtual HardcodedFormatters::HardcodedFormatFinder GetHardcodedFormats();
176
177 virtual HardcodedFormatters::HardcodedSummaryFinder GetHardcodedSummaries();
178
179 virtual HardcodedFormatters::HardcodedSyntheticFinder
180 GetHardcodedSynthetics();
181
182 virtual std::vector<FormattersMatchCandidate>
183 GetPossibleFormattersMatches(ValueObject &valobj,
184 lldb::DynamicValueType use_dynamic);
185
186 virtual std::unique_ptr<TypeScavenger> GetTypeScavenger();
187
188 virtual const char *GetLanguageSpecificTypeLookupHelp();
189
190 class MethodNameVariant {
191 ConstString m_name;
192 lldb::FunctionNameType m_type;
193
194 public:
195 MethodNameVariant(ConstString name, lldb::FunctionNameType type)
196 : m_name(name), m_type(type) {}
197 ConstString GetName() const { return m_name; }
198 lldb::FunctionNameType GetType() const { return m_type; }
199 };
200 // If a language can have more than one possible name for a method, this
201 // function can be used to enumerate them. This is useful when doing name
202 // lookups.
203 virtual std::vector<Language::MethodNameVariant>
204 GetMethodNameVariants(ConstString method_name) const {
205 return std::vector<Language::MethodNameVariant>();
206 };
207
208 /// Returns true iff the given symbol name is compatible with the mangling
209 /// scheme of this language.
210 ///
211 /// This function should only return true if there is a high confidence
212 /// that the name actually belongs to this language.
213 virtual bool SymbolNameFitsToLanguage(Mangled name) const { return false; }
214
215 /// An individual data formatter may apply to several types and cross language
216 /// boundaries. Each of those languages may want to customize the display of
217 /// values of said types by appending proper prefix/suffix information in
218 /// language-specific ways. This function returns that prefix and suffix.
219 ///
220 /// \param[in] type_hint
221 /// A StringRef used to determine what the prefix and suffix should be. It
222 /// is called a hint because some types may have multiple variants for which
223 /// the prefix and/or suffix may vary.
224 ///
225 /// \return
226 /// A std::pair<StringRef, StringRef>, the first being the prefix and the
227 /// second being the suffix. They may be empty.
228 virtual std::pair<llvm::StringRef, llvm::StringRef>
229 GetFormatterPrefixSuffix(llvm::StringRef type_hint);
230
231 // When looking up functions, we take a user provided string which may be a
232 // partial match to the full demangled name and compare it to the actual
233 // demangled name to see if it matches as much as the user specified. An
234 // example of this is if the user provided A::my_function, but the
235 // symbol was really B::A::my_function. We want that to be
236 // a match. But we wouldn't want this to match AnotherA::my_function. The
237 // user is specifying a truncated path, not a truncated set of characters.
238 // This function does a language-aware comparison for those purposes.
239 virtual bool DemangledNameContainsPath(llvm::StringRef path,
240 ConstString demangled) const;
241
242 // if a language has a custom format for printing variable declarations that
243 // it wants LLDB to honor it should return an appropriate closure here
244 virtual DumpValueObjectOptions::DeclPrintingHelper GetDeclPrintingHelper();
245
246 virtual LazyBool IsLogicalTrue(ValueObject &valobj, Status &error);
247
248 // for a ValueObject of some "reference type", if the value points to the
249 // nil/null object, this method returns true
250 virtual bool IsNilReference(ValueObject &valobj);
251
252 /// Returns the summary string for ValueObjects for which IsNilReference() is
253 /// true.
254 virtual llvm::StringRef GetNilReferenceSummaryString() { return {}; }
255
256 // for a ValueObject of some "reference type", if the language provides a
257 // technique to decide whether the reference has ever been assigned to some
258 // object, this method will return true if such detection is possible, and if
259 // the reference has never been assigned
260 virtual bool IsUninitializedReference(ValueObject &valobj);
261
262 virtual bool GetFunctionDisplayName(const SymbolContext *sc,
263 const ExecutionContext *exe_ctx,
264 FunctionNameRepresentation representation,
265 Stream &s);
266
267 virtual ConstString
268 GetDemangledFunctionNameWithoutArguments(Mangled mangled) const {
269 if (ConstString demangled = mangled.GetDemangledName())
270 return demangled;
271
272 return mangled.GetMangledName();
273 }
274
275 virtual void GetExceptionResolverDescription(bool catch_on, bool throw_on,
276 Stream &s);
277
278 static void GetDefaultExceptionResolverDescription(bool catch_on,
279 bool throw_on, Stream &s);
280
281 // These are accessors for general information about the Languages lldb knows
282 // about:
283
284 static lldb::LanguageType
285 GetLanguageTypeFromString(const char *string) = delete;
286 static lldb::LanguageType GetLanguageTypeFromString(llvm::StringRef string);
287
288 static const char *GetNameForLanguageType(lldb::LanguageType language);
289
290 static void PrintAllLanguages(Stream &s, const char *prefix,
291 const char *suffix);
292
293 /// Prints to the specified stream 's' each language type that the
294 /// current target supports for expression evaluation.
295 ///
296 /// \param[out] s Stream to which the language types are written.
297 /// \param[in] prefix String that is prepended to the language type.
298 /// \param[in] suffix String that is appended to the language type.
299 static void PrintSupportedLanguagesForExpressions(Stream &s,
300 llvm::StringRef prefix,
301 llvm::StringRef suffix);
302
303 // return false from callback to stop iterating
304 static void ForAllLanguages(std::function<bool(lldb::LanguageType)> callback);
305
306 static bool LanguageIsCPlusPlus(lldb::LanguageType language);
307
308 static bool LanguageIsObjC(lldb::LanguageType language);
309
310 static bool LanguageIsC(lldb::LanguageType language);
311
312 /// Equivalent to \c LanguageIsC||LanguageIsObjC||LanguageIsCPlusPlus.
313 static bool LanguageIsCFamily(lldb::LanguageType language);
314
315 static bool LanguageIsPascal(lldb::LanguageType language);
316
317 // return the primary language, so if LanguageIsC(l), return eLanguageTypeC,
318 // etc.
319 static lldb::LanguageType GetPrimaryLanguage(lldb::LanguageType language);
320
321 static std::set<lldb::LanguageType> GetSupportedLanguages();
322
323 static LanguageSet GetLanguagesSupportingTypeSystems();
324 static LanguageSet GetLanguagesSupportingTypeSystemsForExpressions();
325 static LanguageSet GetLanguagesSupportingREPLs();
326
327 // Given a mangled function name, calculates some alternative manglings since
328 // the compiler mangling may not line up with the symbol we are expecting.
329 virtual std::vector<ConstString>
330 GenerateAlternateFunctionManglings(const ConstString mangled) const {
331 return std::vector<ConstString>();
332 }
333
334 virtual ConstString
335 FindBestAlternateFunctionMangledName(const Mangled mangled,
336 const SymbolContext &sym_ctx) const {
337 return ConstString();
338 }
339
340 virtual llvm::StringRef GetInstanceVariableName() { return {}; }
341
342protected:
343 // Classes that inherit from Language can see and modify these
344
345 Language();
346
347private:
348 Language(const Language &) = delete;
349 const Language &operator=(const Language &) = delete;
350};
351
352} // namespace lldb_private
353
354#endif // LLDB_TARGET_LANGUAGE_H
355

source code of lldb/include/lldb/Target/Language.h