xref: /freebsd/contrib/llvm-project/lldb/include/lldb/Interpreter/CommandObject.h (revision ec0ea6efa1ad229d75c394c1a9b9cac33af2b1d3)
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
416