contrib/llvm-project/lldb/include/lldb/Interpreter/CommandObject.h

   1 //===-- CommandObject.h -----------------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef LLDB_INTERPRETER_COMMANDOBJECT_H
  10 #define LLDB_INTERPRETER_COMMANDOBJECT_H
  11
  12 #include <map>
  13 #include <string>
  14 #include <vector>
  15
  16 #include "lldb/Utility/Flags.h"
  17
  18 #include "lldb/Interpreter/CommandCompletions.h"
  19 #include "lldb/Interpreter/Options.h"
  20 #include "lldb/Target/ExecutionContext.h"
  21 #include "lldb/Utility/Args.h"
  22 #include "lldb/Utility/CompletionRequest.h"
  23 #include "lldb/Utility/StringList.h"
  24 #include "lldb/lldb-private.h"
  25
  26 namespace lldb_private {
  27
  28 // This function really deals with CommandObjectLists, but we didn't make a
  29 // CommandObjectList class, so I'm sticking it here.  But we really should have
  30 // such a class.  Anyway, it looks up the commands in the map that match the
  31 // partial string cmd_str, inserts the matches into matches, and returns the
  32 // number added.
  33
  34 template <typename ValueType>
  35 int AddNamesMatchingPartialString(
  36     const std::map<std::string, ValueType> &in_map, llvm::StringRef cmd_str,
  37     StringList &matches, StringList *descriptions = nullptr) {
  38   int number_added = 0;
  39
  40   const bool add_all = cmd_str.empty();
  41
  42   for (auto iter = in_map.begin(), end = in_map.end(); iter != end; iter++) {
  43     if (add_all || (iter->first.find(std::string(cmd_str), 0) == 0)) {
  44       ++number_added;
  45       matches.AppendString(iter->first.c_str());
  46       if (descriptions)
  47         descriptions->AppendString(iter->second->GetHelp());
  48     }
  49   }
  50
  51   return number_added;
  52 }
  53
  54 template <typename ValueType>
  55 size_t FindLongestCommandWord(std::map<std::string, ValueType> &dict) {
  56   auto end = dict.end();
  57   size_t max_len = 0;
  58
  59   for (auto pos = dict.begin(); pos != end; ++pos) {
  60     size_t len = pos->first.size();
  61     if (max_len < len)
  62       max_len = len;
  63   }
  64   return max_len;
  65 }
  66
  67 class CommandObject {
  68 public:
  69   typedef llvm::StringRef(ArgumentHelpCallbackFunction)();
  70
  71   struct ArgumentHelpCallback {
  72     ArgumentHelpCallbackFunction *help_callback;
  73     bool self_formatting;
  74
  75     llvm::StringRef operator()() const { return (*help_callback)(); }
  76
  77     explicit operator bool() const { return (help_callback != nullptr); }
  78   };
  79
  80   struct ArgumentTableEntry // Entries in the main argument information table
  81   {
  82     lldb::CommandArgumentType arg_type;
  83     const char *arg_name;
  84     CommandCompletions::CommonCompletionTypes completion_type;
  85     ArgumentHelpCallback help_function;
  86     const char *help_text;
  87   };
  88
  89   struct CommandArgumentData // Used to build individual command argument lists
  90   {
  91     lldb::CommandArgumentType arg_type;
  92     ArgumentRepetitionType arg_repetition;
  93     /// This arg might be associated only with some particular option set(s). By
  94     /// default the arg associates to all option sets.
  95     uint32_t arg_opt_set_association;
  96
  97     CommandArgumentData(lldb::CommandArgumentType type = lldb::eArgTypeNone,
  98                         ArgumentRepetitionType repetition = eArgRepeatPlain,
  99                         uint32_t opt_set = LLDB_OPT_SET_ALL)
 100         : arg_type(type), arg_repetition(repetition),
 101           arg_opt_set_association(opt_set) {}
 102   };
 103
 104   typedef std::vector<CommandArgumentData>
 105       CommandArgumentEntry; // Used to build individual command argument lists
 106
 107   static ArgumentTableEntry g_arguments_data
 108       [lldb::eArgTypeLastArg]; // Main argument information table
 109
 110   typedef std::map<std::string, lldb::CommandObjectSP> CommandMap;
 111
 112   CommandObject(CommandInterpreter &interpreter, llvm::StringRef name,
 113     llvm::StringRef help = "", llvm::StringRef syntax = "",
 114                 uint32_t flags = 0);
 115
 116   virtual ~CommandObject() = default;
 117
 118   static const char *
 119   GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type);
 120
 121   static const char *
 122   GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type);
 123
 124   CommandInterpreter &GetCommandInterpreter() { return m_interpreter; }
 125   Debugger &GetDebugger();
 126
 127   virtual llvm::StringRef GetHelp();
 128
 129   virtual llvm::StringRef GetHelpLong();
 130
 131   virtual llvm::StringRef GetSyntax();
 132
 133   llvm::StringRef GetCommandName() const;
 134
 135   virtual void SetHelp(llvm::StringRef str);
 136
 137   virtual void SetHelpLong(llvm::StringRef str);
 138
 139   void SetSyntax(llvm::StringRef str);
 140
 141   // override this to return true if you want to enable the user to delete the
 142   // Command object from the Command dictionary (aliases have their own
 143   // deletion scheme, so they do not need to care about this)
 144   virtual bool IsRemovable() const { return false; }
 145
 146   virtual bool IsMultiwordObject() { return false; }
 147
 148   virtual CommandObjectMultiword *GetAsMultiwordCommand() { return nullptr; }
 149
 150   virtual bool IsAlias() { return false; }
 151
 152   // override this to return true if your command is somehow a "dash-dash" form
 153   // of some other command (e.g. po is expr -O --); this is a powerful hint to
 154   // the help system that one cannot pass options to this command
 155   virtual bool IsDashDashCommand() { return false; }
 156
 157   virtual lldb::CommandObjectSP GetSubcommandSP(llvm::StringRef sub_cmd,
 158                                                 StringList *matches = nullptr) {
 159     return lldb::CommandObjectSP();
 160   }
 161
 162   virtual CommandObject *GetSubcommandObject(llvm::StringRef sub_cmd,
 163                                              StringList *matches = nullptr) {
 164     return nullptr;
 165   }
 166
 167   virtual void AproposAllSubCommands(llvm::StringRef prefix,
 168                                      llvm::StringRef search_word,
 169                                      StringList &commands_found,
 170                                      StringList &commands_help) {}
 171
 172   void FormatLongHelpText(Stream &output_strm, llvm::StringRef long_help);
 173
 174   void GenerateHelpText(CommandReturnObject &result);
 175
 176   virtual void GenerateHelpText(Stream &result);
 177
 178   // this is needed in order to allow the SBCommand class to transparently try
 179   // and load subcommands - it will fail on anything but a multiword command,
 180   // but it avoids us doing type checkings and casts
 181   virtual bool LoadSubCommand(llvm::StringRef cmd_name,
 182                               const lldb::CommandObjectSP &command_obj) {
 183     return false;
 184   }
 185
 186   virtual bool WantsRawCommandString() = 0;
 187
 188   // By default, WantsCompletion = !WantsRawCommandString. Subclasses who want
 189   // raw command string but desire, for example, argument completion should
 190   // override this method to return true.
 191   virtual bool WantsCompletion() { return !WantsRawCommandString(); }
 192
 193   virtual Options *GetOptions();
 194
 195   static const ArgumentTableEntry *GetArgumentTable();
 196
 197   static lldb::CommandArgumentType LookupArgumentName(llvm::StringRef arg_name);
 198
 199   static const ArgumentTableEntry *
 200   FindArgumentDataByType(lldb::CommandArgumentType arg_type);
 201
 202   int GetNumArgumentEntries();
 203
 204   CommandArgumentEntry *GetArgumentEntryAtIndex(int idx);
 205
 206   static void GetArgumentHelp(Stream &str, lldb::CommandArgumentType arg_type,
 207                               CommandInterpreter &interpreter);
 208
 209   static const char *GetArgumentName(lldb::CommandArgumentType arg_type);
 210
 211   // Generates a nicely formatted command args string for help command output.
 212   // By default, all possible args are taken into account, for example, '<expr
 213   // | variable-name>'.  This can be refined by passing a second arg specifying
 214   // which option set(s) we are interested, which could then, for example,
 215   // produce either '<expr>' or '<variable-name>'.
 216   void GetFormattedCommandArguments(Stream &str,
 217                                     uint32_t opt_set_mask = LLDB_OPT_SET_ALL);
 218
 219   bool IsPairType(ArgumentRepetitionType arg_repeat_type);
 220
 221   bool ParseOptions(Args &args, CommandReturnObject &result);
 222
 223   void SetCommandName(llvm::StringRef name);
 224
 225   /// This default version handles calling option argument completions and then
 226   /// calls HandleArgumentCompletion if the cursor is on an argument, not an
 227   /// option. Don't override this method, override HandleArgumentCompletion
 228   /// instead unless you have special reasons.
 229   ///
 230   /// \param[in,out] request
 231   ///    The completion request that needs to be answered.
 232   virtual void HandleCompletion(CompletionRequest &request);
 233
 234   /// The input array contains a parsed version of the line.
 235   ///
 236   /// We've constructed the map of options and their arguments as well if that
 237   /// is helpful for the completion.
 238   ///
 239   /// \param[in,out] request
 240   ///    The completion request that needs to be answered.
 241   virtual void
 242   HandleArgumentCompletion(CompletionRequest &request,
 243                            OptionElementVector &opt_element_vector) {}
 244
 245   bool HelpTextContainsWord(llvm::StringRef search_word,
 246                             bool search_short_help = true,
 247                             bool search_long_help = true,
 248                             bool search_syntax = true,
 249                             bool search_options = true);
 250
 251   /// The flags accessor.
 252   ///
 253   /// \return
 254   ///     A reference to the Flags member variable.
 255   Flags &GetFlags() { return m_flags; }
 256
 257   /// The flags const accessor.
 258   ///
 259   /// \return
 260   ///     A const reference to the Flags member variable.
 261   const Flags &GetFlags() const { return m_flags; }
 262
 263   /// Get the command that appropriate for a "repeat" of the current command.
 264   ///
 265   /// \param[in] current_command_args
 266   ///    The command arguments.
 267   ///
 268   /// \return
 269   ///     nullptr if there is no special repeat command - it will use the
 270   ///     current command line.
 271   ///     Otherwise a pointer to the command to be repeated.
 272   ///     If the returned string is the empty string, the command won't be
 273   ///     repeated.
 274   virtual const char *GetRepeatCommand(Args &current_command_args,
 275                                        uint32_t index) {
 276     return nullptr;
 277   }
 278
 279   bool HasOverrideCallback() const {
 280     return m_command_override_callback ||
 281            m_deprecated_command_override_callback;
 282   }
 283
 284   void SetOverrideCallback(lldb::CommandOverrideCallback callback,
 285                            void *baton) {
 286     m_deprecated_command_override_callback = callback;
 287     m_command_override_baton = baton;
 288   }
 289
 290   void SetOverrideCallback(lldb::CommandOverrideCallbackWithResult callback,
 291                            void *baton) {
 292     m_command_override_callback = callback;
 293     m_command_override_baton = baton;
 294   }
 295
 296   bool InvokeOverrideCallback(const char **argv, CommandReturnObject &result) {
 297     if (m_command_override_callback)
 298       return m_command_override_callback(m_command_override_baton, argv,
 299                                          result);
 300     else if (m_deprecated_command_override_callback)
 301       return m_deprecated_command_override_callback(m_command_override_baton,
 302                                                     argv);
 303     else
 304       return false;
 305   }
 306
 307   virtual bool Execute(const char *args_string,
 308                        CommandReturnObject &result) = 0;
 309
 310 protected:
 311   bool ParseOptionsAndNotify(Args &args, CommandReturnObject &result,
 312                              OptionGroupOptions &group_options,
 313                              ExecutionContext &exe_ctx);
 314
 315   virtual const char *GetInvalidTargetDescription() {
 316     return "invalid target, create a target using the 'target create' command";
 317   }
 318
 319   virtual const char *GetInvalidProcessDescription() {
 320     return "invalid process";
 321   }
 322
 323   virtual const char *GetInvalidThreadDescription() { return "invalid thread"; }
 324
 325   virtual const char *GetInvalidFrameDescription() { return "invalid frame"; }
 326
 327   virtual const char *GetInvalidRegContextDescription() {
 328     return "invalid frame, no registers";
 329   }
 330
 331   // This is for use in the command interpreter, when you either want the
 332   // selected target, or if no target is present you want to prime the dummy
 333   // target with entities that will be copied over to new targets.
 334   Target &GetSelectedOrDummyTarget(bool prefer_dummy = false);
 335   Target &GetSelectedTarget();
 336   Target &GetDummyTarget();
 337
 338   // If a command needs to use the "current" thread, use this call. Command
 339   // objects will have an ExecutionContext to use, and that may or may not have
 340   // a thread in it.  If it does, you should use that by default, if not, then
 341   // use the ExecutionContext's target's selected thread, etc... This call
 342   // insulates you from the details of this calculation.
 343   Thread *GetDefaultThread();
 344
 345   /// Check the command to make sure anything required by this
 346   /// command is available.
 347   ///
 348   /// \param[out] result
 349   ///     A command result object, if it is not okay to run the command
 350   ///     this will be filled in with a suitable error.
 351   ///
 352   /// \return
 353   ///     \b true if it is okay to run this command, \b false otherwise.
 354   bool CheckRequirements(CommandReturnObject &result);
 355
 356   void Cleanup();
 357
 358   CommandInterpreter &m_interpreter;
 359   ExecutionContext m_exe_ctx;
 360   std::unique_lock<std::recursive_mutex> m_api_locker;
 361   std::string m_cmd_name;
 362   std::string m_cmd_help_short;
 363   std::string m_cmd_help_long;
 364   std::string m_cmd_syntax;
 365   Flags m_flags;
 366   std::vector<CommandArgumentEntry> m_arguments;
 367   lldb::CommandOverrideCallback m_deprecated_command_override_callback;
 368   lldb::CommandOverrideCallbackWithResult m_command_override_callback;
 369   void *m_command_override_baton;
 370
 371   // Helper function to populate IDs or ID ranges as the command argument data
 372   // to the specified command argument entry.
 373   static void AddIDsArgumentData(CommandArgumentEntry &arg,
 374                                  lldb::CommandArgumentType ID,
 375                                  lldb::CommandArgumentType IDRange);
 376 };
 377
 378 class CommandObjectParsed : public CommandObject {
 379 public:
 380   CommandObjectParsed(CommandInterpreter &interpreter, const char *name,
 381                       const char *help = nullptr, const char *syntax = nullptr,
 382                       uint32_t flags = 0)
 383       : CommandObject(interpreter, name, help, syntax, flags) {}
 384
 385   ~CommandObjectParsed() override = default;
 386
 387   bool Execute(const char *args_string, CommandReturnObject &result) override;
 388
 389 protected:
 390   virtual bool DoExecute(Args &command, CommandReturnObject &result) = 0;
 391
 392   bool WantsRawCommandString() override { return false; }
 393 };
 394
 395 class CommandObjectRaw : public CommandObject {
 396 public:
 397   CommandObjectRaw(CommandInterpreter &interpreter, llvm::StringRef name,
 398     llvm::StringRef help = "", llvm::StringRef syntax = "",
 399                    uint32_t flags = 0)
 400       : CommandObject(interpreter, name, help, syntax, flags) {}
 401
 402   ~CommandObjectRaw() override = default;
 403
 404   bool Execute(const char *args_string, CommandReturnObject &result) override;
 405
 406 protected:
 407   virtual bool DoExecute(llvm::StringRef command,
 408                          CommandReturnObject &result) = 0;
 409
 410   bool WantsRawCommandString() override { return true; }
 411 };
 412
 413 } // namespace lldb_private
 414
 415 #endif // LLDB_INTERPRETER_COMMANDOBJECT_H