contrib/llvm-project/lldb/include/lldb/API/SBCommandInterpreter.h

   1 //===-- SBCommandInterpreter.h ----------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef LLDB_SBCommandInterpreter_h_
  10 #define LLDB_SBCommandInterpreter_h_
  11
  12 #include <memory>
  13
  14 #include "lldb/API/SBDebugger.h"
  15 #include "lldb/API/SBDefines.h"
  16
  17 namespace lldb {
  18
  19 class LLDB_API SBCommandInterpreterRunOptions {
  20   friend class SBDebugger;
  21   friend class SBCommandInterpreter;
  22
  23 public:
  24   SBCommandInterpreterRunOptions();
  25   ~SBCommandInterpreterRunOptions();
  26
  27   bool GetStopOnContinue() const;
  28
  29   void SetStopOnContinue(bool);
  30
  31   bool GetStopOnError() const;
  32
  33   void SetStopOnError(bool);
  34
  35   bool GetStopOnCrash() const;
  36
  37   void SetStopOnCrash(bool);
  38
  39   bool GetEchoCommands() const;
  40
  41   void SetEchoCommands(bool);
  42
  43   bool GetEchoCommentCommands() const;
  44
  45   void SetEchoCommentCommands(bool echo);
  46
  47   bool GetPrintResults() const;
  48
  49   void SetPrintResults(bool);
  50
  51   bool GetAddToHistory() const;
  52
  53   void SetAddToHistory(bool);
  54
  55 private:
  56   lldb_private::CommandInterpreterRunOptions *get() const;
  57
  58   lldb_private::CommandInterpreterRunOptions &ref() const;
  59
  60   // This is set in the constructor and will always be valid.
  61   mutable std::unique_ptr<lldb_private::CommandInterpreterRunOptions>
  62       m_opaque_up;
  63 };
  64
  65 class SBCommandInterpreter {
  66 public:
  67   enum {
  68     eBroadcastBitThreadShouldExit = (1 << 0),
  69     eBroadcastBitResetPrompt = (1 << 1),
  70     eBroadcastBitQuitCommandReceived = (1 << 2), // User entered quit
  71     eBroadcastBitAsynchronousOutputData = (1 << 3),
  72     eBroadcastBitAsynchronousErrorData = (1 << 4)
  73   };
  74
  75   SBCommandInterpreter(const lldb::SBCommandInterpreter &rhs);
  76
  77   ~SBCommandInterpreter();
  78
  79   const lldb::SBCommandInterpreter &
  80   operator=(const lldb::SBCommandInterpreter &rhs);
  81
  82   static const char *
  83   GetArgumentTypeAsCString(const lldb::CommandArgumentType arg_type);
  84
  85   static const char *
  86   GetArgumentDescriptionAsCString(const lldb::CommandArgumentType arg_type);
  87
  88   static bool EventIsCommandInterpreterEvent(const lldb::SBEvent &event);
  89
  90   explicit operator bool() const;
  91
  92   bool IsValid() const;
  93
  94   bool CommandExists(const char *cmd);
  95
  96   bool AliasExists(const char *cmd);
  97
  98   lldb::SBBroadcaster GetBroadcaster();
  99
 100   static const char *GetBroadcasterClass();
 101
 102   bool HasCommands();
 103
 104   bool HasAliases();
 105
 106   bool HasAliasOptions();
 107
 108   lldb::SBProcess GetProcess();
 109
 110   lldb::SBDebugger GetDebugger();
 111
 112   lldb::SBCommand AddMultiwordCommand(const char *name, const char *help);
 113
 114   lldb::SBCommand AddCommand(const char *name,
 115                              lldb::SBCommandPluginInterface *impl,
 116                              const char *help);
 117
 118   lldb::SBCommand AddCommand(const char *name,
 119                              lldb::SBCommandPluginInterface *impl,
 120                              const char *help, const char *syntax);
 121
 122   void SourceInitFileInHomeDirectory(lldb::SBCommandReturnObject &result);
 123
 124   void
 125   SourceInitFileInCurrentWorkingDirectory(lldb::SBCommandReturnObject &result);
 126
 127   lldb::ReturnStatus HandleCommand(const char *command_line,
 128                                    lldb::SBCommandReturnObject &result,
 129                                    bool add_to_history = false);
 130
 131   lldb::ReturnStatus HandleCommand(const char *command_line,
 132                                    SBExecutionContext &exe_ctx,
 133                                    SBCommandReturnObject &result,
 134                                    bool add_to_history = false);
 135
 136   void HandleCommandsFromFile(lldb::SBFileSpec &file,
 137                               lldb::SBExecutionContext &override_context,
 138                               lldb::SBCommandInterpreterRunOptions &options,
 139                               lldb::SBCommandReturnObject result);
 140
 141   // The pointer based interface is not useful in SWIG, since the cursor &
 142   // last_char arguments are string pointers INTO current_line and you can't do
 143   // that in a scripting language interface in general...
 144
 145   // In either case, the way this works is that the you give it a line and
 146   // cursor position in the line.  The function will return the number of
 147   // completions.  The matches list will contain number_of_completions + 1
 148   // elements.  The first element is the common substring after the cursor
 149   // position for all the matches.  The rest of the elements are the matches.
 150   // The first element is useful if you are emulating the common shell behavior
 151   // where the tab completes to the string that is common among all the
 152   // matches, then you should first check if the first element is non-empty,
 153   // and if so just insert it and move the cursor to the end of the insertion.
 154   // The next tab will return an empty common substring, and a list of choices
 155   // (if any), at which point you should display the choices and let the user
 156   // type further to disambiguate.
 157
 158   int HandleCompletion(const char *current_line, const char *cursor,
 159                        const char *last_char, int match_start_point,
 160                        int max_return_elements, lldb::SBStringList &matches);
 161
 162   int HandleCompletion(const char *current_line, uint32_t cursor_pos,
 163                        int match_start_point, int max_return_elements,
 164                        lldb::SBStringList &matches);
 165
 166   // Same as HandleCompletion, but also fills out `descriptions` with
 167   // descriptions for each match.
 168   int HandleCompletionWithDescriptions(
 169       const char *current_line, const char *cursor, const char *last_char,
 170       int match_start_point, int max_return_elements,
 171       lldb::SBStringList &matches, lldb::SBStringList &descriptions);
 172
 173   int HandleCompletionWithDescriptions(const char *current_line,
 174                                        uint32_t cursor_pos,
 175                                        int match_start_point,
 176                                        int max_return_elements,
 177                                        lldb::SBStringList &matches,
 178                                        lldb::SBStringList &descriptions);
 179
 180   bool WasInterrupted() const;
 181
 182   // Catch commands before they execute by registering a callback that will get
 183   // called when the command gets executed. This allows GUI or command line
 184   // interfaces to intercept a command and stop it from happening
 185   bool SetCommandOverrideCallback(const char *command_name,
 186                                   lldb::CommandOverrideCallback callback,
 187                                   void *baton);
 188
 189   SBCommandInterpreter(
 190       lldb_private::CommandInterpreter *interpreter_ptr =
 191           nullptr); // Access using SBDebugger::GetCommandInterpreter();
 192
 193   /// Return true if the command interpreter is the active IO handler.
 194   ///
 195   /// This indicates that any input coming into the debugger handles will
 196   /// go to the command interpreter and will result in LLDB command line
 197   /// commands being executed.
 198   bool IsActive();
 199
 200   /// Get the string that needs to be written to the debugger stdin file
 201   /// handle when a control character is typed.
 202   ///
 203   /// Some GUI programs will intercept "control + char" sequences and want
 204   /// to have them do what normally would happen when using a real
 205   /// terminal, so this function allows GUI programs to emulate this
 206   /// functionality.
 207   ///
 208   /// \param[in] ch
 209   ///     The character that was typed along with the control key
 210   ///
 211   /// \return
 212   ///     The string that should be written into the file handle that is
 213   ///     feeding the input stream for the debugger, or nullptr if there is
 214   ///     no string for this control key.
 215   const char *GetIOHandlerControlSequence(char ch);
 216
 217   bool GetPromptOnQuit();
 218
 219   void SetPromptOnQuit(bool b);
 220
 221   /// Sets whether the command interpreter should allow custom exit codes
 222   /// for the 'quit' command.
 223   void AllowExitCodeOnQuit(bool allow);
 224
 225   /// Returns true if the user has called the 'quit' command with a custom exit
 226   /// code.
 227   bool HasCustomQuitExitCode();
 228
 229   /// Returns the exit code that the user has specified when running the
 230   /// 'quit' command. Returns 0 if the user hasn't called 'quit' at all or
 231   /// without a custom exit code.
 232   int GetQuitStatus();
 233
 234   /// Resolve the command just as HandleCommand would, expanding abbreviations
 235   /// and aliases.  If successful, result->GetOutput has the full expansion.
 236   void ResolveCommand(const char *command_line, SBCommandReturnObject &result);
 237
 238 protected:
 239   lldb_private::CommandInterpreter &ref();
 240
 241   lldb_private::CommandInterpreter *get();
 242
 243   void reset(lldb_private::CommandInterpreter *);
 244
 245 private:
 246   friend class SBDebugger;
 247
 248   lldb_private::CommandInterpreter *m_opaque_ptr;
 249 };
 250
 251 class SBCommandPluginInterface {
 252 public:
 253   virtual ~SBCommandPluginInterface() = default;
 254
 255   virtual bool DoExecute(lldb::SBDebugger /*debugger*/, char ** /*command*/,
 256                          lldb::SBCommandReturnObject & /*result*/) {
 257     return false;
 258   }
 259 };
 260
 261 class SBCommand {
 262 public:
 263   SBCommand();
 264
 265   explicit operator bool() const;
 266
 267   bool IsValid();
 268
 269   const char *GetName();
 270
 271   const char *GetHelp();
 272
 273   const char *GetHelpLong();
 274
 275   void SetHelp(const char *);
 276
 277   void SetHelpLong(const char *);
 278
 279   uint32_t GetFlags();
 280
 281   void SetFlags(uint32_t flags);
 282
 283   lldb::SBCommand AddMultiwordCommand(const char *name,
 284                                       const char *help = nullptr);
 285
 286   lldb::SBCommand AddCommand(const char *name,
 287                              lldb::SBCommandPluginInterface *impl,
 288                              const char *help = nullptr);
 289
 290   lldb::SBCommand AddCommand(const char *name,
 291                              lldb::SBCommandPluginInterface *impl,
 292                              const char *help, const char *syntax);
 293
 294 private:
 295   friend class SBDebugger;
 296   friend class SBCommandInterpreter;
 297
 298   SBCommand(lldb::CommandObjectSP cmd_sp);
 299
 300   lldb::CommandObjectSP m_opaque_sp;
 301 };
 302
 303 } // namespace lldb
 304
 305 #endif // LLDB_SBCommandInterpreter_h_