1 //===-- CommandObject.h -----------------------------------------*- C++ -*-===//
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
7 //===----------------------------------------------------------------------===//
9 #ifndef LLDB_INTERPRETER_COMMANDOBJECT_H
10 #define LLDB_INTERPRETER_COMMANDOBJECT_H
16 #include "lldb/Utility/Flags.h"
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"
26 namespace lldb_private {
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
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) {
40 const bool add_all = cmd_str.empty();
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)) {
45 matches.AppendString(iter->first.c_str());
47 descriptions->AppendString(iter->second->GetHelp());
54 template <typename ValueType>
55 size_t FindLongestCommandWord(std::map<std::string, ValueType> &dict) {
56 auto end = dict.end();
59 for (auto pos = dict.begin(); pos != end; ++pos) {
60 size_t len = pos->first.size();
69 typedef llvm::StringRef(ArgumentHelpCallbackFunction)();
71 struct ArgumentHelpCallback {
72 ArgumentHelpCallbackFunction *help_callback;
75 llvm::StringRef operator()() const { return (*help_callback)(); }
77 explicit operator bool() const { return (help_callback != nullptr); }
80 struct ArgumentTableEntry // Entries in the main argument information table
82 lldb::CommandArgumentType arg_type;
84 CommandCompletions::CommonCompletionTypes completion_type;
85 ArgumentHelpCallback help_function;
86 const char *help_text;
89 struct CommandArgumentData // Used to build individual command argument lists
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;
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) {}
104 typedef std::vector<CommandArgumentData>
105 CommandArgumentEntry; // Used to build individual command argument lists
107 static ArgumentTableEntry g_arguments_data
108 [lldb::eArgTypeLastArg]; // Main argument information table
110 typedef std::map<std::string, lldb::CommandObjectSP> CommandMap;
112 CommandObject(CommandInterpreter &interpreter, llvm::StringRef name,
113 llvm::StringRef help = "", llvm::StringRef syntax = "",
116 virtual ~CommandObject() = default;
119 GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type);
122 GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type);
124 CommandInterpreter &GetCommandInterpreter() { return m_interpreter; }
125 Debugger &GetDebugger();
127 virtual llvm::StringRef GetHelp();
129 virtual llvm::StringRef GetHelpLong();
131 virtual llvm::StringRef GetSyntax();
133 llvm::StringRef GetCommandName() const;
135 virtual void SetHelp(llvm::StringRef str);
137 virtual void SetHelpLong(llvm::StringRef str);
139 void SetSyntax(llvm::StringRef str);
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; }
146 virtual bool IsMultiwordObject() { return false; }
148 bool IsUserCommand() { return m_is_user_command; }
150 void SetIsUserCommand(bool is_user) { m_is_user_command = is_user; }
152 virtual CommandObjectMultiword *GetAsMultiwordCommand() { return nullptr; }
154 virtual bool IsAlias() { return false; }
156 // override this to return true if your command is somehow a "dash-dash" form
157 // of some other command (e.g. po is expr -O --); this is a powerful hint to
158 // the help system that one cannot pass options to this command
159 virtual bool IsDashDashCommand() { return false; }
161 virtual lldb::CommandObjectSP GetSubcommandSP(llvm::StringRef sub_cmd,
162 StringList *matches = nullptr) {
163 return lldb::CommandObjectSP();
166 virtual lldb::CommandObjectSP GetSubcommandSPExact(llvm::StringRef sub_cmd) {
167 return lldb::CommandObjectSP();
170 virtual CommandObject *GetSubcommandObject(llvm::StringRef sub_cmd,
171 StringList *matches = nullptr) {
175 void FormatLongHelpText(Stream &output_strm, llvm::StringRef long_help);
177 void GenerateHelpText(CommandReturnObject &result);
179 virtual void GenerateHelpText(Stream &result);
181 // this is needed in order to allow the SBCommand class to transparently try
182 // and load subcommands - it will fail on anything but a multiword command,
183 // but it avoids us doing type checkings and casts
184 virtual bool LoadSubCommand(llvm::StringRef cmd_name,
185 const lldb::CommandObjectSP &command_obj) {
189 virtual llvm::Error LoadUserSubcommand(llvm::StringRef cmd_name,
190 const lldb::CommandObjectSP &command_obj,
192 return llvm::createStringError(llvm::inconvertibleErrorCode(),
193 "can only add commands to container commands");
196 virtual bool WantsRawCommandString() = 0;
198 // By default, WantsCompletion = !WantsRawCommandString. Subclasses who want
199 // raw command string but desire, for example, argument completion should
200 // override this method to return true.
201 virtual bool WantsCompletion() { return !WantsRawCommandString(); }
203 virtual Options *GetOptions();
205 static const ArgumentTableEntry *GetArgumentTable();
207 static lldb::CommandArgumentType LookupArgumentName(llvm::StringRef arg_name);
209 static const ArgumentTableEntry *
210 FindArgumentDataByType(lldb::CommandArgumentType arg_type);
212 int GetNumArgumentEntries();
214 CommandArgumentEntry *GetArgumentEntryAtIndex(int idx);
216 static void GetArgumentHelp(Stream &str, lldb::CommandArgumentType arg_type,
217 CommandInterpreter &interpreter);
219 static const char *GetArgumentName(lldb::CommandArgumentType arg_type);
221 // Generates a nicely formatted command args string for help command output.
222 // By default, all possible args are taken into account, for example, '<expr
223 // | variable-name>'. This can be refined by passing a second arg specifying
224 // which option set(s) we are interested, which could then, for example,
225 // produce either '<expr>' or '<variable-name>'.
226 void GetFormattedCommandArguments(Stream &str,
227 uint32_t opt_set_mask = LLDB_OPT_SET_ALL);
229 bool IsPairType(ArgumentRepetitionType arg_repeat_type);
231 bool ParseOptions(Args &args, CommandReturnObject &result);
233 void SetCommandName(llvm::StringRef name);
235 /// This default version handles calling option argument completions and then
236 /// calls HandleArgumentCompletion if the cursor is on an argument, not an
237 /// option. Don't override this method, override HandleArgumentCompletion
238 /// instead unless you have special reasons.
240 /// \param[in,out] request
241 /// The completion request that needs to be answered.
242 virtual void HandleCompletion(CompletionRequest &request);
244 /// The input array contains a parsed version of the line.
246 /// We've constructed the map of options and their arguments as well if that
247 /// is helpful for the completion.
249 /// \param[in,out] request
250 /// The completion request that needs to be answered.
252 HandleArgumentCompletion(CompletionRequest &request,
253 OptionElementVector &opt_element_vector) {}
255 bool HelpTextContainsWord(llvm::StringRef search_word,
256 bool search_short_help = true,
257 bool search_long_help = true,
258 bool search_syntax = true,
259 bool search_options = true);
261 /// The flags accessor.
264 /// A reference to the Flags member variable.
265 Flags &GetFlags() { return m_flags; }
267 /// The flags const accessor.
270 /// A const reference to the Flags member variable.
271 const Flags &GetFlags() const { return m_flags; }
273 /// Get the command that appropriate for a "repeat" of the current command.
275 /// \param[in] current_command_args
276 /// The command arguments.
279 /// nullptr if there is no special repeat command - it will use the
280 /// current command line.
281 /// Otherwise a pointer to the command to be repeated.
282 /// If the returned string is the empty string, the command won't be
284 virtual const char *GetRepeatCommand(Args ¤t_command_args,
289 bool HasOverrideCallback() const {
290 return m_command_override_callback ||
291 m_deprecated_command_override_callback;
294 void SetOverrideCallback(lldb::CommandOverrideCallback callback,
296 m_deprecated_command_override_callback = callback;
297 m_command_override_baton = baton;
300 void SetOverrideCallback(lldb::CommandOverrideCallbackWithResult callback,
302 m_command_override_callback = callback;
303 m_command_override_baton = baton;
306 bool InvokeOverrideCallback(const char **argv, CommandReturnObject &result) {
307 if (m_command_override_callback)
308 return m_command_override_callback(m_command_override_baton, argv,
310 else if (m_deprecated_command_override_callback)
311 return m_deprecated_command_override_callback(m_command_override_baton,
317 virtual bool Execute(const char *args_string,
318 CommandReturnObject &result) = 0;
321 bool ParseOptionsAndNotify(Args &args, CommandReturnObject &result,
322 OptionGroupOptions &group_options,
323 ExecutionContext &exe_ctx);
325 virtual const char *GetInvalidTargetDescription() {
326 return "invalid target, create a target using the 'target create' command";
329 virtual const char *GetInvalidProcessDescription() {
330 return "invalid process";
333 virtual const char *GetInvalidThreadDescription() { return "invalid thread"; }
335 virtual const char *GetInvalidFrameDescription() { return "invalid frame"; }
337 virtual const char *GetInvalidRegContextDescription() {
338 return "invalid frame, no registers";
341 // This is for use in the command interpreter, when you either want the
342 // selected target, or if no target is present you want to prime the dummy
343 // target with entities that will be copied over to new targets.
344 Target &GetSelectedOrDummyTarget(bool prefer_dummy = false);
345 Target &GetSelectedTarget();
346 Target &GetDummyTarget();
348 // If a command needs to use the "current" thread, use this call. Command
349 // objects will have an ExecutionContext to use, and that may or may not have
350 // a thread in it. If it does, you should use that by default, if not, then
351 // use the ExecutionContext's target's selected thread, etc... This call
352 // insulates you from the details of this calculation.
353 Thread *GetDefaultThread();
355 /// Check the command to make sure anything required by this
356 /// command is available.
358 /// \param[out] result
359 /// A command result object, if it is not okay to run the command
360 /// this will be filled in with a suitable error.
363 /// \b true if it is okay to run this command, \b false otherwise.
364 bool CheckRequirements(CommandReturnObject &result);
368 CommandInterpreter &m_interpreter;
369 ExecutionContext m_exe_ctx;
370 std::unique_lock<std::recursive_mutex> m_api_locker;
371 std::string m_cmd_name;
372 std::string m_cmd_help_short;
373 std::string m_cmd_help_long;
374 std::string m_cmd_syntax;
376 std::vector<CommandArgumentEntry> m_arguments;
377 lldb::CommandOverrideCallback m_deprecated_command_override_callback;
378 lldb::CommandOverrideCallbackWithResult m_command_override_callback;
379 void *m_command_override_baton;
380 bool m_is_user_command = false;
382 // Helper function to populate IDs or ID ranges as the command argument data
383 // to the specified command argument entry.
384 static void AddIDsArgumentData(CommandArgumentEntry &arg,
385 lldb::CommandArgumentType ID,
386 lldb::CommandArgumentType IDRange);
389 class CommandObjectParsed : public CommandObject {
391 CommandObjectParsed(CommandInterpreter &interpreter, const char *name,
392 const char *help = nullptr, const char *syntax = nullptr,
394 : CommandObject(interpreter, name, help, syntax, flags) {}
396 ~CommandObjectParsed() override = default;
398 bool Execute(const char *args_string, CommandReturnObject &result) override;
401 virtual bool DoExecute(Args &command, CommandReturnObject &result) = 0;
403 bool WantsRawCommandString() override { return false; }
406 class CommandObjectRaw : public CommandObject {
408 CommandObjectRaw(CommandInterpreter &interpreter, llvm::StringRef name,
409 llvm::StringRef help = "", llvm::StringRef syntax = "",
411 : CommandObject(interpreter, name, help, syntax, flags) {}
413 ~CommandObjectRaw() override = default;
415 bool Execute(const char *args_string, CommandReturnObject &result) override;
418 virtual bool DoExecute(llvm::StringRef command,
419 CommandReturnObject &result) = 0;
421 bool WantsRawCommandString() override { return true; }
424 } // namespace lldb_private
426 #endif // LLDB_INTERPRETER_COMMANDOBJECT_H