contrib/llvm/tools/lldb/include/lldb/API/SBCommandInterpreter.h

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