[lldb/Commands] Add scripting template list command with auto discovery

This patch introduces a new `template` multiword sub-command to the
`scripting` top-level command. As the name suggests, this sub-command
operates on scripting templates, and currently has the ability to
automatically discover the various scripting extensions that lldb
supports.

Signed-off-by: Med Ismail Bennani <[email protected]>

Author: medismailben

lldb/include/lldb/Core/PluginManager.h

@@ -487,6 +487,31 @@ class PluginManager {
 
   static LanguageSet GetAllTypeSystemSupportedLanguagesForExpressions();
 
+  // Scripted Interface
+  static bool
+  RegisterPlugin(llvm::StringRef name, llvm::StringRef description,
+                 ScriptedInterfaceCreateInstance create_callback,
+                 lldb::ScriptLanguage language,
+                 std::vector<llvm::StringRef> command_interpreter_usages,
+                 std::vector<llvm::StringRef> api_usages);
+
+  static bool UnregisterPlugin(ScriptedInterfaceCreateInstance create_callback);
+
+  static ScriptedInterfaceCreateInstance
+  GetScriptedInterfaceCreateCallbackAtIndex(uint32_t idx);
+
+  static llvm::StringRef GetScriptedInterfaceNameAtIndex(uint32_t idx);
+
+  static llvm::StringRef GetScriptedInterfaceDescriptionAtIndex(uint32_t idx);
+
+  static lldb::ScriptLanguage GetScriptedInterfaceLanguageAtIndex(uint32_t idx);
+
+  static std::vector<llvm::StringRef>
+  GetScriptedInterfaceCommandInterpreterUsagesAtIndex(uint32_t idx);
+
+  static std::vector<llvm::StringRef>
+  GetScriptedInterfaceAPIUsagesAtIndex(uint32_t idx);
+
   // REPL
   static bool RegisterPlugin(llvm::StringRef name, llvm::StringRef description,
                              REPLCreateInstance create_callback,

lldb/include/lldb/Interpreter/Interfaces/ScriptedInterface.h

@@ -68,6 +68,13 @@ class ScriptedInterface {
     return true;
   }
 
+  static bool
+  CreateInstance(lldb::ScriptLanguage language,
+                 std::vector<llvm::StringRef> command_interpreter_usages,
+                 std::vector<llvm::StringRef> api_usages) {
+    return false;
+  }
+
 protected:
   StructuredData::GenericSP m_object_instance_sp;
 };

lldb/include/lldb/lldb-private-interfaces.h

@@ -124,6 +124,10 @@ typedef lldb::REPLSP (*REPLCreateInstance)(Status &error,
                                            lldb::LanguageType language,
                                            Debugger *debugger, Target *target,
                                            const char *repl_options);
+typedef bool (*ScriptedInterfaceCreateInstance)(
+    lldb::ScriptLanguage language,
+    std::vector<llvm::StringRef> command_interpreter_usages,
+    std::vector<llvm::StringRef> api_usages);
 typedef int (*ComparisonFunction)(const void *, const void *);
 typedef void (*DebuggerInitializeCallback)(Debugger &debugger);
 /// Trace

lldb/source/Commands/CommandObjectScripting.cpp

@@ -8,6 +8,7 @@
 
 #include "CommandObjectScripting.h"
 #include "lldb/Core/Debugger.h"
+#include "lldb/Core/PluginManager.h"
 #include "lldb/DataFormatters/DataVisualization.h"
 #include "lldb/Host/Config.h"
 #include "lldb/Host/OptionParser.h"
@@ -21,6 +22,8 @@
 using namespace lldb;
 using namespace lldb_private;
 
+#pragma mark CommandObjectScriptingExecute
+
 #define LLDB_OPTIONS_scripting_execute
 #include "CommandOptions.inc"
 
@@ -114,6 +117,159 @@ void CommandObjectScriptingExecute::DoExecute(llvm::StringRef command,
     result.SetStatus(eReturnStatusFailed);
 }
 
+#pragma mark CommandObjectScriptingTemplateList
+
+#define LLDB_OPTIONS_scripting_template_list
+#include "CommandOptions.inc"
+
+Status CommandObjectScriptingTemplateList::CommandOptions::SetOptionValue(
+    uint32_t option_idx, llvm::StringRef option_arg,
+    ExecutionContext *execution_context) {
+  Status error;
+  const int short_option = m_getopt_table[option_idx].val;
+
+  switch (short_option) {
+  case 'l':
+    language = (lldb::ScriptLanguage)OptionArgParser::ToOptionEnum(
+        option_arg, GetDefinitions()[option_idx].enum_values,
+        eScriptLanguageNone, error);
+    if (!error.Success())
+      error.SetErrorStringWithFormat("unrecognized value for language '%s'",
+                                     option_arg.str().c_str());
+    break;
+  default:
+    llvm_unreachable("Unimplemented option");
+  }
+
+  return error;
+}
+
+void CommandObjectScriptingTemplateList::CommandOptions::OptionParsingStarting(
+    ExecutionContext *execution_context) {
+  language = lldb::eScriptLanguageNone;
+}
+
+llvm::ArrayRef<OptionDefinition>
+CommandObjectScriptingTemplateList::CommandOptions::GetDefinitions() {
+  return llvm::ArrayRef(g_scripting_execute_options);
+}
+
+CommandObjectScriptingTemplateList::CommandObjectScriptingTemplateList(
+    CommandInterpreter &interpreter)
+    : CommandObjectParsed(
+          interpreter, "scripting template list",
+          "List all the available scripting affordances templates. ",
+          "scripting template list [--language <scripting-language> --]") {}
+
+CommandObjectScriptingTemplateList::~CommandObjectScriptingTemplateList() =
+    default;
+
+void CommandObjectScriptingTemplateList::DoExecute(
+    Args &command, CommandReturnObject &result) {
+  lldb::ScriptLanguage language =
+      (m_options.language == lldb::eScriptLanguageNone)
+          ? m_interpreter.GetDebugger().GetScriptLanguage()
+          : m_options.language;
+
+  if (language == lldb::eScriptLanguageNone) {
+    result.AppendError(
+        "the script-lang setting is set to none - scripting not available");
+    return;
+  }
+
+  ScriptInterpreter *script_interpreter =
+      GetDebugger().GetScriptInterpreter(true, language);
+
+  if (script_interpreter == nullptr) {
+    result.AppendError("no script interpreter");
+    return;
+  }
+
+  Stream &s = result.GetOutputStream();
+  s.Printf("Available scripted affordances:\n");
+
+  auto print_field = [&s](llvm::StringRef key, llvm::StringRef value,
+                          bool check_validy = false) {
+    if (!check_validy || !value.empty()) {
+      s.IndentMore();
+      s.Indent();
+      s << key << ": " << value << '\n';
+      s.IndentLess();
+    }
+  };
+  auto print_usages = [&s](llvm::StringRef usage_kind,
+                           std::vector<llvm::StringRef> &usages) {
+    s.IndentMore();
+    s.Indent();
+    s << usage_kind << " Usages:";
+    if (usages.empty())
+      s << " No usages.\n";
+    else if (usages.size() == 1)
+      s << " " << usages.front() << '\n';
+    else {
+      s << '\n';
+      for (llvm::StringRef usage : usages) {
+        s.IndentMore();
+        s.Indent();
+        s << usage << '\n';
+        s.IndentLess();
+      }
+    }
+    s.IndentLess();
+  };
+
+  size_t i = 0;
+  for (llvm::StringRef plugin_name =
+           PluginManager::GetScriptedInterfaceNameAtIndex(i);
+       !plugin_name.empty();) {
+
+    llvm::StringRef desc =
+        PluginManager::GetScriptedInterfaceDescriptionAtIndex(i);
+    lldb::ScriptLanguage lang =
+        PluginManager::GetScriptedInterfaceLanguageAtIndex(i);
+    std::vector<llvm::StringRef> ci_usages =
+        PluginManager::GetScriptedInterfaceCommandInterpreterUsagesAtIndex(i);
+    std::vector<llvm::StringRef> api_usages =
+        PluginManager::GetScriptedInterfaceAPIUsagesAtIndex(i);
+
+    print_field("Name", plugin_name);
+    switch (lang) {
+    case eScriptLanguagePython:
+      print_field("Language", "Python");
+      break;
+    case eScriptLanguageLua:
+      print_field("Language", "Lua");
+      break;
+    default:
+      break;
+    }
+    print_field("Description", desc);
+    print_usages("Command Interpreter", ci_usages);
+    print_usages("API", api_usages);
+
+    plugin_name = PluginManager::GetScriptedInterfaceNameAtIndex(++i);
+    if (!plugin_name.empty())
+      s.EOL();
+  }
+}
+
+#pragma mark CommandObjectMultiwordScriptingTemplate
+
+// CommandObjectMultiwordScriptingTemplate
+
+CommandObjectMultiwordScriptingTemplate::
+    CommandObjectMultiwordScriptingTemplate(CommandInterpreter &interpreter)
+    : CommandObjectMultiword(
+          interpreter, "scripting template",
+          "Commands for operating on the scripting templates.",
+          "scripting template [<subcommand-options>]") {
+  LoadSubCommand("list", CommandObjectSP(new CommandObjectScriptingTemplateList(
+                             interpreter)));
+}
+
+CommandObjectMultiwordScriptingTemplate::
+    ~CommandObjectMultiwordScriptingTemplate() = default;
+
 #pragma mark CommandObjectMultiwordScripting
 
 // CommandObjectMultiwordScripting
@@ -126,6 +282,9 @@ CommandObjectMultiwordScripting::CommandObjectMultiwordScripting(
           "scripting <subcommand> [<subcommand-options>]") {
   LoadSubCommand("execute", CommandObjectSP(new CommandObjectScriptingExecute(
                                 interpreter)));
+  LoadSubCommand("template",
+                 CommandObjectSP(
+                     new CommandObjectMultiwordScriptingTemplate(interpreter)));
 }
 
 CommandObjectMultiwordScripting::~CommandObjectMultiwordScripting() = default;

lldb/source/Commands/CommandObjectScripting.h

@@ -44,6 +44,37 @@ class CommandObjectScriptingExecute : public CommandObjectRaw {
   CommandOptions m_options;
 };
 
+class CommandObjectMultiwordScriptingTemplate : public CommandObjectMultiword {
+public:
+  CommandObjectMultiwordScriptingTemplate(CommandInterpreter &interpreter);
+
+  ~CommandObjectMultiwordScriptingTemplate() override;
+};
+
+class CommandObjectScriptingTemplateList : public CommandObjectParsed {
+public:
+  CommandObjectScriptingTemplateList(CommandInterpreter &interpreter);
+  ~CommandObjectScriptingTemplateList() override;
+  Options *GetOptions() override { return &m_options; }
+
+  class CommandOptions : public Options {
+  public:
+    CommandOptions() = default;
+    ~CommandOptions() override = default;
+    Status SetOptionValue(uint32_t option_idx, llvm::StringRef option_arg,
+                          ExecutionContext *execution_context) override;
+    void OptionParsingStarting(ExecutionContext *execution_context) override;
+    llvm::ArrayRef<OptionDefinition> GetDefinitions() override;
+    lldb::ScriptLanguage language = lldb::eScriptLanguageNone;
+  };
+
+protected:
+  void DoExecute(Args &command, CommandReturnObject &result) override;
+
+private:
+  CommandOptions m_options;
+};
+
 } // namespace lldb_private
 
 #endif // LLDB_SOURCE_INTERPRETER_COMMANDOBJECTSCRIPT_H

