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 SetHelpLong (const char * str);
120 SetHelpLong (std::string str);
123 SetSyntax (const char *str);
125 // override this to return true if you want to enable the user to delete
126 // the Command object from the Command dictionary (aliases have their own
127 // deletion scheme, so they do not need to care about this)
129 IsRemovable () const { return false; }
132 IsAlias () { return m_is_alias; }
135 SetIsAlias (bool value) { m_is_alias = value; }
138 IsMultiwordObject () { return false; }
140 virtual lldb::CommandObjectSP
141 GetSubcommandSP (const char *sub_cmd, StringList *matches = NULL)
143 return lldb::CommandObjectSP();
146 virtual CommandObject *
147 GetSubcommandObject (const char *sub_cmd, StringList *matches = NULL)
153 AproposAllSubCommands (const char *prefix,
154 const char *search_word,
155 StringList &commands_found,
156 StringList &commands_help)
161 GenerateHelpText (CommandReturnObject &result);
164 GenerateHelpText (Stream &result);
166 // this is needed in order to allow the SBCommand class to
167 // transparently try and load subcommands - it will fail on
168 // anything but a multiword command, but it avoids us doing
169 // type checkings and casts
171 LoadSubCommand (const char *cmd_name,
172 const lldb::CommandObjectSP& command_obj)
178 WantsRawCommandString() = 0;
180 // By default, WantsCompletion = !WantsRawCommandString.
181 // Subclasses who want raw command string but desire, for example,
182 // argument completion should override this method to return true.
184 WantsCompletion() { return !WantsRawCommandString(); }
189 static const ArgumentTableEntry*
192 static lldb::CommandArgumentType
193 LookupArgumentName (const char *arg_name);
195 static ArgumentTableEntry *
196 FindArgumentDataByType (lldb::CommandArgumentType arg_type);
199 GetNumArgumentEntries ();
201 CommandArgumentEntry *
202 GetArgumentEntryAtIndex (int idx);
205 GetArgumentHelp (Stream &str, lldb::CommandArgumentType arg_type, CommandInterpreter &interpreter);
208 GetArgumentName (lldb::CommandArgumentType arg_type);
210 // Generates a nicely formatted command args string for help command output.
211 // By default, all possible args are taken into account, for example,
212 // '<expr | variable-name>'. This can be refined by passing a second arg
213 // specifying which option set(s) we are interested, which could then, for
214 // example, produce either '<expr>' or '<variable-name>'.
216 GetFormattedCommandArguments (Stream &str, uint32_t opt_set_mask = LLDB_OPT_SET_ALL);
219 IsPairType (ArgumentRepetitionType arg_repeat_type);
223 //----------------------------------------------------------------------
224 // eFlagRequiresTarget
226 // Ensures a valid target is contained in m_exe_ctx prior to executing
227 // the command. If a target doesn't exist or is invalid, the command
228 // will fail and CommandObject::GetInvalidTargetDescription() will be
229 // returned as the error. CommandObject subclasses can override the
230 // virtual function for GetInvalidTargetDescription() to provide custom
231 // strings when needed.
232 //----------------------------------------------------------------------
233 eFlagRequiresTarget = (1u << 0),
234 //----------------------------------------------------------------------
235 // eFlagRequiresProcess
237 // Ensures a valid process is contained in m_exe_ctx prior to executing
238 // the command. If a process doesn't exist or is invalid, the command
239 // will fail and CommandObject::GetInvalidProcessDescription() will be
240 // returned as the error. CommandObject subclasses can override the
241 // virtual function for GetInvalidProcessDescription() to provide custom
242 // strings when needed.
243 //----------------------------------------------------------------------
244 eFlagRequiresProcess = (1u << 1),
245 //----------------------------------------------------------------------
246 // eFlagRequiresThread
248 // Ensures a valid thread is contained in m_exe_ctx prior to executing
249 // the command. If a thread doesn't exist or is invalid, the command
250 // will fail and CommandObject::GetInvalidThreadDescription() will be
251 // returned as the error. CommandObject subclasses can override the
252 // virtual function for GetInvalidThreadDescription() to provide custom
253 // strings when needed.
254 //----------------------------------------------------------------------
255 eFlagRequiresThread = (1u << 2),
256 //----------------------------------------------------------------------
257 // eFlagRequiresFrame
259 // Ensures a valid frame is contained in m_exe_ctx prior to executing
260 // the command. If a frame doesn't exist or is invalid, the command
261 // will fail and CommandObject::GetInvalidFrameDescription() will be
262 // returned as the error. CommandObject subclasses can override the
263 // virtual function for GetInvalidFrameDescription() to provide custom
264 // strings when needed.
265 //----------------------------------------------------------------------
266 eFlagRequiresFrame = (1u << 3),
267 //----------------------------------------------------------------------
268 // eFlagRequiresRegContext
270 // Ensures a valid register context (from the selected frame if there
271 // is a frame in m_exe_ctx, or from the selected thread from m_exe_ctx)
272 // is available from m_exe_ctx prior to executing the command. If a
273 // target doesn't exist or is invalid, the command will fail and
274 // CommandObject::GetInvalidRegContextDescription() will be returned as
275 // the error. CommandObject subclasses can override the virtual function
276 // for GetInvalidRegContextDescription() to provide custom strings when
278 //----------------------------------------------------------------------
279 eFlagRequiresRegContext = (1u << 4),
280 //----------------------------------------------------------------------
281 // eFlagTryTargetAPILock
283 // Attempts to acquire the target lock if a target is selected in the
284 // command interpreter. If the command object fails to acquire the API
285 // lock, the command will fail with an appropriate error message.
286 //----------------------------------------------------------------------
287 eFlagTryTargetAPILock = (1u << 5),
288 //----------------------------------------------------------------------
289 // eFlagProcessMustBeLaunched
291 // Verifies that there is a launched process in m_exe_ctx, if there
292 // isn't, the command will fail with an appropriate error message.
293 //----------------------------------------------------------------------
294 eFlagProcessMustBeLaunched = (1u << 6),
295 //----------------------------------------------------------------------
296 // eFlagProcessMustBePaused
298 // Verifies that there is a paused process in m_exe_ctx, if there
299 // isn't, the command will fail with an appropriate error message.
300 //----------------------------------------------------------------------
301 eFlagProcessMustBePaused = (1u << 7)
305 ParseOptions (Args& args, CommandReturnObject &result);
308 SetCommandName (const char *name);
310 // This function really deals with CommandObjectLists, but we didn't make a
311 // CommandObjectList class, so I'm sticking it here. But we really should have
312 // such a class. Anyway, it looks up the commands in the map that match the partial
313 // string cmd_str, inserts the matches into matches, and returns the number added.
316 AddNamesMatchingPartialString (CommandMap &in_map, const char *cmd_str, StringList &matches);
318 //------------------------------------------------------------------
319 /// The input array contains a parsed version of the line. The insertion
320 /// point is given by cursor_index (the index in input of the word containing
321 /// the cursor) and cursor_char_position (the position of the cursor in that word.)
322 /// This default version handles calling option argument completions and then calls
323 /// HandleArgumentCompletion if the cursor is on an argument, not an option.
324 /// Don't override this method, override HandleArgumentCompletion instead unless
325 /// you have special reasons.
327 /// @param[in] interpreter
328 /// The command interpreter doing the completion.
331 /// The command line parsed into words
333 /// @param[in] cursor_index
334 /// The index in \ainput of the word in which the cursor lies.
336 /// @param[in] cursor_char_pos
337 /// The character position of the cursor in its argument word.
339 /// @param[in] match_start_point
340 /// @param[in] match_return_elements
341 /// FIXME: Not yet implemented... If there is a match that is expensive to compute, these are
342 /// here to allow you to compute the completions in batches. Start the completion from \amatch_start_point,
343 /// and return \amatch_return_elements elements.
345 /// @param[out] word_complete
346 /// \btrue if this is a complete option value (a space will be inserted after the
347 /// completion.) \bfalse otherwise.
349 /// @param[out] matches
350 /// The array of matches returned.
352 /// FIXME: This is the wrong return value, since we also need to make a distinction between
353 /// total number of matches, and the window the user wants returned.
356 /// \btrue if we were in an option, \bfalse otherwise.
357 //------------------------------------------------------------------
359 HandleCompletion (Args &input,
361 int &cursor_char_position,
362 int match_start_point,
363 int max_return_elements,
365 StringList &matches);
367 //------------------------------------------------------------------
368 /// The input array contains a parsed version of the line. The insertion
369 /// point is given by cursor_index (the index in input of the word containing
370 /// the cursor) and cursor_char_position (the position of the cursor in that word.)
371 /// We've constructed the map of options and their arguments as well if that is
372 /// helpful for the completion.
374 /// @param[in] interpreter
375 /// The command interpreter doing the completion.
378 /// The command line parsed into words
380 /// @param[in] cursor_index
381 /// The index in \ainput of the word in which the cursor lies.
383 /// @param[in] cursor_char_pos
384 /// The character position of the cursor in its argument word.
386 /// @param[in] opt_element_vector
387 /// The results of the options parse of \a input.
389 /// @param[in] match_start_point
390 /// @param[in] match_return_elements
391 /// See CommandObject::HandleCompletions for a description of how these work.
393 /// @param[out] word_complete
394 /// \btrue if this is a complete option value (a space will be inserted after the
395 /// completion.) \bfalse otherwise.
397 /// @param[out] matches
398 /// The array of matches returned.
400 /// FIXME: This is the wrong return value, since we also need to make a distinction between
401 /// total number of matches, and the window the user wants returned.
404 /// The number of completions.
405 //------------------------------------------------------------------
408 HandleArgumentCompletion (Args &input,
410 int &cursor_char_position,
411 OptionElementVector &opt_element_vector,
412 int match_start_point,
413 int max_return_elements,
421 HelpTextContainsWord (const char *search_word);
423 //------------------------------------------------------------------
424 /// The flags accessor.
427 /// A reference to the Flags member variable.
428 //------------------------------------------------------------------
435 //------------------------------------------------------------------
436 /// The flags const accessor.
439 /// A const reference to the Flags member variable.
440 //------------------------------------------------------------------
447 //------------------------------------------------------------------
448 /// Get the command that appropriate for a "repeat" of the current command.
450 /// @param[in] current_command_line
451 /// The complete current command line.
454 /// NULL if there is no special repeat command - it will use the current command line.
455 /// Otherwise a pointer to the command to be repeated.
456 /// If the returned string is the empty string, the command won't be repeated.
457 //------------------------------------------------------------------
458 virtual const char *GetRepeatCommand (Args ¤t_command_args, uint32_t index)
464 HasOverrideCallback () const
466 return m_command_override_callback || m_deprecated_command_override_callback;
470 SetOverrideCallback (lldb::CommandOverrideCallback callback, void *baton)
472 m_deprecated_command_override_callback = callback;
473 m_command_override_baton = baton;
477 SetOverrideCallback (lldb::CommandOverrideCallbackWithResult callback, void *baton)
479 m_command_override_callback = callback;
480 m_command_override_baton = baton;
484 InvokeOverrideCallback (const char **argv, CommandReturnObject &result)
486 if (m_command_override_callback)
487 return m_command_override_callback(m_command_override_baton, argv, result);
488 else if (m_deprecated_command_override_callback)
489 return m_deprecated_command_override_callback(m_command_override_baton, argv);
495 Execute (const char *args_string, CommandReturnObject &result) = 0;
499 GetInvalidTargetDescription()
501 return "invalid target, create a target using the 'target create' command";
505 GetInvalidProcessDescription()
507 return "invalid process";
511 GetInvalidThreadDescription()
513 return "invalid thread";
517 GetInvalidFrameDescription()
519 return "invalid frame";
523 GetInvalidRegContextDescription ()
525 return "invalid frame, no registers";
528 //------------------------------------------------------------------
529 /// Check the command to make sure anything required by this
530 /// command is available.
532 /// @param[out] result
533 /// A command result object, if it is not okay to run the command
534 /// this will be filled in with a suitable error.
537 /// \b true if it is okay to run this command, \b false otherwise.
538 //------------------------------------------------------------------
540 CheckRequirements (CommandReturnObject &result);
545 CommandInterpreter &m_interpreter;
546 ExecutionContext m_exe_ctx;
547 Mutex::Locker m_api_locker;
548 std::string m_cmd_name;
549 std::string m_cmd_help_short;
550 std::string m_cmd_help_long;
551 std::string m_cmd_syntax;
554 std::vector<CommandArgumentEntry> m_arguments;
555 lldb::CommandOverrideCallback m_deprecated_command_override_callback;
556 lldb::CommandOverrideCallbackWithResult m_command_override_callback;
557 void * m_command_override_baton;
559 // Helper function to populate IDs or ID ranges as the command argument data
560 // to the specified command argument entry.
562 AddIDsArgumentData(CommandArgumentEntry &arg, lldb::CommandArgumentType ID, lldb::CommandArgumentType IDRange);
566 class CommandObjectParsed : public CommandObject
570 CommandObjectParsed (CommandInterpreter &interpreter,
572 const char *help = NULL,
573 const char *syntax = NULL,
574 uint32_t flags = 0) :
575 CommandObject (interpreter, name, help, syntax, flags) {}
578 ~CommandObjectParsed () {};
581 Execute (const char *args_string, CommandReturnObject &result);
585 DoExecute (Args& command,
586 CommandReturnObject &result) = 0;
589 WantsRawCommandString() { return false; };
592 class CommandObjectRaw : public CommandObject
596 CommandObjectRaw (CommandInterpreter &interpreter,
598 const char *help = NULL,
599 const char *syntax = NULL,
600 uint32_t flags = 0) :
601 CommandObject (interpreter, name, help, syntax, flags) {}
604 ~CommandObjectRaw () {};
607 Execute (const char *args_string, CommandReturnObject &result);
611 DoExecute (const char *command, CommandReturnObject &result) = 0;
614 WantsRawCommandString() { return true; };
618 } // namespace lldb_private
621 #endif // liblldb_CommandObject_h_