Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 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 | |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 9 | #ifndef LLDB_INTERPRETER_COMMANDOBJECT_H |
| 10 | #define LLDB_INTERPRETER_COMMANDOBJECT_H |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 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++) { |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 43 | if (add_all || (iter->first.find(std::string(cmd_str), 0) == 0)) { |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 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; |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 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) {} |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 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(); |
| 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 | /// |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 230 | /// \param[in,out] request |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 231 | /// The completion request that needs to be answered. |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 232 | virtual void HandleCompletion(CompletionRequest &request); |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 233 | |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 234 | /// The input array contains a parsed version of the line. |
| 235 | /// |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 236 | /// We've constructed the map of options and their arguments as well if that |
| 237 | /// is helpful for the completion. |
| 238 | /// |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 239 | /// \param[in,out] request |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 240 | /// The completion request that needs to be answered. |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 241 | virtual void |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 242 | HandleArgumentCompletion(CompletionRequest &request, |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 243 | OptionElementVector &opt_element_vector) {} |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 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 | /// |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 265 | /// \param[in] current_command_args |
| 266 | /// The command arguments. |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 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 ¤t_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. |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 334 | Target &GetSelectedOrDummyTarget(bool prefer_dummy = false); |
| 335 | Target &GetSelectedTarget(); |
| 336 | Target &GetDummyTarget(); |
Andrew Walbran | 3d2c197 | 2020-04-07 12:24:26 +0100 | [diff] [blame] | 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 | |
Olivier Deprez | f4ef2d0 | 2021-04-20 13:36:24 +0200 | [diff] [blame] | 415 | #endif // LLDB_INTERPRETER_COMMANDOBJECT_H |