Merge pull request #6274 from apple/dl/cherry-pick-dwim-print

[lldb] Cherry-pick initial dwim-print command commits

Author: kastiglione

lldb/include/lldb/Core/Debugger.h

@@ -352,6 +352,8 @@ class Debugger : public std::enable_shared_from_this<Debugger>,
 
   bool SetTabSize(uint32_t tab_size);
 
+  lldb::DWIMPrintVerbosity GetDWIMPrintVerbosity() const;
+
   bool GetEscapeNonPrintables() const;
 
   bool GetNotifyVoid() const;

lldb/include/lldb/lldb-enumerations.h

@@ -1234,6 +1234,16 @@ enum TraceCursorSeekType {
   eTraceCursorSeekTypeEnd
 };
 
+/// Enum to control the verbosity level of `dwim-print` execution.
+enum DWIMPrintVerbosity {
+  /// Run `dwim-print` with no verbosity.
+  eDWIMPrintVerbosityNone,
+  /// Print a message when `dwim-print` uses `expression` evaluation.
+  eDWIMPrintVerbosityExpression,
+  /// Always print a message indicating how `dwim-print` is evaluating its
+  /// expression.
+  eDWIMPrintVerbosityFull,
+};
 
 } // namespace lldb
 

lldb/source/Commands/CMakeLists.txt