lldb/source/Commands/Options.td

@@ -836,7 +836,13 @@ let Command = "container add" in {
 }
 
 let Command = "scripting execute" in {
-  def script_language : Option<"language", "l">,
+  def scripting_execute_language : Option<"language", "l">,
+    EnumArg<"ScriptLang">, Desc<"Specify the scripting "
+    " language. If none is specific the default scripting language is used.">;
+}
+
+let Command = "scripting template list" in {
+  def scripting_template_list_language : Option<"language", "l">,
     EnumArg<"ScriptLang">, Desc<"Specify the scripting "
     " language. If none is specific the default scripting language is used.">;
 }

lldb/source/Core/PluginManager.cpp

@@ -1479,6 +1479,88 @@ LanguageSet PluginManager::GetAllTypeSystemSupportedLanguagesForExpressions() {
   return all;
 }
 
+#pragma mark ScriptedInterfaces
+
+struct ScriptedInterfaceInstance
+    : public PluginInstance<ScriptedInterfaceCreateInstance> {
+  ScriptedInterfaceInstance(
+      llvm::StringRef name, llvm::StringRef description,
+      ScriptedInterfaceCreateInstance create_callback,
+      lldb::ScriptLanguage language,
+      std::vector<llvm::StringRef> command_interpreter_usages,
+      std::vector<llvm::StringRef> api_usages)
+      : PluginInstance<ScriptedInterfaceCreateInstance>(name, description,
+                                                        create_callback),
+        language(language),
+        command_interpreter_usages(command_interpreter_usages),
+        api_usages(api_usages) {}
+
+  lldb::ScriptLanguage language;
+  std::vector<llvm::StringRef> command_interpreter_usages;
+  std::vector<llvm::StringRef> api_usages;
+};
+
+typedef PluginInstances<ScriptedInterfaceInstance> ScriptedInterfaceInstances;
+
+static ScriptedInterfaceInstances &GetScriptedInterfaceInstances() {
+  static ScriptedInterfaceInstances g_instances;
+  return g_instances;
+}
+
+bool PluginManager::RegisterPlugin(
+    llvm::StringRef name, llvm::StringRef description,
+    ScriptedInterfaceCreateInstance create_callback,
+    lldb::ScriptLanguage language,
+    std::vector<llvm::StringRef> command_interpreter_usages,
+    std::vector<llvm::StringRef> api_usages) {
+  return GetScriptedInterfaceInstances().RegisterPlugin(
+      name, description, create_callback, language, command_interpreter_usages,
+      api_usages);
+}
+
+bool PluginManager::UnregisterPlugin(
+    ScriptedInterfaceCreateInstance create_callback) {
+  return GetScriptedInterfaceInstances().UnregisterPlugin(create_callback);
+}
+
+ScriptedInterfaceCreateInstance
+PluginManager::GetScriptedInterfaceCreateCallbackAtIndex(uint32_t idx) {
+  return GetScriptedInterfaceInstances().GetCallbackAtIndex(idx);
+}
+
+llvm::StringRef PluginManager::GetScriptedInterfaceNameAtIndex(uint32_t index) {
+  return GetScriptedInterfaceInstances().GetNameAtIndex(index);
+}
+
+llvm::StringRef
+PluginManager::GetScriptedInterfaceDescriptionAtIndex(uint32_t index) {
+  return GetScriptedInterfaceInstances().GetDescriptionAtIndex(index);
+}
+
+lldb::ScriptLanguage
+PluginManager::GetScriptedInterfaceLanguageAtIndex(uint32_t idx) {
+  const auto &instances = GetScriptedInterfaceInstances().GetInstances();
+  return idx < instances.size() ? instances[idx].language
+                                : ScriptLanguage::eScriptLanguageNone;
+}
+
+std::vector<llvm::StringRef>
+PluginManager::GetScriptedInterfaceCommandInterpreterUsagesAtIndex(
+    uint32_t idx) {
+  const auto &instances = GetScriptedInterfaceInstances().GetInstances();
+  if (idx >= instances.size())
+    return {};
+  return instances[idx].command_interpreter_usages;
+}
+
+std::vector<llvm::StringRef>
+PluginManager::GetScriptedInterfaceAPIUsagesAtIndex(uint32_t idx) {
+  const auto &instances = GetScriptedInterfaceInstances().GetInstances();
+  if (idx >= instances.size())
+    return {};
+  return instances[idx].api_usages;
+}
+
 #pragma mark REPL
 
 struct REPLInstance : public PluginInstance<REPLCreateInstance> {
@@ -1539,6 +1621,7 @@ void PluginManager::DebuggerInitialize(Debugger &debugger) {
   GetOperatingSystemInstances().PerformDebuggerCallback(debugger);
   GetStructuredDataPluginInstances().PerformDebuggerCallback(debugger);
   GetTracePluginInstances().PerformDebuggerCallback(debugger);
+  GetScriptedInterfaceInstances().PerformDebuggerCallback(debugger);
 }
 
 // This is the preferred new way to register plugin specific settings.  e.g.