diff options
Diffstat (limited to 'contrib/llvm-project/lldb/include/lldb/API/SBCommandInterpreter.h')
| -rw-r--r-- | contrib/llvm-project/lldb/include/lldb/API/SBCommandInterpreter.h | 483 |
1 files changed, 483 insertions, 0 deletions
diff --git a/contrib/llvm-project/lldb/include/lldb/API/SBCommandInterpreter.h b/contrib/llvm-project/lldb/include/lldb/API/SBCommandInterpreter.h new file mode 100644 index 000000000000..b7e39b785861 --- /dev/null +++ b/contrib/llvm-project/lldb/include/lldb/API/SBCommandInterpreter.h @@ -0,0 +1,483 @@ +//===-- SBCommandInterpreter.h ----------------------------------*- C++ -*-===// +// +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +// +//===----------------------------------------------------------------------===// + +#ifndef LLDB_API_SBCOMMANDINTERPRETER_H +#define LLDB_API_SBCOMMANDINTERPRETER_H + +#include <memory> + +#include "lldb/API/SBDebugger.h" +#include "lldb/API/SBDefines.h" +#include "lldb/API/SBStructuredData.h" + +namespace lldb_private { +class CommandPluginInterfaceImplementation; +} + +namespace lldb { + +class SBCommandInterpreter { +public: + enum { + eBroadcastBitThreadShouldExit = (1 << 0), + eBroadcastBitResetPrompt = (1 << 1), + eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit + eBroadcastBitAsynchronousOutputData = (1 << 3), + eBroadcastBitAsynchronousErrorData = (1 << 4) + }; + + SBCommandInterpreter(); + SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs); + + ~SBCommandInterpreter(); + + const lldb::SBCommandInterpreter & + operator=(const lldb::SBCommandInterpreter &rhs); + + static const char * + GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type); + + static const char * + GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type); + + static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event); + + explicit operator bool() const; + + bool IsValid() const; + + /// Return whether a built-in command with the passed in + /// name or command path exists. + /// + /// \param[in] cmd + /// The command or command path to search for. + /// + /// \return + /// \b true if the command exists, \b false otherwise. + bool CommandExists(const char *cmd); + + /// Return whether a user defined command with the passed in + /// name or command path exists. + /// + /// \param[in] cmd + /// The command or command path to search for. + /// + /// \return + /// \b true if the command exists, \b false otherwise. + bool UserCommandExists(const char *cmd); + + /// Return whether the passed in name or command path + /// exists and is an alias to some other command. + /// + /// \param[in] cmd + /// The command or command path to search for. + /// + /// \return + /// \b true if the command exists, \b false otherwise. + bool AliasExists(const char *cmd); + + lldb::SBBroadcaster GetBroadcaster(); + + static const char *GetBroadcasterClass(); + + bool HasCommands(); + + bool HasAliases(); + + bool HasAliasOptions(); + + bool IsInteractive(); + + lldb::SBProcess GetProcess(); + + lldb::SBDebugger GetDebugger(); + +#ifndef SWIG + lldb::SBCommand AddMultiwordCommand(const char *name, const char *help); + + /// Add a new command to the lldb::CommandInterpreter. + /// + /// The new command won't support autorepeat. If you need this functionality, + /// use the override of this function that accepts the \a auto_repeat_command + /// parameter. + /// + /// \param[in] name + /// The name of the command. + /// + /// \param[in] impl + /// The handler of this command. + /// + /// \param[in] help + /// The general description to show as part of the help message of this + /// command. + /// + /// \return + /// A lldb::SBCommand representing the newly created command. + lldb::SBCommand AddCommand(const char *name, + lldb::SBCommandPluginInterface *impl, + const char *help); + + /// Add a new command to the lldb::CommandInterpreter. + /// + /// The new command won't support autorepeat. If you need this functionality, + /// use the override of this function that accepts the \a auto_repeat_command + /// parameter. + /// + /// \param[in] name + /// The name of the command. + /// + /// \param[in] impl + /// The handler of this command. + /// + /// \param[in] help + /// The general description to show as part of the help message of this + /// command. + /// + /// \param[in] syntax + /// The syntax to show as part of the help message of this command. This + /// could include a description of the different arguments and flags this + /// command accepts. + /// + /// \return + /// A lldb::SBCommand representing the newly created command. + lldb::SBCommand AddCommand(const char *name, + lldb::SBCommandPluginInterface *impl, + const char *help, const char *syntax); + + /// Add a new command to the lldb::CommandInterpreter. + /// + /// \param[in] name + /// The name of the command. + /// + /// \param[in] impl + /// The handler of this command. + /// + /// \param[in] help + /// The general description to show as part of the help message of this + /// command. + /// + /// \param[in] syntax + /// The syntax to show as part of the help message of this command. This + /// could include a description of the different arguments and flags this + /// command accepts. + /// + /// \param[in] auto_repeat_command + /// Autorepeating is triggered when the user presses Enter successively + /// after executing a command. If \b nullptr is provided, the previous + /// exact command will be repeated. If \b "" is provided, autorepeating + /// is disabled. Otherwise, the provided string is used as a repeat + /// command. + /// + /// \return + /// A lldb::SBCommand representing the newly created command. + lldb::SBCommand AddCommand(const char *name, + lldb::SBCommandPluginInterface *impl, + const char *help, const char *syntax, + const char *auto_repeat_command); + void SourceInitFileInGlobalDirectory(lldb::SBCommandReturnObject &result); +#endif + + + void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result); + void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result, + bool is_repl); + + void + SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result); + + lldb::ReturnStatus HandleCommand(const char *command_line, + lldb::SBCommandReturnObject &result, + bool add_to_history = false); + + lldb::ReturnStatus HandleCommand(const char *command_line, + SBExecutionContext &exe_ctx, + SBCommandReturnObject &result, + bool add_to_history = false); + + void HandleCommandsFromFile(lldb::SBFileSpec &file, + lldb::SBExecutionContext &override_context, + lldb::SBCommandInterpreterRunOptions &options, + lldb::SBCommandReturnObject result); + + // The pointer based interface is not useful in SWIG, since the cursor & + // last_char arguments are string pointers INTO current_line and you can't do + // that in a scripting language interface in general... + + // In either case, the way this works is that the you give it a line and + // cursor position in the line. The function will return the number of + // completions. The matches list will contain number_of_completions + 1 + // elements. The first element is the common substring after the cursor + // position for all the matches. The rest of the elements are the matches. + // The first element is useful if you are emulating the common shell behavior + // where the tab completes to the string that is common among all the + // matches, then you should first check if the first element is non-empty, + // and if so just insert it and move the cursor to the end of the insertion. + // The next tab will return an empty common substring, and a list of choices + // (if any), at which point you should display the choices and let the user + // type further to disambiguate. + +#ifndef SWIG + int HandleCompletion(const char *current_line, const char *cursor, + const char *last_char, int match_start_point, + int max_return_elements, lldb::SBStringList &matches); +#endif + + int HandleCompletion(const char *current_line, uint32_t cursor_pos, + int match_start_point, int max_return_elements, + lldb::SBStringList &matches); + + // Same as HandleCompletion, but also fills out `descriptions` with + // descriptions for each match. +#ifndef SWIG + int HandleCompletionWithDescriptions( + const char *current_line, const char *cursor, const char *last_char, + int match_start_point, int max_return_elements, + lldb::SBStringList &matches, lldb::SBStringList &descriptions); +#endif + + int HandleCompletionWithDescriptions(const char *current_line, + uint32_t cursor_pos, + int match_start_point, + int max_return_elements, + lldb::SBStringList &matches, + lldb::SBStringList &descriptions); + + /// Returns whether an interrupt flag was raised either by the SBDebugger - + /// when the function is not running on the RunCommandInterpreter thread, or + /// by SBCommandInterpreter::InterruptCommand if it is. If your code is doing + /// interruptible work, check this API periodically, and interrupt if it + /// returns true. + bool WasInterrupted() const; + + /// Interrupts the command currently executing in the RunCommandInterpreter + /// thread. + /// + /// \return + /// \b true if there was a command in progress to recieve the interrupt. + /// \b false if there's no command currently in flight. + bool InterruptCommand(); + + // Catch commands before they execute by registering a callback that will get + // called when the command gets executed. This allows GUI or command line + // interfaces to intercept a command and stop it from happening + bool SetCommandOverrideCallback(const char *command_name, + lldb::CommandOverrideCallback callback, + void *baton); + + /// Return true if the command interpreter is the active IO handler. + /// + /// This indicates that any input coming into the debugger handles will + /// go to the command interpreter and will result in LLDB command line + /// commands being executed. + bool IsActive(); + + /// Get the string that needs to be written to the debugger stdin file + /// handle when a control character is typed. + /// + /// Some GUI programs will intercept "control + char" sequences and want + /// to have them do what normally would happen when using a real + /// terminal, so this function allows GUI programs to emulate this + /// functionality. + /// + /// \param[in] ch + /// The character that was typed along with the control key + /// + /// \return + /// The string that should be written into the file handle that is + /// feeding the input stream for the debugger, or nullptr if there is + /// no string for this control key. + const char *GetIOHandlerControlSequence(char ch); + + bool GetPromptOnQuit(); + + void SetPromptOnQuit(bool b); + + /// Sets whether the command interpreter should allow custom exit codes + /// for the 'quit' command. + void AllowExitCodeOnQuit(bool allow); + + /// Returns true if the user has called the 'quit' command with a custom exit + /// code. + bool HasCustomQuitExitCode(); + + /// Returns the exit code that the user has specified when running the + /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or + /// without a custom exit code. + int GetQuitStatus(); + + /// Resolve the command just as HandleCommand would, expanding abbreviations + /// and aliases. If successful, result->GetOutput has the full expansion. + void ResolveCommand(const char *command_line, SBCommandReturnObject &result); + + SBStructuredData GetStatistics(); + + /// Returns a list of handled commands, output and error. Each element in + /// the list is a dictionary with the following keys/values: + /// - "command" (string): The command that was given by the user. + /// - "commandName" (string): The name of the executed command. + /// - "commandArguments" (string): The arguments of the executed command. + /// - "output" (string): The output of the command. Empty ("") if no output. + /// - "error" (string): The error of the command. Empty ("") if no error. + /// - "durationInSeconds" (float): The time it took to execute the command. + /// - "timestampInEpochSeconds" (int): The timestamp when the command is + /// executed. + /// + /// Turn on settings `interpreter.save-transcript` for LLDB to populate + /// this list. Otherwise this list is empty. + SBStructuredData GetTranscript(); + +protected: + friend class lldb_private::CommandPluginInterfaceImplementation; + + /// Access using SBDebugger::GetCommandInterpreter(); + SBCommandInterpreter(lldb_private::CommandInterpreter *interpreter_ptr); + lldb_private::CommandInterpreter &ref(); + + lldb_private::CommandInterpreter *get(); + + void reset(lldb_private::CommandInterpreter *); + +private: + friend class SBDebugger; + + lldb_private::CommandInterpreter *m_opaque_ptr; +}; + +#ifndef SWIG +class SBCommandPluginInterface { +public: + virtual ~SBCommandPluginInterface() = default; + + virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/, + lldb::SBCommandReturnObject & /*result*/) { + return false; + } +}; + +class SBCommand { +public: + SBCommand(); + + explicit operator bool() const; + + bool IsValid(); + + const char *GetName(); + + const char *GetHelp(); + + const char *GetHelpLong(); + + void SetHelp(const char *); + + void SetHelpLong(const char *); + + uint32_t GetFlags(); + + void SetFlags(uint32_t flags); + + lldb::SBCommand AddMultiwordCommand(const char *name, + const char *help = nullptr); + + /// Add a new subcommand to the lldb::SBCommand. + /// + /// The new command won't support autorepeat. If you need this functionality, + /// use the override of this function that accepts the \a auto_repeat + /// parameter. + /// + /// \param[in] name + /// The name of the command. + /// + /// \param[in] impl + /// The handler of this command. + /// + /// \param[in] help + /// The general description to show as part of the help message of this + /// command. + /// + /// \return + /// A lldb::SBCommand representing the newly created command. + lldb::SBCommand AddCommand(const char *name, + lldb::SBCommandPluginInterface *impl, + const char *help = nullptr); + + /// Add a new subcommand to the lldb::SBCommand. + /// + /// The new command won't support autorepeat. If you need this functionality, + /// use the override of this function that accepts the \a auto_repeat_command + /// parameter. + /// + /// \param[in] name + /// The name of the command. + /// + /// \param[in] impl + /// The handler of this command. + /// + /// \param[in] help + /// The general description to show as part of the help message of this + /// command. + /// + /// \param[in] syntax + /// The syntax to show as part of the help message of this command. This + /// could include a description of the different arguments and flags this + /// command accepts. + /// + /// \return + /// A lldb::SBCommand representing the newly created command. + lldb::SBCommand AddCommand(const char *name, + lldb::SBCommandPluginInterface *impl, + const char *help, const char *syntax); + + /// Add a new subcommand to the lldb::SBCommand. + /// + /// The new command won't support autorepeat. If you need this functionality, + /// use the override of this function that accepts the \a auto_repeat_command + /// parameter. + /// + /// \param[in] name + /// The name of the command. + /// + /// \param[in] impl + /// The handler of this command. + /// + /// \param[in] help + /// The general description to show as part of the help message of this + /// command. + /// + /// \param[in] syntax + /// The syntax to show as part of the help message of this command. This + /// could include a description of the different arguments and flags this + /// command accepts. + /// + /// \param[in] auto_repeat_command + /// Autorepeating is triggered when the user presses Enter successively + /// after executing a command. If \b nullptr is provided, the previous + /// exact command will be repeated. If \b "" is provided, autorepeating + /// is disabled. Otherwise, the provided string is used as a repeat + /// command. + /// + /// \return + /// A lldb::SBCommand representing the newly created command. + lldb::SBCommand AddCommand(const char *name, + lldb::SBCommandPluginInterface *impl, + const char *help, const char *syntax, + const char *auto_repeat_command); + +private: + friend class SBDebugger; + friend class SBCommandInterpreter; + + SBCommand(lldb::CommandObjectSP cmd_sp); + + lldb::CommandObjectSP m_opaque_sp; +}; +#endif + +} // namespace lldb + +#endif // LLDB_API_SBCOMMANDINTERPRETER_H |