@@ -14,6 +14,7 @@ add_lldb_library(lldbCommands
   CommandObjectBreakpointCommand.cpp
   CommandObjectCommands.cpp
   CommandObjectDisassemble.cpp
+  CommandObjectDWIMPrint.cpp
   CommandObjectExpression.cpp
   CommandObjectFrame.cpp
   CommandObjectGUI.cpp

lldb/source/Commands/CommandObjectDWIMPrint.cpp

@@ -0,0 +1,112 @@
+//===-- CommandObjectDWIMPrint.cpp ------------------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+
+#include "CommandObjectDWIMPrint.h"
+
+#include "lldb/Core/ValueObject.h"
+#include "lldb/DataFormatters/DumpValueObjectOptions.h"
+#include "lldb/Interpreter/CommandInterpreter.h"
+#include "lldb/Interpreter/CommandObject.h"
+#include "lldb/Interpreter/CommandReturnObject.h"
+#include "lldb/Interpreter/OptionGroupFormat.h"
+#include "lldb/Interpreter/OptionGroupValueObjectDisplay.h"
+#include "lldb/Target/StackFrame.h"
+#include "lldb/Utility/ConstString.h"
+#include "lldb/lldb-defines.h"
+#include "lldb/lldb-enumerations.h"
+#include "lldb/lldb-forward.h"
+#include "llvm/ADT/StringRef.h"
+#include "llvm/Support/FormatVariadic.h"
+
+using namespace llvm;
+using namespace lldb;
+using namespace lldb_private;
+
+CommandObjectDWIMPrint::CommandObjectDWIMPrint(CommandInterpreter &interpreter)
+    : CommandObjectRaw(interpreter, "dwim-print",
+                       "Print a variable or expression.",
+                       "dwim-print [<variable-name> | <expression>]",
+                       eCommandProcessMustBePaused | eCommandTryTargetAPILock) {
+  m_option_group.Append(&m_format_options,
+                        OptionGroupFormat::OPTION_GROUP_FORMAT |
+                            OptionGroupFormat::OPTION_GROUP_GDB_FMT,
+                        LLDB_OPT_SET_1);
+  m_option_group.Append(&m_varobj_options, LLDB_OPT_SET_ALL, LLDB_OPT_SET_1);
+  m_option_group.Finalize();
+}
+
+Options *CommandObjectDWIMPrint::GetOptions() { return &m_option_group; }
+
+bool CommandObjectDWIMPrint::DoExecute(StringRef command,
+                                       CommandReturnObject &result) {
+  m_option_group.NotifyOptionParsingStarting(&m_exe_ctx);
+  OptionsWithRaw args{command};
+  StringRef expr = args.GetRawPart();
+
+  if (args.HasArgs()) {
+    if (!ParseOptionsAndNotify(args.GetArgs(), result, m_option_group,
+                               m_exe_ctx))
+      return false;
+  } else if (command.empty()) {
+    result.AppendErrorWithFormatv("'{0}' takes a variable or expression",
+                                  m_cmd_name);
+    return false;
+  }
+  auto verbosity = GetDebugger().GetDWIMPrintVerbosity();
+
+  DumpValueObjectOptions dump_options = m_varobj_options.GetAsDumpOptions(
+      eLanguageRuntimeDescriptionDisplayVerbosityFull,
+      m_format_options.GetFormat());
+
+  // First, try `expr` as the name of a frame variable.
+  if (StackFrame *frame = m_exe_ctx.GetFramePtr()) {
+    auto valobj_sp = frame->FindVariable(ConstString(expr));
+    if (valobj_sp && valobj_sp->GetError().Success()) {
+      if (verbosity == eDWIMPrintVerbosityFull) {
+        StringRef flags;
+        if (args.HasArgs())
+          flags = args.GetArgString();
+        result.AppendMessageWithFormatv("note: ran `frame variable {0}{1}`",
+                                        flags, expr);
+      }
+      valobj_sp->Dump(result.GetOutputStream(), dump_options);
+      result.SetStatus(eReturnStatusSuccessFinishResult);
+      return true;
+    }
+  }
+
+  // Second, also lastly, try `expr` as a source expression to evaluate.
+  {
+    Target *target_ptr = m_exe_ctx.GetTargetPtr();
+    // Fallback to the dummy target, which can allow for expression evaluation.
+    Target &target = target_ptr ? *target_ptr : GetDummyTarget();
+
+    auto *exe_scope = m_exe_ctx.GetBestExecutionContextScope();
+    ValueObjectSP valobj_sp;
+    if (target.EvaluateExpression(expr, exe_scope, valobj_sp) ==
+        eExpressionCompleted) {
+      if (verbosity != eDWIMPrintVerbosityNone) {
+        StringRef flags;
+        if (args.HasArgs())
+          flags = args.GetArgStringWithDelimiter();
+        result.AppendMessageWithFormatv("note: ran `expression {0}{1}`", flags,
+                                        expr);
+      }
+      valobj_sp->Dump(result.GetOutputStream(), dump_options);
+      result.SetStatus(eReturnStatusSuccessFinishResult);
+      return true;
+    } else {
+      if (valobj_sp)
+        result.SetError(valobj_sp->GetError());
+      else
+        result.AppendErrorWithFormatv(
+            "unknown error evaluating expression `{0}`", expr);
+      return false;
+    }
+  }
+}

lldb/source/Commands/CommandObjectDWIMPrint.h

@@ -0,0 +1,49 @@
+//===-- CommandObjectDWIMPrint.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_SOURCE_COMMANDS_COMMANDOBJECTDWIMPRINT_H
+#define LLDB_SOURCE_COMMANDS_COMMANDOBJECTDWIMPRINT_H
+
+#include "lldb/Interpreter/CommandObject.h"
+#include "lldb/Interpreter/OptionGroupFormat.h"
+#include "lldb/Interpreter/OptionGroupValueObjectDisplay.h"
+#include "lldb/Interpreter/OptionValueFormat.h"
+
+namespace lldb_private {
+
+/// Implements `dwim-print`, a printing command that chooses the most direct,
+/// efficient, and resilient means of printing a given expression.
+///
+/// DWIM is an acronym for Do What I Mean. From Wikipedia, DWIM is described as:
+///
+///   > attempt to anticipate what users intend to do, correcting trivial errors
+///   > automatically rather than blindly executing users' explicit but
+///   > potentially incorrect input
+///
+/// The `dwim-print` command serves as a single print command for users who
+/// don't yet know, or perfer not to know, the various lldb commands that can be
+/// used to print, and when to use them.
+class CommandObjectDWIMPrint : public CommandObjectRaw {
+public:
+  CommandObjectDWIMPrint(CommandInterpreter &interpreter);
+
+  ~CommandObjectDWIMPrint() override = default;
+
+  Options *GetOptions() override;
+
+private:
+  bool DoExecute(llvm::StringRef command, CommandReturnObject &result) override;
+
+  OptionGroupOptions m_option_group;
+  OptionGroupFormat m_format_options = lldb::eFormatDefault;
+  OptionGroupValueObjectDisplay m_varobj_options;
+};
+
+} // namespace lldb_private
+
+#endif

lldb/source/Core/CoreProperties.td

@@ -225,4 +225,9 @@ let Definition = "debugger" in {
     Global,
     DefaultStringValue<"${ansi.normal}">,
     Desc<"When displaying suggestion in a color-enabled terminal, use the ANSI terminal code specified in this format immediately after the suggestion.">;
+  def DWIMPrintVerbosity: Property<"dwim-print-verbosity", "Enum">,
+    Global,
+    DefaultEnumValue<"eDWIMPrintVerbosityExpression">,
+    EnumValues<"OptionEnumValues(g_dwim_print_verbosities)">,
+    Desc<"The verbosity level used by dwim-print.">;
 }

lldb/source/Core/Debugger.cpp

@@ -51,6 +51,7 @@
 #include "lldb/Utility/State.h"
 #include "lldb/Utility/Stream.h"
 #include "lldb/Utility/StreamString.h"
+#include "lldb/lldb-enumerations.h"
 
 #if defined(_WIN32)
 #include "lldb/Host/windows/PosixApi.h"
@@ -148,6 +149,16 @@ static constexpr OptionEnumValueElement g_language_enumerators[] = {
     },
 };
 
