Mangled.h

Go to the documentation of this file.

//===-- Mangled.h ---------------------------------------------------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
 
#ifndef LLDB_CORE_MANGLED_H
#define LLDB_CORE_MANGLED_H
 
#include "lldb/Core/DemangledNameInfo.h"
#include "lldb/Utility/ConstString.h"
#include "lldb/lldb-enumerations.h"
#include "lldb/lldb-forward.h"
#include "lldb/lldb-types.h"
#include "llvm/ADT/ArrayRef.h"
#include "llvm/ADT/StringRef.h"
 
#include <cstddef>
#include <cstdint>
#include <optional>
 
namespace lldb_private {
 
/// \class Mangled Mangled.h "lldb/Core/Mangled.h"
/// A class that handles mangled names.
///
/// Designed to handle mangled names. The demangled version of any names will
/// be computed when the demangled name is accessed through the Demangled()
/// accessor. This class can also tokenize the demangled version of the name
/// for powerful searches. Functions and symbols could make instances of this
/// class for their mangled names. Uniqued string pools are used for the
/// mangled, demangled, and token string values to allow for faster
/// comparisons and for efficient memory use.
class Mangled {
public:
  enum NamePreference {
    ePreferMangled,
    ePreferDemangled,
    ePreferDemangledWithoutArguments
  };
 
  enum ManglingScheme : uint8_t {
    eManglingSchemeNone = 0,
    eFirstRegisteredManglingScheme,
  };
 
  /// The number of possible mangling schemes, which sizes the tables that are
  /// indexed by ManglingScheme.
  static constexpr size_t g_num_mangling_schemes = 16;
 
  /// What a mangled function name says about the function's declaration.
  enum class FunctionNameKind {
    TopLevel,
    InNamespace,
    Method,
    ConstructorOrDestructor,
    Unknown,
  };
 
  /// The parts of a mangled function name used in the symbol table's indices.
  struct FunctionNameParts {
    /// If empty, the symbol is only indexed by its mangled name.
    ConstString basename;
    /// The enclosing context. The symbol table only uses it to work
    /// out which contexts are classes: a ConstructorOrDestructor
    /// shows that its context is one, and an Unknown function in such
    /// a context is a method.
    ConstString decl_context;
    FunctionNameKind kind = FunctionNameKind::Unknown;
  };
 
  /// Default constructor.
  ///
  /// Initialize with both mangled and demangled names empty.
  Mangled() = default;
 
  /// Construct with name.
  ///
  /// Constructor with an optional string and auto-detect if \a name is
  /// mangled or not.
  ///
  /// \param[in] name
  ///     The already const name to copy into this object.
  explicit Mangled(ConstString name);
 
  explicit Mangled(llvm::StringRef name);
 
  bool operator==(const Mangled &rhs) const {
    return m_mangled == rhs.m_mangled &&
           GetDemangledName() == rhs.GetDemangledName();
  }
 
  bool operator!=(const Mangled &rhs) const {
    return !(*this == rhs);
  }
 
  /// Convert to bool operator.
  ///
  /// This allows code to check any Mangled objects to see if they contain
  /// anything valid using code such as:
  ///
  /// \code
  /// Mangled mangled(...);
  /// if (mangled)
  /// { ...
  /// \endcode
  ///
  /// \return
  ///     Returns \b true if either the mangled or unmangled name is set,
  ///     \b false if the object has an empty mangled and unmangled name.
  explicit operator bool() const;
 
  /// Clear the mangled and demangled values.
  void Clear();
 
  /// Compare the mangled string values
  ///
  /// Compares the Mangled::GetName() string in \a lhs and \a rhs.
  ///
  /// \param[in] lhs
  ///     A const reference to the Left Hand Side object to compare.
  ///
  /// \param[in] rhs
  ///     A const reference to the Right Hand Side object to compare.
  ///
  /// \return
  ///     -1 if \a lhs is less than \a rhs
  ///     0 if \a lhs is equal to \a rhs
  ///     1 if \a lhs is greater than \a rhs
  static int Compare(const Mangled &lhs, const Mangled &rhs);
 
  /// Dump a description of this object to a Stream \a s.
  ///
  /// Dump a Mangled object to stream \a s. We don't force our demangled name
  /// to be computed currently (we don't use the accessor).
  ///
  /// \param[in] s
  ///     The stream to which to dump the object description.
  void Dump(Stream *s) const;
 
  /// Dump a debug description of this object to a Stream \a s.
  ///
  /// \param[in] s
  ///     The stream to which to dump the object description.
  void DumpDebug(Stream *s) const;
 
  /// Demangled name get accessor.
  ///
  /// \return
  ///     A const reference to the demangled name string object.
  ConstString GetDemangledName() const;
 
  /// Display demangled name get accessor.
  ///
  /// \return
  ///     A const reference to the display demangled name string object.
  ConstString GetDisplayDemangledName() const;
 
  void SetDemangledName(ConstString name) { m_demangled = name; }
 
  void SetMangledName(ConstString name) { m_mangled = name; }
 
  /// Mangled name get accessor.
  ///
  /// \return
  ///     The mangled name string object.
  ConstString GetMangledName() const { return m_mangled; }
 
