diff options
Diffstat (limited to 'include/lldb/Interpreter/CommandObject.h')
| -rw-r--r-- | include/lldb/Interpreter/CommandObject.h | 608 |
1 files changed, 608 insertions, 0 deletions
diff --git a/include/lldb/Interpreter/CommandObject.h b/include/lldb/Interpreter/CommandObject.h new file mode 100644 index 000000000000..2bfab0a8ecc4 --- /dev/null +++ b/include/lldb/Interpreter/CommandObject.h @@ -0,0 +1,608 @@ +//===-- CommandObject.h -----------------------------------------*- C++ -*-===// +// +// The LLVM Compiler Infrastructure +// +// This file is distributed under the University of Illinois Open Source +// License. See LICENSE.TXT for details. +// +//===----------------------------------------------------------------------===// + +#ifndef liblldb_CommandObject_h_ +#define liblldb_CommandObject_h_ + +#include <map> +#include <set> +#include <string> +#include <vector> + +#include "lldb/lldb-private.h" +#include "lldb/Interpreter/Args.h" +#include "lldb/Interpreter/CommandCompletions.h" +#include "lldb/Core/StringList.h" +#include "lldb/Core/Flags.h" +#include "lldb/Host/Mutex.h" +#include "lldb/Target/ExecutionContext.h" + +namespace lldb_private { + +class CommandObject +{ +public: + + typedef const char *(ArgumentHelpCallbackFunction) (); + + struct ArgumentHelpCallback + { + ArgumentHelpCallbackFunction *help_callback; + bool self_formatting; + + const char* + operator () () const + { + return (*help_callback)(); + } + + operator bool() const + { + return (help_callback != NULL); + } + + }; + + struct ArgumentTableEntry // Entries in the main argument information table + { + lldb::CommandArgumentType arg_type; + const char *arg_name; + CommandCompletions::CommonCompletionTypes completion_type; + ArgumentHelpCallback help_function; + const char *help_text; + }; + + struct CommandArgumentData // Used to build individual command argument lists + { + lldb::CommandArgumentType arg_type; + ArgumentRepetitionType arg_repetition; + uint32_t arg_opt_set_association; // This arg might be associated only with some particular option set(s). + CommandArgumentData(): + arg_type(lldb::eArgTypeNone), + arg_repetition(eArgRepeatPlain), + arg_opt_set_association(LLDB_OPT_SET_ALL) // By default, the arg associates to all option sets. + {} + }; + + typedef std::vector<CommandArgumentData> CommandArgumentEntry; // Used to build individual command argument lists + + static ArgumentTableEntry g_arguments_data[lldb::eArgTypeLastArg]; // Main argument information table + + typedef std::map<std::string, lldb::CommandObjectSP> CommandMap; + + CommandObject (CommandInterpreter &interpreter, + const char *name, + const char *help = NULL, + const char *syntax = NULL, + uint32_t flags = 0); + + virtual + ~CommandObject (); + + + static const char * + GetArgumentTypeAsCString (const lldb::CommandArgumentType arg_type); + + static const char * + GetArgumentDescriptionAsCString (const lldb::CommandArgumentType arg_type); + + CommandInterpreter & + GetCommandInterpreter () + { + return m_interpreter; + } + + const char * + GetHelp (); + + virtual const char * + GetHelpLong (); + + const char * + GetSyntax (); + + const char * + GetCommandName (); + + void + SetHelp (const char * str); + + void + SetHelpLong (const char * str); + + void + SetHelpLong (std::string str); + + void + SetSyntax (const char *str); + + // override this to return true if you want to enable the user to delete + // the Command object from the Command dictionary (aliases have their own + // deletion scheme, so they do not need to care about this) + virtual bool + IsRemovable () const { return false; } + + bool + IsAlias () { return m_is_alias; } + + void + SetIsAlias (bool value) { m_is_alias = value; } + + virtual bool + IsMultiwordObject () { return false; } + + virtual lldb::CommandObjectSP + GetSubcommandSP (const char *sub_cmd, StringList *matches = NULL) + { + return lldb::CommandObjectSP(); + } + + virtual CommandObject * + GetSubcommandObject (const char *sub_cmd, StringList *matches = NULL) + { + return NULL; + } + + virtual void + AproposAllSubCommands (const char *prefix, + const char *search_word, + StringList &commands_found, + StringList &commands_help) + { + } + + void + GenerateHelpText (CommandReturnObject &result); + + virtual void + GenerateHelpText (Stream &result); + + // this is needed in order to allow the SBCommand class to + // transparently try and load subcommands - it will fail on + // anything but a multiword command, but it avoids us doing + // type checkings and casts + virtual bool + LoadSubCommand (const char *cmd_name, + const lldb::CommandObjectSP& command_obj) + { + return false; + } + + virtual bool + WantsRawCommandString() = 0; + + // By default, WantsCompletion = !WantsRawCommandString. + // Subclasses who want raw command string but desire, for example, + // argument completion should override this method to return true. + virtual bool + WantsCompletion() { return !WantsRawCommandString(); } + + virtual Options * + GetOptions (); + + static const ArgumentTableEntry* + GetArgumentTable (); + + static lldb::CommandArgumentType + LookupArgumentName (const char *arg_name); + + static ArgumentTableEntry * + FindArgumentDataByType (lldb::CommandArgumentType arg_type); + + int + GetNumArgumentEntries (); + + CommandArgumentEntry * + GetArgumentEntryAtIndex (int idx); + + static void + GetArgumentHelp (Stream &str, lldb::CommandArgumentType arg_type, CommandInterpreter &interpreter); + + static const char * + GetArgumentName (lldb::CommandArgumentType arg_type); + + // Generates a nicely formatted command args string for help command output. + // By default, all possible args are taken into account, for example, + // '<expr | variable-name>'. This can be refined by passing a second arg + // specifying which option set(s) we are interested, which could then, for + // example, produce either '<expr>' or '<variable-name>'. + void + GetFormattedCommandArguments (Stream &str, uint32_t opt_set_mask = LLDB_OPT_SET_ALL); + + bool + IsPairType (ArgumentRepetitionType arg_repeat_type); + + enum + { + //---------------------------------------------------------------------- + // eFlagRequiresTarget + // + // Ensures a valid target is contained in m_exe_ctx prior to executing + // the command. If a target doesn't exist or is invalid, the command + // will fail and CommandObject::GetInvalidTargetDescription() will be + // returned as the error. CommandObject subclasses can override the + // virtual function for GetInvalidTargetDescription() to provide custom + // strings when needed. + //---------------------------------------------------------------------- + eFlagRequiresTarget = (1u << 0), + //---------------------------------------------------------------------- + // eFlagRequiresProcess + // + // Ensures a valid process is contained in m_exe_ctx prior to executing + // the command. If a process doesn't exist or is invalid, the command + // will fail and CommandObject::GetInvalidProcessDescription() will be + // returned as the error. CommandObject subclasses can override the + // virtual function for GetInvalidProcessDescription() to provide custom + // strings when needed. + //---------------------------------------------------------------------- + eFlagRequiresProcess = (1u << 1), + //---------------------------------------------------------------------- + // eFlagRequiresThread + // + // Ensures a valid thread is contained in m_exe_ctx prior to executing + // the command. If a thread doesn't exist or is invalid, the command + // will fail and CommandObject::GetInvalidThreadDescription() will be + // returned as the error. CommandObject subclasses can override the + // virtual function for GetInvalidThreadDescription() to provide custom + // strings when needed. + //---------------------------------------------------------------------- + eFlagRequiresThread = (1u << 2), + //---------------------------------------------------------------------- + // eFlagRequiresFrame + // + // Ensures a valid frame is contained in m_exe_ctx prior to executing + // the command. If a frame doesn't exist or is invalid, the command + // will fail and CommandObject::GetInvalidFrameDescription() will be + // returned as the error. CommandObject subclasses can override the + // virtual function for GetInvalidFrameDescription() to provide custom + // strings when needed. + //---------------------------------------------------------------------- + eFlagRequiresFrame = (1u << 3), + //---------------------------------------------------------------------- + // eFlagRequiresRegContext + // + // Ensures a valid register context (from the selected frame if there + // is a frame in m_exe_ctx, or from the selected thread from m_exe_ctx) + // is availble from m_exe_ctx prior to executing the command. If a + // target doesn't exist or is invalid, the command will fail and + // CommandObject::GetInvalidRegContextDescription() will be returned as + // the error. CommandObject subclasses can override the virtual function + // for GetInvalidRegContextDescription() to provide custom strings when + // needed. + //---------------------------------------------------------------------- + eFlagRequiresRegContext = (1u << 4), + //---------------------------------------------------------------------- + // eFlagTryTargetAPILock + // + // Attempts to acquire the target lock if a target is selected in the + // command interpreter. If the command object fails to acquire the API + // lock, the command will fail with an appropriate error message. + //---------------------------------------------------------------------- + eFlagTryTargetAPILock = (1u << 5), + //---------------------------------------------------------------------- + // eFlagProcessMustBeLaunched + // + // Verifies that there is a launched process in m_exe_ctx, if there + // isn't, the command will fail with an appropriate error message. + //---------------------------------------------------------------------- + eFlagProcessMustBeLaunched = (1u << 6), + //---------------------------------------------------------------------- + // eFlagProcessMustBePaused + // + // Verifies that there is a paused process in m_exe_ctx, if there + // isn't, the command will fail with an appropriate error message. + //---------------------------------------------------------------------- + eFlagProcessMustBePaused = (1u << 7) + }; + + bool + ParseOptions (Args& args, CommandReturnObject &result); + + void + SetCommandName (const char *name); + + // This function really deals with CommandObjectLists, but we didn't make a + // CommandObjectList class, so I'm sticking it here. But we really should have + // such a class. Anyway, it looks up the commands in the map that match the partial + // string cmd_str, inserts the matches into matches, and returns the number added. + + static int + AddNamesMatchingPartialString (CommandMap &in_map, const char *cmd_str, StringList &matches); + + //------------------------------------------------------------------ + /// The input array contains a parsed version of the line. The insertion + /// point is given by cursor_index (the index in input of the word containing + /// the cursor) and cursor_char_position (the position of the cursor in that word.) + /// This default version handles calling option argument completions and then calls + /// HandleArgumentCompletion if the cursor is on an argument, not an option. + /// Don't override this method, override HandleArgumentCompletion instead unless + /// you have special reasons. + /// + /// @param[in] interpreter + /// The command interpreter doing the completion. + /// + /// @param[in] input + /// The command line parsed into words + /// + /// @param[in] cursor_index + /// The index in \ainput of the word in which the cursor lies. + /// + /// @param[in] cursor_char_pos + /// The character position of the cursor in its argument word. + /// + /// @param[in] match_start_point + /// @param[in] match_return_elements + /// FIXME: Not yet implemented... If there is a match that is expensive to compute, these are + /// here to allow you to compute the completions in batches. Start the completion from \amatch_start_point, + /// and return \amatch_return_elements elements. + /// + /// @param[out] word_complete + /// \btrue if this is a complete option value (a space will be inserted after the + /// completion.) \bfalse otherwise. + /// + /// @param[out] matches + /// The array of matches returned. + /// + /// FIXME: This is the wrong return value, since we also need to make a distinction between + /// total number of matches, and the window the user wants returned. + /// + /// @return + /// \btrue if we were in an option, \bfalse otherwise. + //------------------------------------------------------------------ + virtual int + HandleCompletion (Args &input, + int &cursor_index, + int &cursor_char_position, + int match_start_point, + int max_return_elements, + bool &word_complete, + StringList &matches); + + //------------------------------------------------------------------ + /// The input array contains a parsed version of the line. The insertion + /// point is given by cursor_index (the index in input of the word containing + /// the cursor) and cursor_char_position (the position of the cursor in that word.) + /// We've constructed the map of options and their arguments as well if that is + /// helpful for the completion. + /// + /// @param[in] interpreter + /// The command interpreter doing the completion. + /// + /// @param[in] input + /// The command line parsed into words + /// + /// @param[in] cursor_index + /// The index in \ainput of the word in which the cursor lies. + /// + /// @param[in] cursor_char_pos + /// The character position of the cursor in its argument word. + /// + /// @param[in] opt_element_vector + /// The results of the options parse of \a input. + /// + /// @param[in] match_start_point + /// @param[in] match_return_elements + /// See CommandObject::HandleCompletions for a description of how these work. + /// + /// @param[out] word_complete + /// \btrue if this is a complete option value (a space will be inserted after the + /// completion.) \bfalse otherwise. + /// + /// @param[out] matches + /// The array of matches returned. + /// + /// FIXME: This is the wrong return value, since we also need to make a distinction between + /// total number of matches, and the window the user wants returned. + /// + /// @return + /// The number of completions. + //------------------------------------------------------------------ + + virtual int + HandleArgumentCompletion (Args &input, + int &cursor_index, + int &cursor_char_position, + OptionElementVector &opt_element_vector, + int match_start_point, + int max_return_elements, + bool &word_complete, + StringList &matches) + { + return 0; + } + + bool + HelpTextContainsWord (const char *search_word); + + //------------------------------------------------------------------ + /// The flags accessor. + /// + /// @return + /// A reference to the Flags member variable. + //------------------------------------------------------------------ + Flags& + GetFlags() + { + return m_flags; + } + + //------------------------------------------------------------------ + /// The flags const accessor. + /// + /// @return + /// A const reference to the Flags member variable. + //------------------------------------------------------------------ + const Flags& + GetFlags() const + { + return m_flags; + } + + //------------------------------------------------------------------ + /// Get the command that appropriate for a "repeat" of the current command. + /// + /// @param[in] current_command_line + /// The complete current command line. + /// + /// @return + /// NULL if there is no special repeat command - it will use the current command line. + /// Otherwise a pointer to the command to be repeated. + /// If the returned string is the empty string, the command won't be repeated. + //------------------------------------------------------------------ + virtual const char *GetRepeatCommand (Args ¤t_command_args, uint32_t index) + { + return NULL; + } + + CommandOverrideCallback + GetOverrideCallback () const + { + return m_command_override_callback; + } + + void * + GetOverrideCallbackBaton () const + { + return m_command_override_baton; + } + + void + SetOverrideCallback (CommandOverrideCallback callback, void *baton) + { + m_command_override_callback = callback; + m_command_override_baton = baton; + } + + virtual bool + Execute (const char *args_string, CommandReturnObject &result) = 0; + +protected: + virtual const char * + GetInvalidTargetDescription() + { + return "invalid target, create a target using the 'target create' command"; + } + + virtual const char * + GetInvalidProcessDescription() + { + return "invalid process"; + } + + virtual const char * + GetInvalidThreadDescription() + { + return "invalid thread"; + } + + virtual const char * + GetInvalidFrameDescription() + { + return "invalid frame"; + } + + virtual const char * + GetInvalidRegContextDescription () + { + return "invalid frame, no registers"; + } + + //------------------------------------------------------------------ + /// Check the command to make sure anything required by this + /// command is available. + /// + /// @param[out] result + /// A command result object, if it is not okay to run the command + /// this will be filled in with a suitable error. + /// + /// @return + /// \b true if it is okay to run this command, \b false otherwise. + //------------------------------------------------------------------ + bool + CheckRequirements (CommandReturnObject &result); + + void + Cleanup (); + + CommandInterpreter &m_interpreter; + ExecutionContext m_exe_ctx; + Mutex::Locker m_api_locker; + std::string m_cmd_name; + std::string m_cmd_help_short; + std::string m_cmd_help_long; + std::string m_cmd_syntax; + bool m_is_alias; + Flags m_flags; + std::vector<CommandArgumentEntry> m_arguments; + CommandOverrideCallback m_command_override_callback; + void * m_command_override_baton; + + // Helper function to populate IDs or ID ranges as the command argument data + // to the specified command argument entry. + static void + AddIDsArgumentData(CommandArgumentEntry &arg, lldb::CommandArgumentType ID, lldb::CommandArgumentType IDRange); + +}; + +class CommandObjectParsed : public CommandObject +{ +public: + + CommandObjectParsed (CommandInterpreter &interpreter, + const char *name, + const char *help = NULL, + const char *syntax = NULL, + uint32_t flags = 0) : + CommandObject (interpreter, name, help, syntax, flags) {} + + virtual + ~CommandObjectParsed () {}; + + virtual bool + Execute (const char *args_string, CommandReturnObject &result); + +protected: + virtual bool + DoExecute (Args& command, + CommandReturnObject &result) = 0; + + virtual bool + WantsRawCommandString() { return false; }; +}; + +class CommandObjectRaw : public CommandObject +{ +public: + + CommandObjectRaw (CommandInterpreter &interpreter, + const char *name, + const char *help = NULL, + const char *syntax = NULL, + uint32_t flags = 0) : + CommandObject (interpreter, name, help, syntax, flags) {} + + virtual + ~CommandObjectRaw () {}; + + virtual bool + Execute (const char *args_string, CommandReturnObject &result); + +protected: + virtual bool + DoExecute (const char *command, CommandReturnObject &result) = 0; + + virtual bool + WantsRawCommandString() { return true; }; +}; + + +} // namespace lldb_private + + +#endif // liblldb_CommandObject_h_ |