+static constexpr OptionEnumValueElement g_dwim_print_verbosities[] = {
+    {eDWIMPrintVerbosityNone, "none",
+     "Use no verbosity when running dwim-print."},
+    {eDWIMPrintVerbosityExpression, "expression",
+     "Use partial verbosity when running dwim-print - display a message when "
+     "`expression` evaluation is used."},
+    {eDWIMPrintVerbosityFull, "full",
+     "Use full verbosity when running dwim-print."},
+};
+
 static constexpr OptionEnumValueElement s_stop_show_column_values[] = {
     {
         eStopShowColumnAnsiOrCaret,
@@ -519,6 +530,13 @@ bool Debugger::SetTabSize(uint32_t tab_size) {
   return m_collection_sp->SetPropertyAtIndexAsUInt64(nullptr, idx, tab_size);
 }
 
+lldb::DWIMPrintVerbosity Debugger::GetDWIMPrintVerbosity() const {
+  const uint32_t idx = ePropertyDWIMPrintVerbosity;
+  return (lldb::DWIMPrintVerbosity)
+      m_collection_sp->GetPropertyAtIndexAsEnumeration(
+          nullptr, idx, g_debugger_properties[idx].default_uint_value);
+}
+
 #pragma mark Debugger
 
 // const DebuggerPropertiesSP &

lldb/source/Interpreter/CommandInterpreter.cpp

@@ -15,6 +15,7 @@
 #include "Commands/CommandObjectApropos.h"
 #include "Commands/CommandObjectBreakpoint.h"
 #include "Commands/CommandObjectCommands.h"
+#include "Commands/CommandObjectDWIMPrint.h"
 #include "Commands/CommandObjectDisassemble.h"
 #include "Commands/CommandObjectExpression.h"
 #include "Commands/CommandObjectFrame.h"
@@ -538,6 +539,7 @@ void CommandInterpreter::LoadCommandDictionary() {
   REGISTER_COMMAND_OBJECT("breakpoint", CommandObjectMultiwordBreakpoint);
   REGISTER_COMMAND_OBJECT("command", CommandObjectMultiwordCommands);
   REGISTER_COMMAND_OBJECT("disassemble", CommandObjectDisassemble);
+  REGISTER_COMMAND_OBJECT("dwim-print", CommandObjectDWIMPrint);
   REGISTER_COMMAND_OBJECT("expression", CommandObjectExpression);
   REGISTER_COMMAND_OBJECT("frame", CommandObjectMultiwordFrame);
   REGISTER_COMMAND_OBJECT("gui", CommandObjectGUI);

lldb/test/API/commands/dwim-print/Makefile

@@ -0,0 +1,3 @@
+C_SOURCES := main.c
+
+include Makefile.rules

lldb/test/API/commands/dwim-print/TestDWIMPrint.py

@@ -0,0 +1,105 @@
+"""
+Test dwim-print with variables, variable paths, and expressions.
+"""
+
+import re
+import lldb
+from lldbsuite.test.lldbtest import *
+from lldbsuite.test.decorators import *
+import lldbsuite.test.lldbutil as lldbutil
+
+
+class TestCase(TestBase):
+    def _run_cmd(self, cmd: str) -> str:
+        """Run the given lldb command and return its output."""
+        result = lldb.SBCommandReturnObject()
+        self.ci.HandleCommand(cmd, result)
+        return result.GetOutput().rstrip()
+
+    PERSISTENT_VAR = re.compile(r"\$\d+")
+
+    def _mask_persistent_var(self, string: str) -> str:
+        """
+        Replace persistent result variables (ex '$0', '$1', etc) with a regex
+        that matches any persistent result (r'\$\d+'). The returned string can
+        be matched against other `expression` results.
+        """
+        before, after = self.PERSISTENT_VAR.split(string, maxsplit=1)
+        return re.escape(before) + r"\$\d+" + re.escape(after)
+
+    def _expect_cmd(
+        self,
+        dwim_cmd: str,
+        actual_cmd: str,
+    ) -> None:
+        """Run dwim-print and verify the output against the expected command."""
+        # Resolve the dwim-print command to either `expression` or `frame variable`.
+        substitute_cmd = dwim_cmd.replace("dwim-print", actual_cmd, 1)
+        interp = self.dbg.GetCommandInterpreter()
+        result = lldb.SBCommandReturnObject()
+        interp.ResolveCommand(substitute_cmd, result)
+        self.assertTrue(result.Succeeded(), result.GetError())
+
+        resolved_cmd = result.GetOutput()
+        if actual_cmd == "frame variable":
+            resolved_cmd = resolved_cmd.replace(" -- ", " ", 1)
+
+        expected_output = self._run_cmd(resolved_cmd)
+
+        # Verify dwim-print chose the expected command.
+        self.runCmd("settings set dwim-print-verbosity full")
+        substrs = [f"note: ran `{resolved_cmd}`"]
+        patterns = []
+
+        if actual_cmd == "expression" and self.PERSISTENT_VAR.search(expected_output):
+            patterns.append(self._mask_persistent_var(expected_output))
+        else:
+            substrs.append(expected_output)
+
+        self.expect(dwim_cmd, substrs=substrs, patterns=patterns)
+
+    def test_variables(self):
+        """Test dwim-print with variables."""
+        self.build()
+        lldbutil.run_to_name_breakpoint(self, "main")
+        vars = ("argc", "argv")
+        for var in vars:
+            self._expect_cmd(f"dwim-print {var}", "frame variable")
+
+    def test_variable_paths(self):
+        """Test dwim-print with variable path expressions."""
+        self.build()
+        lldbutil.run_to_name_breakpoint(self, "main")
+        exprs = ("&argc", "*argv", "argv[0]")
+        for expr in exprs:
+            self._expect_cmd(f"dwim-print {expr}", "expression")
+
+    def test_expressions(self):
+        """Test dwim-print with expressions."""
+        self.build()
+        lldbutil.run_to_name_breakpoint(self, "main")
+        exprs = ("argc + 1", "(void)argc", "(int)abs(argc)")
+        for expr in exprs:
+            self._expect_cmd(f"dwim-print {expr}", "expression")
+
+    def test_dummy_target_expressions(self):
+        """Test dwim-print's ability to evaluate expressions without a target."""
+        self._expect_cmd("dwim-print 1 + 2", "expression")
+
+    def test_gdb_format(self):
+        self.build()
+        lldbutil.run_to_name_breakpoint(self, "main")
+        self._expect_cmd(f"dwim-print/x argc", "frame variable")
+        self._expect_cmd(f"dwim-print/x argc + 1", "expression")
+
+    def test_format_flags(self):
+        self.build()
+        lldbutil.run_to_name_breakpoint(self, "main")
+        self._expect_cmd(f"dwim-print -fx -- argc", "frame variable")
+        self._expect_cmd(f"dwim-print -fx -- argc + 1", "expression")
+
+    def test_display_flags(self):
+        self.build()
+        lldbutil.run_to_name_breakpoint(self, "main")
+        self._expect_cmd(f"dwim-print -T -- argc", "frame variable")
+        self._expect_cmd(f"dwim-print -T -- argc + 1", "expression")