  /// Best name get accessor.
  ///
  /// \param[in] preference
  ///     Which name would you prefer to get?
  ///
  /// \return
  ///     A const reference to the preferred name string object if this
  ///     object has a valid name of that kind, else a const reference to the
  ///     other name is returned.
  ConstString GetName(NamePreference preference = ePreferDemangled) const;
 
  /// Check if "name" matches either the mangled or demangled name.
  ///
  /// \param[in] name
  ///     A name to match against both strings.
  ///
  /// \return
  ///     \b True if \a name matches either name, \b false otherwise.
  bool NameMatches(ConstString name) const {
    if (m_mangled == name)
      return true;
    return GetDemangledName() == name;
  }
  bool NameMatches(const RegularExpression &regex) const;
 
  /// Set the string value in this object.
  ///
  /// This version auto detects if the string is mangled by inspecting the
  /// string value and looking for the prefixes of the registered mangling
  /// schemes.
  ///
  /// \param[in] name
  ///     The already const version of the name for this object.
  void SetValue(ConstString name);
 
  /// Try to guess the language from the mangling.
  ///
  /// For a mangled name to have a language it must have both a mangled and a
  /// demangled name and it can be guessed from the mangling what the language
  /// is.  Note: this will return C++ for any language that uses Itanium ABI
  /// mangling.
  ///
  /// Standard C function names will return eLanguageTypeUnknown because they
  /// aren't mangled and it isn't clear what language the name represents
  /// (there will be no mangled name).
  ///
  /// \return
  ///     The language for the mangled/demangled name, eLanguageTypeUnknown
  ///     if there is no mangled or demangled counterpart.
  lldb::LanguageType GuessLanguage() const;
 
  /// Try to identify the mangling scheme used.
  /// \param[in] name
  ///     The name we are attempting to identify the mangling scheme for.
  ///
  /// \return
  ///     eManglingSchemeNone if no registered mangling scheme matches \p name,
  ///     otherwise the scheme that does.
  static Mangled::ManglingScheme GetManglingScheme(llvm::StringRef name);
 
  static bool IsMangledName(llvm::StringRef name);
 
  using ManglingSchemeMatcher = bool (*)(llvm::StringRef name);
 
  /// Register a mangling scheme for \p language. All mangled names in
  /// this scheme start with one of \p prefixes. If the prefixes are
  /// insufficient to unambiguously identify a scheme, \p matches
  /// checks the rest of each name.
  ///
  /// Registering the same scheme again returns the same scheme.
  ///
  /// \return
  ///     The new scheme, or eManglingSchemeNone if there is no slot left.
  static ManglingScheme
  RegisterManglingScheme(llvm::ArrayRef<llvm::StringRef> prefixes,
                         lldb::LanguageType language,
                         ManglingSchemeMatcher matches = nullptr);
 
  /// Stop recognizing the names of \p scheme, a scheme returned by
  /// RegisterManglingScheme().
  static void UnregisterManglingScheme(ManglingScheme scheme);
 
  /// Returns the language that registered \p scheme, or eLanguageTypeUnknown
  /// if no language did.
  static lldb::LanguageType GetLanguageForManglingScheme(ManglingScheme scheme);
 
  /// Decode a serialized version of this object from data.
  ///
  /// \param data
  ///   The decoder object that references the serialized data.
  ///
  /// \param offset_ptr
  ///   A pointer that contains the offset from which the data will be decoded
  ///   from that gets updated as data gets decoded.
  ///
  /// \param strtab
  ///   All strings in cache files are put into string tables for efficiency
  ///   and cache file size reduction. Strings are stored as uint32_t string
  ///   table offsets in the cache data.
  bool Decode(const DataExtractor &data, lldb::offset_t *offset_ptr,
              const StringTableReader &strtab);
 
  /// Encode this object into a data encoder object.
  ///
  /// This allows this object to be serialized to disk.
  ///
  /// \param encoder
  ///   A data encoder object that serialized bytes will be encoded into.
  ///
  /// \param strtab
  ///   All strings in cache files are put into string tables for efficiency
  ///   and cache file size reduction. Strings are stored as uint32_t string
  ///   table offsets in the cache data.
  void Encode(DataEncoder &encoder, ConstStringTable &strtab) const;
 
  /// Compute the \c DemangledNameInfo of the demangled name.
  ///
  /// Note that this always re-runs the demangler. \see DemangledNameInfoCache
  /// for caching the result.
  ///
  /// \return
  ///     std::nullopt if no info could be computed (for example because the
  ///     name is mangled with a scheme that doesn't provide any info).
  std::optional<DemangledNameInfo> ComputeDemangledInfo() const;
 
  /// Compute the base name (without namespace/class qualifiers) from the
  /// demangled name.
  ///
  /// For a demangled name like "ns::MyClass<int>::templateFunc", this returns
  /// just "templateFunc".
  ///
  /// \return
  ///     A ConstString containing the basename, or nullptr if computation
  ///     fails.
  ConstString GetBaseName() const;
 
private:
  /// The mangled version of the name.
  ConstString m_mangled;
 
  /// Mutable so we can get it on demand with
  /// a const version of this object.
  mutable ConstString m_demangled;
};
static_assert(sizeof(Mangled) <= 2 * sizeof(ConstString),
              "High-volume object, size of object must be increased with care");
 
Stream &operator<<(Stream &s, const Mangled &obj);
 
} // namespace lldb_private
 
#endif // LLDB_CORE_MANGLED_H