[lldb-dap] Add an option to provide a format for stack frames (llvm#71843)

When this option gets enabled, descriptions of stack frames will be
generated using the format provided in the launch configuration instead
of simply calling `SBFrame::GetDisplayFunctionName`. This allows
lldb-dap to show an output similar to the one in the CLI.

(cherry picked from commit d9ec4b2)

Author: walter-erquinigo

lldb/bindings/headers.swig

@@ -30,6 +30,7 @@
 #include "lldb/API/SBFile.h"
 #include "lldb/API/SBFileSpec.h"
 #include "lldb/API/SBFileSpecList.h"
+#include "lldb/API/SBFormat.h"
 #include "lldb/API/SBFrame.h"
 #include "lldb/API/SBFunction.h"
 #include "lldb/API/SBHostOS.h"

lldb/bindings/interface/SBFormatDocstrings.i

@@ -0,0 +1,5 @@
+%feature("docstring",
+"Class that represents a format string that can be used to generate "
+"descriptions of objects like frames and threads. See "
+"https://lldb.llvm.org/use/formatting.html for more information."
+) lldb::SBFormat;

lldb/bindings/interfaces.swig

@@ -34,6 +34,7 @@
 %include "./interface/SBFileDocstrings.i"
 %include "./interface/SBFileSpecDocstrings.i"
 %include "./interface/SBFileSpecListDocstrings.i"
+%include "./interface/SBFormatDocstrings.i"
 %include "./interface/SBFrameDocstrings.i"
 %include "./interface/SBFunctionDocstrings.i"
 %include "./interface/SBHostOSDocstrings.i"
@@ -106,6 +107,7 @@
 %include "lldb/API/SBFile.h"
 %include "lldb/API/SBFileSpec.h"
 %include "lldb/API/SBFileSpecList.h"
+%include "lldb/API/SBFormat.h"
 %include "lldb/API/SBFrame.h"
 %include "lldb/API/SBFunction.h"
 %include "lldb/API/SBHostOS.h"

lldb/include/lldb/API/SBDefines.h

@@ -71,6 +71,7 @@ class LLDB_API SBExpressionOptions;
 class LLDB_API SBFile;
 class LLDB_API SBFileSpec;
 class LLDB_API SBFileSpecList;
+class LLDB_API SBFormat;
 class LLDB_API SBFrame;
 class LLDB_API SBFunction;
 class LLDB_API SBHostOS;

lldb/include/lldb/API/SBError.h

@@ -80,6 +80,7 @@ class LLDB_API SBError {
   friend class SBData;
   friend class SBDebugger;
   friend class SBFile;
+  friend class SBFormat;
   friend class SBHostOS;
   friend class SBModule;
   friend class SBPlatform;

lldb/include/lldb/API/SBFormat.h

@@ -0,0 +1,65 @@
+//===-- SBFormat.h ----------------------------------------------*- C++ -*-===//
+//
+// 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_API_SBFORMAT_H
+#define LLDB_API_SBFORMAT_H
+
+#include "lldb/API/SBDefines.h"
+
+namespace lldb_private {
+namespace python {
+class SWIGBridge;
+} // namespace python
+namespace lua {
+class SWIGBridge;
+} // namespace lua
+} // namespace lldb_private
+
+namespace lldb {
+
+/// Class that represents a format string that can be used to generate
+/// descriptions of objects like frames and threads. See
+/// https://lldb.llvm.org/use/formatting.html for more information.
+class LLDB_API SBFormat {
+public:
+  SBFormat();
+
+  /// Create an \a SBFormat by parsing the given format string. If parsing
+  /// fails, this object is initialized as invalid.
+  ///
+  /// \param[in] format
+  ///   The format string to parse.
+  ///
+  /// \param[out] error
+  ///   An object where error messages will be written to if parsing fails.
+  SBFormat(const char *format, lldb::SBError &error);
+
+  SBFormat(const lldb::SBFormat &rhs);
+
+  lldb::SBFormat &operator=(const lldb::SBFormat &rhs);
+
+  ~SBFormat();
+
+  /// \return
+  ///   \b true if and only if this object is valid and can be used for
+  ///   formatting.
+  explicit operator bool() const;
+
+protected:
+  friend class SBFrame;
+
+  /// \return
+  ///   The underlying shared pointer storage for this object.
+  lldb::FormatEntrySP GetFormatEntrySP() const;
+
+  /// The storage for this object.
+  lldb::FormatEntrySP m_opaque_sp;
+};
+
+} // namespace lldb
+#endif // LLDB_API_SBFORMAT_H

lldb/include/lldb/API/SBFrame.h

@@ -88,7 +88,7 @@ class LLDB_API SBFrame {
   const char *GetDisplayFunctionName();
 
   const char *GetFunctionName() const;
-  
+
   // Return the frame function's language.  If there isn't a function, then
   // guess the language type from the mangled name.
   lldb::LanguageType GuessLanguage() const;
@@ -197,6 +197,21 @@ class LLDB_API SBFrame {
 
   bool GetDescription(lldb::SBStream &description);
 
+  /// Similar to \a GetDescription() but the format of the description can be
+  /// configured via the \p format parameter. See
+  /// https://lldb.llvm.org/use/formatting.html for more information on format
+  /// strings.
+  ///
+  /// \param[in] format
+  ///   The format to use for generating the description.
+  ///
+  /// \param[out] output
+  ///   The stream where the description will be written to.
+  ///
+  /// \return
+  ///   An error object with an error message in case of failures.
+  SBError GetDescriptionWithFormat(const SBFormat &format, SBStream &output);
+
 protected:
   friend class SBBlock;
   friend class SBExecutionContext;