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 
27 namespace lldb_private {
28 
29 class Language : public PluginInterface {
30 public:
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(&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(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(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   virtual bool IsTopLevelFunction(Function &function);
164 
165   virtual bool IsSourceFile(llvm::StringRef file_path) const = 0;
166 
167   virtual const Highlighter *GetHighlighter() const { return nullptr; }
168 
169   virtual lldb::TypeCategoryImplSP GetFormatters();
170 
171   virtual HardcodedFormatters::HardcodedFormatFinder GetHardcodedFormats();
172 
173   virtual HardcodedFormatters::HardcodedSummaryFinder GetHardcodedSummaries();
174 
175   virtual HardcodedFormatters::HardcodedSyntheticFinder
176   GetHardcodedSynthetics();
177 
178   virtual std::vector<FormattersMatchCandidate>
179   GetPossibleFormattersMatches(ValueObject &valobj,
180                                lldb::DynamicValueType use_dynamic);
181 
182   virtual std::unique_ptr<TypeScavenger> GetTypeScavenger();
183 
184   virtual const char *GetLanguageSpecificTypeLookupHelp();
185 
186   class MethodNameVariant {
187     ConstString m_name;
188     lldb::FunctionNameType m_type;
189 
190   public:
191     MethodNameVariant(ConstString name, lldb::FunctionNameType type)
192         : m_name(name), m_type(type) {}
193     ConstString GetName() const { return m_name; }
194     lldb::FunctionNameType GetType() const { return m_type; }
195   };
196   // If a language can have more than one possible name for a method, this
197   // function can be used to enumerate them. This is useful when doing name
198   // lookups.
199   virtual std::vector<Language::MethodNameVariant>
200   GetMethodNameVariants(ConstString method_name) const {
201     return std::vector<Language::MethodNameVariant>();
202   };
203 
204   /// Returns true iff the given symbol name is compatible with the mangling
205   /// scheme of this language.
206   ///
207   /// This function should only return true if there is a high confidence
208   /// that the name actually belongs to this language.
209   virtual bool SymbolNameFitsToLanguage(Mangled name) const { return false; }
210 
211   // if an individual data formatter can apply to several types and cross a
212   // language boundary it makes sense for individual languages to want to
213   // customize the printing of values of that type by appending proper
214   // prefix/suffix information in language-specific ways
215   virtual bool GetFormatterPrefixSuffix(ValueObject &valobj,
216                                         ConstString type_hint,
217                                         std::string &prefix,
218                                         std::string &suffix);
219 
220   // When looking up functions, we take a user provided string which may be a
221   // partial match to the full demangled name and compare it to the actual
222   // demangled name to see if it matches as much as the user specified.  An
223   // example of this is if the user provided A::my_function, but the
224   // symbol was really B::A::my_function.  We want that to be
225   // a match.  But we wouldn't want this to match AnotherA::my_function.  The
226   // user is specifying a truncated path, not a truncated set of characters.
227   // This function does a language-aware comparison for those purposes.
228   virtual bool DemangledNameContainsPath(llvm::StringRef path,
229                                          ConstString demangled) const;
230 
231   // if a language has a custom format for printing variable declarations that
232   // it wants LLDB to honor it should return an appropriate closure here
233   virtual DumpValueObjectOptions::DeclPrintingHelper GetDeclPrintingHelper();
234 
235   virtual LazyBool IsLogicalTrue(ValueObject &valobj, Status &error);
236 
237   // for a ValueObject of some "reference type", if the value points to the
238   // nil/null object, this method returns true
239   virtual bool IsNilReference(ValueObject &valobj);
240 
241   /// Returns the summary string for ValueObjects for which IsNilReference() is
242   /// true.
243   virtual llvm::StringRef GetNilReferenceSummaryString() { return {}; }
244 
245   // for a ValueObject of some "reference type", if the language provides a
246   // technique to decide whether the reference has ever been assigned to some
247   // object, this method will return true if such detection is possible, and if
248   // the reference has never been assigned
249   virtual bool IsUninitializedReference(ValueObject &valobj);
250 
251   virtual bool GetFunctionDisplayName(const SymbolContext *sc,
252                                       const ExecutionContext *exe_ctx,
253                                       FunctionNameRepresentation representation,
254                                       Stream &s);
255 
256   virtual ConstString
257   GetDemangledFunctionNameWithoutArguments(Mangled mangled) const {
258     if (ConstString demangled = mangled.GetDemangledName())
259       return demangled;
260 
261     return mangled.GetMangledName();
262   }
263 
264   virtual void GetExceptionResolverDescription(bool catch_on, bool throw_on,
265                                                Stream &s);
266 
267   static void GetDefaultExceptionResolverDescription(bool catch_on,
268                                                      bool throw_on, Stream &s);
269 
270   // These are accessors for general information about the Languages lldb knows
271   // about:
272 
273   static lldb::LanguageType
274   GetLanguageTypeFromString(const char *string) = delete;
275   static lldb::LanguageType GetLanguageTypeFromString(llvm::StringRef string);
276 
277   static const char *GetNameForLanguageType(lldb::LanguageType language);
278 
279   static void PrintAllLanguages(Stream &s, const char *prefix,
280                                 const char *suffix);
281 
282   /// Prints to the specified stream 's' each language type that the
283   /// current target supports for expression evaluation.
284   ///
285   /// \param[out] s      Stream to which the language types are written.
286   /// \param[in]  prefix String that is prepended to the language type.
287   /// \param[in]  suffix String that is appended to the language type.
288   static void PrintSupportedLanguagesForExpressions(Stream &s,
289                                                     llvm::StringRef prefix,
290                                                     llvm::StringRef suffix);
291 
292   // return false from callback to stop iterating
293   static void ForAllLanguages(std::function<bool(lldb::LanguageType)> callback);
294 
295   static bool LanguageIsCPlusPlus(lldb::LanguageType language);
296 
297   static bool LanguageIsObjC(lldb::LanguageType language);
298 
299   static bool LanguageIsC(lldb::LanguageType language);
300 
301   /// Equivalent to \c LanguageIsC||LanguageIsObjC||LanguageIsCPlusPlus.
302   static bool LanguageIsCFamily(lldb::LanguageType language);
303 
304   static bool LanguageIsPascal(lldb::LanguageType language);
305 
306   // return the primary language, so if LanguageIsC(l), return eLanguageTypeC,
307   // etc.
308   static lldb::LanguageType GetPrimaryLanguage(lldb::LanguageType language);
309 
310   static std::set<lldb::LanguageType> GetSupportedLanguages();
311 
312   static LanguageSet GetLanguagesSupportingTypeSystems();
313   static LanguageSet GetLanguagesSupportingTypeSystemsForExpressions();
314   static LanguageSet GetLanguagesSupportingREPLs();
315 
316   // Given a mangled function name, calculates some alternative manglings since
317   // the compiler mangling may not line up with the symbol we are expecting.
318   virtual std::vector<ConstString>
319   GenerateAlternateFunctionManglings(const ConstString mangled) const {
320     return std::vector<ConstString>();
321   }
322 
323   virtual ConstString
324   FindBestAlternateFunctionMangledName(const Mangled mangled,
325                                        const SymbolContext &sym_ctx) const {
326     return ConstString();
327   }
328 
329 protected:
330   // Classes that inherit from Language can see and modify these
331 
332   Language();
333 
334 private:
335   Language(const Language &) = delete;
336   const Language &operator=(const Language &) = delete;
337 };
338 
339 } // namespace lldb_private
340 
341 #endif // LLDB_TARGET_LANGUAGE_H
342