1 //===-- CommandObject.h -----------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_CommandObject_h_
11 #define liblldb_CommandObject_h_
18 #include "lldb/lldb-private.h"
19 #include "lldb/Interpreter/Args.h"
20 #include "lldb/Interpreter/CommandCompletions.h"
21 #include "lldb/Core/StringList.h"
22 #include "lldb/Core/Flags.h"
23 #include "lldb/Host/Mutex.h"
24 #include "lldb/Target/ExecutionContext.h"
26 namespace lldb_private {
32 typedef const char *(ArgumentHelpCallbackFunction) ();
34 struct ArgumentHelpCallback
36 ArgumentHelpCallbackFunction *help_callback;
42 return (*help_callback)();
45 explicit operator bool() const
47 return (help_callback != NULL);
52 struct ArgumentTableEntry // Entries in the main argument information table
54 lldb::CommandArgumentType arg_type;
56 CommandCompletions::CommonCompletionTypes completion_type;
57 ArgumentHelpCallback help_function;
58 const char *help_text;
61 struct CommandArgumentData // Used to build individual command argument lists
63 lldb::CommandArgumentType arg_type;
64 ArgumentRepetitionType arg_repetition;
65 uint32_t arg_opt_set_association; // This arg might be associated only with some particular option set(s).
66 CommandArgumentData():
67 arg_type(lldb::eArgTypeNone),
68 arg_repetition(eArgRepeatPlain),
69 arg_opt_set_association(LLDB_OPT_SET_ALL) // By default, the arg associates to all option sets.
73 typedef std::vector<CommandArgumentData> CommandArgumentEntry; // Used to build individual command argument lists
75 static ArgumentTableEntry g_arguments_data[lldb::eArgTypeLastArg]; // Main argument information table
77 typedef std::map<std::string, lldb::CommandObjectSP> CommandMap;
79 CommandObject (CommandInterpreter &interpreter,
81 const char *help = NULL,
82 const char *syntax = NULL,
90 GetArgumentTypeAsCString (const lldb::CommandArgumentType arg_type);
93 GetArgumentDescriptionAsCString (const lldb::CommandArgumentType arg_type);
96 GetCommandInterpreter ()
114 SetHelp (const char * str);
117 SetHelp (std::string str);
120 SetHelpLong (const char * str);
123 SetHelpLong (std::string str);
126 SetSyntax (const char *str);
128 // override this to return true if you want to enable the user to delete
129 // the Command object from the Command dictionary (aliases have their own
130 // deletion scheme, so they do not need to care about this)
132 IsRemovable () const { return false; }
135 IsAlias () { return m_is_alias; }
138 SetIsAlias (bool value) { m_is_alias = value; }
141 IsMultiwordObject () { return false; }
143 virtual lldb::CommandObjectSP
144 GetSubcommandSP (const char *sub_cmd, StringList *matches = NULL)
146 return lldb::CommandObjectSP();
149 virtual CommandObject *
150 GetSubcommandObject (const char *sub_cmd, StringList *matches = NULL)
156 AproposAllSubCommands (const char *prefix,
157 const char *search_word,
158 StringList &commands_found,
159 StringList &commands_help)
164 GenerateHelpText (CommandReturnObject &result);
167 GenerateHelpText (Stream &result);
169 // this is needed in order to allow the SBCommand class to
170 // transparently try and load subcommands - it will fail on
171 // anything but a multiword command, but it avoids us doing
172 // type checkings and casts
174 LoadSubCommand (const char *cmd_name,
175 const lldb::CommandObjectSP& command_obj)
181 WantsRawCommandString() = 0;
183 // By default, WantsCompletion = !WantsRawCommandString.
184 // Subclasses who want raw command string but desire, for example,
185 // argument completion should override this method to return true.
187 WantsCompletion() { return !WantsRawCommandString(); }
192 static const ArgumentTableEntry*
195 static lldb::CommandArgumentType
196 LookupArgumentName (const char *arg_name);
198 static const ArgumentTableEntry *
199 FindArgumentDataByType (lldb::CommandArgumentType arg_type);
202 GetNumArgumentEntries ();
204 CommandArgumentEntry *
205 GetArgumentEntryAtIndex (int idx);
208 GetArgumentHelp (Stream &str, lldb::CommandArgumentType arg_type, CommandInterpreter &interpreter);
211 GetArgumentName (lldb::CommandArgumentType arg_type);
213 // Generates a nicely formatted command args string for help command output.
214 // By default, all possible args are taken into account, for example,
215 // '<expr | variable-name>'. This can be refined by passing a second arg
216 // specifying which option set(s) we are interested, which could then, for
217 // example, produce either '<expr>' or '<variable-name>'.
219 GetFormattedCommandArguments (Stream &str, uint32_t opt_set_mask = LLDB_OPT_SET_ALL);
222 IsPairType (ArgumentRepetitionType arg_repeat_type);
225 ParseOptions (Args& args, CommandReturnObject &result);
228 SetCommandName (const char *name);
230 // This function really deals with CommandObjectLists, but we didn't make a
231 // CommandObjectList class, so I'm sticking it here. But we really should have
232 // such a class. Anyway, it looks up the commands in the map that match the partial
233 // string cmd_str, inserts the matches into matches, and returns the number added.
236 AddNamesMatchingPartialString (CommandMap &in_map, const char *cmd_str, StringList &matches);
238 //------------------------------------------------------------------
239 /// The input array contains a parsed version of the line. The insertion
240 /// point is given by cursor_index (the index in input of the word containing
241 /// the cursor) and cursor_char_position (the position of the cursor in that word.)
242 /// This default version handles calling option argument completions and then calls
243 /// HandleArgumentCompletion if the cursor is on an argument, not an option.
244 /// Don't override this method, override HandleArgumentCompletion instead unless
245 /// you have special reasons.
247 /// @param[in] interpreter
248 /// The command interpreter doing the completion.
251 /// The command line parsed into words
253 /// @param[in] cursor_index
254 /// The index in \ainput of the word in which the cursor lies.
256 /// @param[in] cursor_char_pos
257 /// The character position of the cursor in its argument word.
259 /// @param[in] match_start_point
260 /// @param[in] match_return_elements
261 /// FIXME: Not yet implemented... If there is a match that is expensive to compute, these are
262 /// here to allow you to compute the completions in batches. Start the completion from \amatch_start_point,
263 /// and return \amatch_return_elements elements.
265 /// @param[out] word_complete
266 /// \btrue if this is a complete option value (a space will be inserted after the
267 /// completion.) \bfalse otherwise.
269 /// @param[out] matches
270 /// The array of matches returned.
272 /// FIXME: This is the wrong return value, since we also need to make a distinction between
273 /// total number of matches, and the window the user wants returned.
276 /// \btrue if we were in an option, \bfalse otherwise.
277 //------------------------------------------------------------------
279 HandleCompletion (Args &input,
281 int &cursor_char_position,
282 int match_start_point,
283 int max_return_elements,
285 StringList &matches);
287 //------------------------------------------------------------------
288 /// The input array contains a parsed version of the line. The insertion
289 /// point is given by cursor_index (the index in input of the word containing
290 /// the cursor) and cursor_char_position (the position of the cursor in that word.)
291 /// We've constructed the map of options and their arguments as well if that is
292 /// helpful for the completion.
294 /// @param[in] interpreter
295 /// The command interpreter doing the completion.
298 /// The command line parsed into words
300 /// @param[in] cursor_index
301 /// The index in \ainput of the word in which the cursor lies.
303 /// @param[in] cursor_char_pos
304 /// The character position of the cursor in its argument word.
306 /// @param[in] opt_element_vector
307 /// The results of the options parse of \a input.
309 /// @param[in] match_start_point
310 /// @param[in] match_return_elements
311 /// See CommandObject::HandleCompletions for a description of how these work.
313 /// @param[out] word_complete
314 /// \btrue if this is a complete option value (a space will be inserted after the
315 /// completion.) \bfalse otherwise.
317 /// @param[out] matches
318 /// The array of matches returned.
320 /// FIXME: This is the wrong return value, since we also need to make a distinction between
321 /// total number of matches, and the window the user wants returned.
324 /// The number of completions.
325 //------------------------------------------------------------------
328 HandleArgumentCompletion (Args &input,
330 int &cursor_char_position,
331 OptionElementVector &opt_element_vector,
332 int match_start_point,
333 int max_return_elements,
341 HelpTextContainsWord (const char *search_word);
343 //------------------------------------------------------------------
344 /// The flags accessor.
347 /// A reference to the Flags member variable.
348 //------------------------------------------------------------------
355 //------------------------------------------------------------------
356 /// The flags const accessor.
359 /// A const reference to the Flags member variable.
360 //------------------------------------------------------------------
367 //------------------------------------------------------------------
368 /// Get the command that appropriate for a "repeat" of the current command.
370 /// @param[in] current_command_line
371 /// The complete current command line.
374 /// NULL if there is no special repeat command - it will use the current command line.
375 /// Otherwise a pointer to the command to be repeated.
376 /// If the returned string is the empty string, the command won't be repeated.
377 //------------------------------------------------------------------
378 virtual const char *GetRepeatCommand (Args ¤t_command_args, uint32_t index)
384 HasOverrideCallback () const
386 return m_command_override_callback || m_deprecated_command_override_callback;
390 SetOverrideCallback (lldb::CommandOverrideCallback callback, void *baton)
392 m_deprecated_command_override_callback = callback;
393 m_command_override_baton = baton;
397 SetOverrideCallback (lldb::CommandOverrideCallbackWithResult callback, void *baton)
399 m_command_override_callback = callback;
400 m_command_override_baton = baton;
404 InvokeOverrideCallback (const char **argv, CommandReturnObject &result)
406 if (m_command_override_callback)
407 return m_command_override_callback(m_command_override_baton, argv, result);
408 else if (m_deprecated_command_override_callback)
409 return m_deprecated_command_override_callback(m_command_override_baton, argv);
415 Execute (const char *args_string, CommandReturnObject &result) = 0;
419 GetInvalidTargetDescription()
421 return "invalid target, create a target using the 'target create' command";
425 GetInvalidProcessDescription()
427 return "invalid process";
431 GetInvalidThreadDescription()
433 return "invalid thread";
437 GetInvalidFrameDescription()
439 return "invalid frame";
443 GetInvalidRegContextDescription ()
445 return "invalid frame, no registers";
448 // This is for use in the command interpreter, when you either want the selected target, or if no target
449 // is present you want to prime the dummy target with entities that will be copied over to new targets.
450 Target *GetSelectedOrDummyTarget(bool prefer_dummy = false);
451 Target *GetDummyTarget();
453 //------------------------------------------------------------------
454 /// Check the command to make sure anything required by this
455 /// command is available.
457 /// @param[out] result
458 /// A command result object, if it is not okay to run the command
459 /// this will be filled in with a suitable error.
462 /// \b true if it is okay to run this command, \b false otherwise.
463 //------------------------------------------------------------------
465 CheckRequirements (CommandReturnObject &result);
470 CommandInterpreter &m_interpreter;
471 ExecutionContext m_exe_ctx;
472 Mutex::Locker m_api_locker;
473 std::string m_cmd_name;
474 std::string m_cmd_help_short;
475 std::string m_cmd_help_long;
476 std::string m_cmd_syntax;
479 std::vector<CommandArgumentEntry> m_arguments;
480 lldb::CommandOverrideCallback m_deprecated_command_override_callback;
481 lldb::CommandOverrideCallbackWithResult m_command_override_callback;
482 void * m_command_override_baton;
484 // Helper function to populate IDs or ID ranges as the command argument data
485 // to the specified command argument entry.
487 AddIDsArgumentData(CommandArgumentEntry &arg, lldb::CommandArgumentType ID, lldb::CommandArgumentType IDRange);
491 class CommandObjectParsed : public CommandObject
495 CommandObjectParsed (CommandInterpreter &interpreter,
497 const char *help = NULL,
498 const char *syntax = NULL,
499 uint32_t flags = 0) :
500 CommandObject (interpreter, name, help, syntax, flags) {}
503 ~CommandObjectParsed () {};
506 Execute (const char *args_string, CommandReturnObject &result);
510 DoExecute (Args& command,
511 CommandReturnObject &result) = 0;
514 WantsRawCommandString() { return false; };
517 class CommandObjectRaw : public CommandObject
521 CommandObjectRaw (CommandInterpreter &interpreter,
523 const char *help = NULL,
524 const char *syntax = NULL,
525 uint32_t flags = 0) :
526 CommandObject (interpreter, name, help, syntax, flags) {}
529 ~CommandObjectRaw () {};
532 Execute (const char *args_string, CommandReturnObject &result);
536 DoExecute (const char *command, CommandReturnObject &result) = 0;
539 WantsRawCommandString() { return true; };
543 } // namespace lldb_private
546 #endif // liblldb_CommandObject_h_