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(&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  // 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