contrib/llvm/tools/lldb/include/lldb/Interpreter/CommandObject.h

   1 //===-- CommandObject.h -----------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_CommandObject_h_
  11 #define liblldb_CommandObject_h_
  12
  13 #include <map>
  14 #include <set>
  15 #include <string>
  16 #include <vector>
  17
  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"
  25
  26 namespace lldb_private {
  27
  28 class CommandObject
  29 {
  30 public:
  31
  32     typedef const char *(ArgumentHelpCallbackFunction) ();
  33
  34     struct ArgumentHelpCallback
  35     {
  36         ArgumentHelpCallbackFunction  *help_callback;
  37         bool                           self_formatting;
  38
  39         const char*
  40         operator () () const
  41         {
  42             return (*help_callback)();
  43         }
  44
  45         explicit operator bool() const
  46         {
  47             return (help_callback != NULL);
  48         }
  49
  50     };
  51
  52     struct ArgumentTableEntry  // Entries in the main argument information table
  53     {
  54         lldb::CommandArgumentType  arg_type;
  55         const char *arg_name;
  56         CommandCompletions::CommonCompletionTypes completion_type;
  57         ArgumentHelpCallback  help_function;
  58         const char *help_text;
  59     };
  60
  61     struct CommandArgumentData  // Used to build individual command argument lists
  62     {
  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.
  70         {}
  71     };
  72
  73     typedef std::vector<CommandArgumentData> CommandArgumentEntry; // Used to build individual command argument lists
  74
  75     static ArgumentTableEntry g_arguments_data[lldb::eArgTypeLastArg];   // Main argument information table
  76
  77     typedef std::map<std::string, lldb::CommandObjectSP> CommandMap;
  78
  79     CommandObject (CommandInterpreter &interpreter,
  80                    const char *name,
  81                    const char *help = NULL,
  82                    const char *syntax = NULL,
  83                    uint32_t flags = 0);
  84
  85     virtual
  86     ~CommandObject ();
  87
  88
  89     static const char *
  90     GetArgumentTypeAsCString (const lldb::CommandArgumentType arg_type);
  91
  92     static const char *
  93     GetArgumentDescriptionAsCString (const lldb::CommandArgumentType arg_type);
  94
  95     CommandInterpreter &
  96     GetCommandInterpreter ()
  97     {
  98         return m_interpreter;
  99     }
 100
 101     virtual const char *
 102     GetHelp ();
 103
 104     virtual const char *
 105     GetHelpLong ();
 106
 107     const char *
 108     GetSyntax ();
 109
 110     const char *
 111     GetCommandName ();
 112
 113     void
 114     SetHelp (const char * str);
 115
 116     void
 117     SetHelp (std::string str);
 118
 119     void
 120     SetHelpLong (const char * str);
 121
 122     void
 123     SetHelpLong (std::string str);
 124
 125     void
 126     SetSyntax (const char *str);
 127
 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)
 131     virtual bool
 132     IsRemovable () const { return false; }
 133
 134     bool
 135     IsAlias () { return m_is_alias; }
 136
 137     void
 138     SetIsAlias (bool value) { m_is_alias = value; }
 139
 140     virtual bool
 141     IsMultiwordObject () { return false; }
 142
 143     virtual lldb::CommandObjectSP
 144     GetSubcommandSP (const char *sub_cmd, StringList *matches = NULL)
 145     {
 146         return lldb::CommandObjectSP();
 147     }
 148
 149     virtual CommandObject *
 150     GetSubcommandObject (const char *sub_cmd, StringList *matches = NULL)
 151     {
 152         return NULL;
 153     }
 154
 155     virtual void
 156     AproposAllSubCommands (const char *prefix,
 157                            const char *search_word,
 158                            StringList &commands_found,
 159                            StringList &commands_help)
 160     {
 161     }
 162
 163     void
 164     GenerateHelpText (CommandReturnObject &result);
 165
 166     virtual void
 167     GenerateHelpText (Stream &result);
 168
 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
 173     virtual bool
 174     LoadSubCommand (const char *cmd_name,
 175                     const lldb::CommandObjectSP& command_obj)
 176     {
 177         return false;
 178     }
 179
 180     virtual bool
 181     WantsRawCommandString() = 0;
 182
 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.
 186     virtual bool
 187     WantsCompletion() { return !WantsRawCommandString(); }
 188
 189     virtual Options *
 190     GetOptions ();
 191
 192     static const ArgumentTableEntry*
 193     GetArgumentTable ();
 194
 195     static lldb::CommandArgumentType
 196     LookupArgumentName (const char *arg_name);
 197
 198     static const ArgumentTableEntry *
 199     FindArgumentDataByType (lldb::CommandArgumentType arg_type);
 200
 201     int
 202     GetNumArgumentEntries ();
 203
 204     CommandArgumentEntry *
 205     GetArgumentEntryAtIndex (int idx);
 206
 207     static void
 208     GetArgumentHelp (Stream &str, lldb::CommandArgumentType arg_type, CommandInterpreter &interpreter);
 209
 210     static const char *
 211     GetArgumentName (lldb::CommandArgumentType arg_type);
 212
 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>'.
 218     void
 219     GetFormattedCommandArguments (Stream &str, uint32_t opt_set_mask = LLDB_OPT_SET_ALL);
 220
 221     bool
 222     IsPairType (ArgumentRepetitionType arg_repeat_type);
 223
 224     bool
 225     ParseOptions (Args& args, CommandReturnObject &result);
 226
 227     void
 228     SetCommandName (const char *name);
 229
 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.
 234
 235     static int
 236     AddNamesMatchingPartialString (CommandMap &in_map, const char *cmd_str, StringList &matches);
 237
 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.
 246     ///
 247     /// @param[in] interpreter
 248     ///    The command interpreter doing the completion.
 249     ///
 250     /// @param[in] input
 251     ///    The command line parsed into words
 252     ///
 253     /// @param[in] cursor_index
 254     ///     The index in \ainput of the word in which the cursor lies.
 255     ///
 256     /// @param[in] cursor_char_pos
 257     ///     The character position of the cursor in its argument word.
 258     ///
 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.
 264     ///
 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.
 268     ///
 269     /// @param[out] matches
 270     ///     The array of matches returned.
 271     ///
 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.
 274     ///
 275     /// @return
 276     ///     \btrue if we were in an option, \bfalse otherwise.
 277     //------------------------------------------------------------------
 278     virtual int
 279     HandleCompletion (Args &input,
 280                       int &cursor_index,
 281                       int &cursor_char_position,
 282                       int match_start_point,
 283                       int max_return_elements,
 284                       bool &word_complete,
 285                       StringList &matches);
 286
 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.
 293     ///
 294     /// @param[in] interpreter
 295     ///    The command interpreter doing the completion.
 296     ///
 297     /// @param[in] input
 298     ///    The command line parsed into words
 299     ///
 300     /// @param[in] cursor_index
 301     ///     The index in \ainput of the word in which the cursor lies.
 302     ///
 303     /// @param[in] cursor_char_pos
 304     ///     The character position of the cursor in its argument word.
 305     ///
 306     /// @param[in] opt_element_vector
 307     ///     The results of the options parse of \a input.
 308     ///
 309     /// @param[in] match_start_point
 310     /// @param[in] match_return_elements
 311     ///     See CommandObject::HandleCompletions for a description of how these work.
 312     ///
 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.
 316     ///
 317     /// @param[out] matches
 318     ///     The array of matches returned.
 319     ///
 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.
 322     ///
 323     /// @return
 324     ///     The number of completions.
 325     //------------------------------------------------------------------
 326
 327     virtual int
 328     HandleArgumentCompletion (Args &input,
 329                               int &cursor_index,
 330                               int &cursor_char_position,
 331                               OptionElementVector &opt_element_vector,
 332                               int match_start_point,
 333                               int max_return_elements,
 334                               bool &word_complete,
 335                               StringList &matches)
 336     {
 337         return 0;
 338     }
 339
 340     bool
 341     HelpTextContainsWord (const char *search_word);
 342
 343     //------------------------------------------------------------------
 344     /// The flags accessor.
 345     ///
 346     /// @return
 347     ///     A reference to the Flags member variable.
 348     //------------------------------------------------------------------
 349     Flags&
 350     GetFlags()
 351     {
 352         return m_flags;
 353     }
 354
 355     //------------------------------------------------------------------
 356     /// The flags const accessor.
 357     ///
 358     /// @return
 359     ///     A const reference to the Flags member variable.
 360     //------------------------------------------------------------------
 361     const Flags&
 362     GetFlags() const
 363     {
 364         return m_flags;
 365     }
 366
 367     //------------------------------------------------------------------
 368     /// Get the command that appropriate for a "repeat" of the current command.
 369     ///
 370     /// @param[in] current_command_line
 371     ///    The complete current command line.
 372     ///
 373     /// @return
 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 &current_command_args, uint32_t index)
 379     {
 380         return NULL;
 381     }
 382
 383     bool
 384     HasOverrideCallback () const
 385     {
 386         return m_command_override_callback || m_deprecated_command_override_callback;
 387     }
 388
 389     void
 390     SetOverrideCallback (lldb::CommandOverrideCallback callback, void *baton)
 391     {
 392         m_deprecated_command_override_callback = callback;
 393         m_command_override_baton = baton;
 394     }
 395
 396     void
 397     SetOverrideCallback (lldb::CommandOverrideCallbackWithResult callback, void *baton)
 398     {
 399         m_command_override_callback = callback;
 400         m_command_override_baton = baton;
 401     }
 402
 403     bool
 404     InvokeOverrideCallback (const char **argv, CommandReturnObject &result)
 405     {
 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);
 410         else
 411             return false;
 412     }
 413
 414     virtual bool
 415     Execute (const char *args_string, CommandReturnObject &result) = 0;
 416
 417 protected:
 418     virtual const char *
 419     GetInvalidTargetDescription()
 420     {
 421         return "invalid target, create a target using the 'target create' command";
 422     }
 423
 424     virtual const char *
 425     GetInvalidProcessDescription()
 426     {
 427         return "invalid process";
 428     }
 429
 430     virtual const char *
 431     GetInvalidThreadDescription()
 432     {
 433         return "invalid thread";
 434     }
 435
 436     virtual const char *
 437     GetInvalidFrameDescription()
 438     {
 439         return "invalid frame";
 440     }
 441
 442     virtual const char *
 443     GetInvalidRegContextDescription ()
 444     {
 445         return "invalid frame, no registers";
 446     }
 447
 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();
 452
 453     //------------------------------------------------------------------
 454     /// Check the command to make sure anything required by this
 455     /// command is available.
 456     ///
 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.
 460     ///
 461     /// @return
 462     ///     \b true if it is okay to run this command, \b false otherwise.
 463     //------------------------------------------------------------------
 464     bool
 465     CheckRequirements (CommandReturnObject &result);
 466
 467     void
 468     Cleanup ();
 469
 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;
 477     bool m_is_alias;
 478     Flags m_flags;
 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;
 483
 484     // Helper function to populate IDs or ID ranges as the command argument data
 485     // to the specified command argument entry.
 486     static void
 487     AddIDsArgumentData(CommandArgumentEntry &arg, lldb::CommandArgumentType ID, lldb::CommandArgumentType IDRange);
 488
 489 };
 490
 491 class CommandObjectParsed : public CommandObject
 492 {
 493 public:
 494
 495     CommandObjectParsed (CommandInterpreter &interpreter,
 496                          const char *name,
 497                          const char *help = NULL,
 498                          const char *syntax = NULL,
 499                          uint32_t flags = 0) :
 500         CommandObject (interpreter, name, help, syntax, flags) {}
 501
 502     virtual
 503     ~CommandObjectParsed () {};
 504
 505     virtual bool
 506     Execute (const char *args_string, CommandReturnObject &result);
 507
 508 protected:
 509     virtual bool
 510     DoExecute (Args& command,
 511              CommandReturnObject &result) = 0;
 512
 513     virtual bool
 514     WantsRawCommandString() { return false; };
 515 };
 516
 517 class CommandObjectRaw : public CommandObject
 518 {
 519 public:
 520
 521     CommandObjectRaw (CommandInterpreter &interpreter,
 522                          const char *name,
 523                          const char *help = NULL,
 524                          const char *syntax = NULL,
 525                          uint32_t flags = 0) :
 526         CommandObject (interpreter, name, help, syntax, flags) {}
 527
 528     virtual
 529     ~CommandObjectRaw () {};
 530
 531     virtual bool
 532     Execute (const char *args_string, CommandReturnObject &result);
 533
 534 protected:
 535     virtual bool
 536     DoExecute (const char *command, CommandReturnObject &result) = 0;
 537
 538     virtual bool
 539     WantsRawCommandString() { return true; };
 540 };
 541
 542
 543 } // namespace lldb_private
 544
 545
 546 #endif  // liblldb_CommandObject_h_