LLDB  mainline
ScriptInterpreter.h
Go to the documentation of this file.
1 //===-- ScriptInterpreter.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_INTERPRETER_SCRIPTINTERPRETER_H
10 #define LLDB_INTERPRETER_SCRIPTINTERPRETER_H
11 
15 #include "lldb/Core/SearchFilter.h"
16 #include "lldb/Core/StreamFile.h"
19 #include "lldb/Utility/Status.h"
21 #include "lldb/lldb-private.h"
22 
23 namespace lldb_private {
24 
26 public:
27  ScriptInterpreterLocker() = default;
28 
29  virtual ~ScriptInterpreterLocker() = default;
30 
31 private:
34  operator=(const ScriptInterpreterLocker &) = delete;
35 };
36 
38 public:
39  /// Create an IO redirect. If IO is enabled, this will redirects the output
40  /// to the command return object if set or to the debugger otherwise. If IO
41  /// is disabled, it will redirect all IO to /dev/null.
42  static llvm::Expected<std::unique_ptr<ScriptInterpreterIORedirect>>
43  Create(bool enable_io, Debugger &debugger, CommandReturnObject *result);
44 
46 
47  lldb::FileSP GetInputFile() const { return m_input_file_sp; }
48  lldb::FileSP GetOutputFile() const { return m_output_file_sp->GetFileSP(); }
49  lldb::FileSP GetErrorFile() const { return m_error_file_sp->GetFileSP(); }
50 
51  /// Flush our output and error file handles.
52  void Flush();
53 
54 private:
55  ScriptInterpreterIORedirect(std::unique_ptr<File> input,
56  std::unique_ptr<File> output);
58 
59  lldb::FileSP m_input_file_sp;
60  lldb::StreamFileSP m_output_file_sp;
61  lldb::StreamFileSP m_error_file_sp;
64 };
65 
67 public:
83  eScriptReturnTypeOpaqueObject
84  };
85 
86  ScriptInterpreter(Debugger &debugger, lldb::ScriptLanguage script_lang);
87 
88  ~ScriptInterpreter() override;
89 
91  public:
93  : m_enable_io(true), m_set_lldb_globals(true), m_maskout_errors(true) {}
94 
95  bool GetEnableIO() const { return m_enable_io; }
96 
97  bool GetSetLLDBGlobals() const { return m_set_lldb_globals; }
98 
99  // If this is true then any exceptions raised by the script will be
100  // cleared with PyErr_Clear(). If false then they will be left for
101  // the caller to clean up
102  bool GetMaskoutErrors() const { return m_maskout_errors; }
103 
105  m_enable_io = enable;
106  return *this;
107  }
108 
110  m_set_lldb_globals = set;
111  return *this;
112  }
113 
115  m_maskout_errors = maskout;
116  return *this;
117  }
118 
119  private:
123  };
124 
125  virtual bool Interrupt() { return false; }
126 
127  virtual bool ExecuteOneLine(
128  llvm::StringRef command, CommandReturnObject *result,
129  const ExecuteScriptOptions &options = ExecuteScriptOptions()) = 0;
130 
131  virtual void ExecuteInterpreterLoop() = 0;
132 
134  llvm::StringRef in_string, ScriptReturnType return_type, void *ret_value,
135  const ExecuteScriptOptions &options = ExecuteScriptOptions()) {
136  return true;
137  }
138 
140  const char *in_string,
141  const ExecuteScriptOptions &options = ExecuteScriptOptions()) {
142  Status error;
143  error.SetErrorString("not implemented");
144  return error;
145  }
146 
147  virtual Status
149  Status error;
150  error.SetErrorString("not implemented");
151  return error;
152  }
153 
155  StringList &input,
156  std::string &output,
157  bool has_extra_args) {
158  Status error;
159  error.SetErrorString("not implemented");
160  return error;
161  }
162 
164  std::string &output) {
165  return false;
166  }
167 
168  virtual bool GenerateTypeScriptFunction(const char *oneliner,
169  std::string &output,
170  const void *name_token = nullptr) {
171  return false;
172  }
173 
175  std::string &output,
176  const void *name_token = nullptr) {
177  return false;
178  }
179 
181  std::string &output) {
182  return false;
183  }
184 
185  virtual bool GenerateTypeSynthClass(StringList &input, std::string &output,
186  const void *name_token = nullptr) {
187  return false;
188  }
189 
190  virtual bool GenerateTypeSynthClass(const char *oneliner, std::string &output,
191  const void *name_token = nullptr) {
192  return false;
193  }
194 
196  CreateSyntheticScriptedProvider(const char *class_name,
197  lldb::ValueObjectSP valobj) {
198  return StructuredData::ObjectSP();
199  }
200 
202  CreateScriptCommandObject(const char *class_name) {
203  return StructuredData::GenericSP();
204  }
205 
207  CreateFrameRecognizer(const char *class_name) {
208  return StructuredData::GenericSP();
209  }
210 
211  virtual lldb::ValueObjectListSP GetRecognizedArguments(
212  const StructuredData::ObjectSP &implementor,
213  lldb::StackFrameSP frame_sp) {
214  return lldb::ValueObjectListSP();
215  }
216 
218  OSPlugin_CreatePluginObject(const char *class_name,
219  lldb::ProcessSP process_sp) {
220  return StructuredData::GenericSP();
221  }
222 
226  }
227 
230  return StructuredData::ArraySP();
231  }
232 
235  lldb::tid_t thread_id) {
236  return StructuredData::StringSP();
237  }
238 
241  lldb::tid_t tid, lldb::addr_t context) {
243  }
244 
246  CreateScriptedThreadPlan(const char *class_name,
247  StructuredDataImpl *args_data,
248  std::string &error_str,
249  lldb::ThreadPlanSP thread_plan_sp) {
250  return StructuredData::ObjectSP();
251  }
252 
253  virtual bool
255  Event *event, bool &script_error) {
256  script_error = true;
257  return true;
258  }
259 
260  virtual bool
262  Event *event, bool &script_error) {
263  script_error = true;
264  return true;
265  }
266 
267  virtual bool
269  bool &script_error) {
270  script_error = true;
271  return true;
272  }
273 
274  virtual lldb::StateType
276  bool &script_error) {
277  script_error = true;
278  return lldb::eStateStepping;
279  }
280 
282  CreateScriptedBreakpointResolver(const char *class_name,
283  StructuredDataImpl *args_data,
284  lldb::BreakpointSP &bkpt_sp) {
285  return StructuredData::GenericSP();
286  }
287 
288  virtual bool
290  SymbolContext *sym_ctx)
291  {
292  return false;
293  }
294 
295  virtual lldb::SearchDepth
297  {
299  }
300 
303  return StructuredData::ObjectSP();
304  }
305 
308  const char *setting_name, lldb_private::Status &error) {
310  }
311 
312  virtual Status GenerateFunction(const char *signature,
313  const StringList &input) {
314  Status error;
315  error.SetErrorString("unimplemented");
316  return error;
317  }
318 
319  virtual void CollectDataForBreakpointCommandCallback(
320  std::vector<BreakpointOptions *> &options, CommandReturnObject &result);
321 
322  virtual void
323  CollectDataForWatchpointCommandCallback(WatchpointOptions *wp_options,
324  CommandReturnObject &result);
325 
326  /// Set the specified text as the callback for the breakpoint.
327  Status
328  SetBreakpointCommandCallback(std::vector<BreakpointOptions *> &bp_options_vec,
329  const char *callback_text);
330 
332  const char *callback_text) {
333  Status error;
334  error.SetErrorString("unimplemented");
335  return error;
336  }
337 
338  /// This one is for deserialization:
340  BreakpointOptions *bp_options,
341  std::unique_ptr<BreakpointOptions::CommandData> &data_up) {
342  Status error;
343  error.SetErrorString("unimplemented");
344  return error;
345  }
346 
347  Status SetBreakpointCommandCallbackFunction(
348  std::vector<BreakpointOptions *> &bp_options_vec,
349  const char *function_name, StructuredData::ObjectSP extra_args_sp);
350 
351  /// Set a script function as the callback for the breakpoint.
352  virtual Status
354  BreakpointOptions *bp_options,
355  const char *function_name,
356  StructuredData::ObjectSP extra_args_sp) {
357  Status error;
358  error.SetErrorString("unimplemented");
359  return error;
360  }
361 
362  /// Set a one-liner as the callback for the watchpoint.
364  const char *oneliner) {}
365 
366  virtual bool GetScriptedSummary(const char *function_name,
367  lldb::ValueObjectSP valobj,
368  StructuredData::ObjectSP &callee_wrapper_sp,
369  const TypeSummaryOptions &options,
370  std::string &retval) {
371  return false;
372  }
373 
374  virtual void Clear() {
375  // Clean up any ref counts to SBObjects that might be in global variables
376  }
377 
378  virtual size_t
380  uint32_t max) {
381  return 0;
382  }
383 
384  virtual lldb::ValueObjectSP
386  return lldb::ValueObjectSP();
387  }
388 
389  virtual int
391  const char *child_name) {
392  return UINT32_MAX;
393  }
394 
395  virtual bool
397  return false;
398  }
399 
401  const StructuredData::ObjectSP &implementor) {
402  return true;
403  }
404 
405  virtual lldb::ValueObjectSP
407  return nullptr;
408  }
409 
410  virtual ConstString
412  return ConstString();
413  }
414 
415  virtual bool
416  RunScriptBasedCommand(const char *impl_function, llvm::StringRef args,
417  ScriptedCommandSynchronicity synchronicity,
419  Status &error,
420  const lldb_private::ExecutionContext &exe_ctx) {
421  return false;
422  }
423 
424  virtual bool RunScriptBasedCommand(
425  StructuredData::GenericSP impl_obj_sp, llvm::StringRef args,
426  ScriptedCommandSynchronicity synchronicity,
428  const lldb_private::ExecutionContext &exe_ctx) {
429  return false;
430  }
431 
432  virtual bool RunScriptFormatKeyword(const char *impl_function,
433  Process *process, std::string &output,
434  Status &error) {
435  error.SetErrorString("unimplemented");
436  return false;
437  }
438 
439  virtual bool RunScriptFormatKeyword(const char *impl_function, Thread *thread,
440  std::string &output, Status &error) {
441  error.SetErrorString("unimplemented");
442  return false;
443  }
444 
445  virtual bool RunScriptFormatKeyword(const char *impl_function, Target *target,
446  std::string &output, Status &error) {
447  error.SetErrorString("unimplemented");
448  return false;
449  }
450 
451  virtual bool RunScriptFormatKeyword(const char *impl_function,
452  StackFrame *frame, std::string &output,
453  Status &error) {
454  error.SetErrorString("unimplemented");
455  return false;
456  }
457 
458  virtual bool RunScriptFormatKeyword(const char *impl_function,
459  ValueObject *value, std::string &output,
460  Status &error) {
461  error.SetErrorString("unimplemented");
462  return false;
463  }
464 
465  virtual bool GetDocumentationForItem(const char *item, std::string &dest) {
466  dest.clear();
467  return false;
468  }
469 
470  virtual bool
472  std::string &dest) {
473  dest.clear();
474  return false;
475  }
476 
477  virtual uint32_t
479  return 0;
480  }
481 
483  std::string &dest) {
484  dest.clear();
485  return false;
486  }
487 
488  virtual bool CheckObjectExists(const char *name) { return false; }
489 
490  virtual bool
491  LoadScriptingModule(const char *filename, bool init_session,
493  StructuredData::ObjectSP *module_sp = nullptr);
494 
495  virtual bool IsReservedWord(const char *word) { return false; }
496 
497  virtual std::unique_ptr<ScriptInterpreterLocker> AcquireInterpreterLock();
498 
499  const char *GetScriptInterpreterPtyName();
500 
501  virtual llvm::Expected<unsigned>
502  GetMaxPositionalArgumentsForCallable(const llvm::StringRef &callable_name) {
503  return llvm::createStringError(
504  llvm::inconvertibleErrorCode(), "Unimplemented function");
505  }
506 
507  static std::string LanguageToString(lldb::ScriptLanguage language);
508 
509  static lldb::ScriptLanguage StringToLanguage(const llvm::StringRef &string);
510 
511  lldb::ScriptLanguage GetLanguage() { return m_script_lang; }
512 
513 protected:
516 };
517 
518 } // namespace lldb_private
519 
520 #endif // LLDB_INTERPRETER_SCRIPTINTERPRETER_H
virtual bool GetDocumentationForItem(const char *item, std::string &dest)
A class to manage flag bits.
Definition: Debugger.h:70
virtual lldb::StateType ScriptedThreadPlanGetRunState(StructuredData::ObjectSP implementor_sp, bool &script_error)
virtual Status GenerateFunction(const char *signature, const StringList &input)
virtual StructuredData::ObjectSP CreateScriptedThreadPlan(const char *class_name, StructuredDataImpl *args_data, std::string &error_str, lldb::ThreadPlanSP thread_plan_sp)
A class that represents a running process on the host machine.
const ScriptInterpreterLocker & operator=(const ScriptInterpreterLocker &)=delete
virtual StructuredData::ArraySP OSPlugin_ThreadsInfo(StructuredData::ObjectSP os_plugin_object_sp)
virtual uint32_t GetFlagsForCommandObject(StructuredData::GenericSP cmd_obj_sp)
virtual bool ScriptedThreadPlanExplainsStop(StructuredData::ObjectSP implementor_sp, Event *event, bool &script_error)
std::shared_ptr< Array > ArraySP
virtual bool CheckObjectExists(const char *name)
virtual bool GenerateTypeScriptFunction(const char *oneliner, std::string &output, const void *name_token=nullptr)
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
virtual bool RunScriptFormatKeyword(const char *impl_function, Thread *thread, std::string &output, Status &error)
virtual bool GetLongHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp, std::string &dest)
virtual StructuredData::DictionarySP OSPlugin_CreateThread(StructuredData::ObjectSP os_plugin_object_sp, lldb::tid_t tid, lldb::addr_t context)
virtual StructuredData::StringSP OSPlugin_RegisterContextData(StructuredData::ObjectSP os_plugin_object_sp, lldb::tid_t thread_id)
A file utility class.
Definition: FileSpec.h:56
virtual bool IsReservedWord(const char *word)
virtual bool ScriptedThreadPlanIsStale(StructuredData::ObjectSP implementor_sp, bool &script_error)
virtual bool GenerateTypeSynthClass(StringList &input, std::string &output, const void *name_token=nullptr)
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
virtual lldb::ValueObjectSP GetChildAtIndex(const StructuredData::ObjectSP &implementor, uint32_t idx)
virtual bool RunScriptFormatKeyword(const char *impl_function, StackFrame *frame, std::string &output, Status &error)
virtual StructuredData::GenericSP CreateScriptCommandObject(const char *class_name)
virtual ~ScriptInterpreterLocker()=default
virtual bool RunScriptBasedCommand(const char *impl_function, llvm::StringRef args, ScriptedCommandSynchronicity synchronicity, lldb_private::CommandReturnObject &cmd_retobj, Status &error, const lldb_private::ExecutionContext &exe_ctx)
virtual void SetWatchpointCommandCallback(WatchpointOptions *wp_options, const char *oneliner)
Set a one-liner as the callback for the watchpoint.
virtual lldb::ValueObjectListSP GetRecognizedArguments(const StructuredData::ObjectSP &implementor, lldb::StackFrameSP frame_sp)
virtual int GetIndexOfChildWithName(const StructuredData::ObjectSP &implementor, const char *child_name)
virtual bool UpdateSynthProviderInstance(const StructuredData::ObjectSP &implementor)
virtual bool GenerateTypeScriptFunction(StringList &input, std::string &output, const void *name_token=nullptr)
std::shared_ptr< Dictionary > DictionarySP
#define UINT32_MAX
Definition: lldb-defines.h:31
virtual bool ExecuteOneLineWithReturn(llvm::StringRef in_string, ScriptReturnType return_type, void *ret_value, const ExecuteScriptOptions &options=ExecuteScriptOptions())
virtual Status SetBreakpointCommandCallbackFunction(BreakpointOptions *bp_options, const char *function_name, StructuredData::ObjectSP extra_args_sp)
Set a script function as the callback for the breakpoint.
ExecuteScriptOptions & SetMaskoutErrors(bool maskout)
virtual bool ScriptedThreadPlanShouldStop(StructuredData::ObjectSP implementor_sp, Event *event, bool &script_error)
static llvm::raw_ostream & error(Stream &strm)
virtual bool RunScriptFormatKeyword(const char *impl_function, Target *target, std::string &output, Status &error)
StateType
Process and Thread States.
uint64_t tid_t
Definition: lldb-types.h:86
virtual bool GenerateTypeSynthClass(const char *oneliner, std::string &output, const void *name_token=nullptr)
lldb::ScriptLanguage m_script_lang
void SetErrorString(llvm::StringRef err_str)
Set the current error string to err_str.
Definition: Status.cpp:242
virtual bool GenerateScriptAliasFunction(StringList &input, std::string &output)
A plug-in interface definition class for debugging a process.
Definition: Process.h:362
virtual llvm::Expected< unsigned > GetMaxPositionalArgumentsForCallable(const llvm::StringRef &callable_name)
virtual bool MightHaveChildrenSynthProviderInstance(const StructuredData::ObjectSP &implementor)
virtual StructuredData::ObjectSP CreateSyntheticScriptedProvider(const char *class_name, lldb::ValueObjectSP valobj)
virtual bool GenerateWatchpointCommandCallbackData(StringList &input, std::string &output)
Process or thread is in the process of stepping and can not be examined.
virtual Status GenerateBreakpointCommandCallbackData(StringList &input, std::string &output, bool has_extra_args)
std::shared_ptr< String > StringSP
virtual StructuredData::DictionarySP GetDynamicSettings(StructuredData::ObjectSP plugin_module_sp, Target *target, const char *setting_name, lldb_private::Status &error)
virtual StructuredData::ObjectSP LoadPluginModule(const FileSpec &file_spec, lldb_private::Status &error)
virtual Status ExecuteMultipleLines(const char *in_string, const ExecuteScriptOptions &options=ExecuteScriptOptions())
lldb::ScriptLanguage GetLanguage()
virtual bool RunScriptFormatKeyword(const char *impl_function, ValueObject *value, std::string &output, Status &error)
virtual size_t CalculateNumChildren(const StructuredData::ObjectSP &implementor, uint32_t max)
An abstract communications class.
Definition: Communication.h:84
virtual bool RunScriptFormatKeyword(const char *impl_function, Process *process, std::string &output, Status &error)
"lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a watchpoint.
uint64_t addr_t
Definition: lldb-types.h:83
virtual bool GetShortHelpForCommandObject(StructuredData::GenericSP cmd_obj_sp, std::string &dest)
A uniqued constant string class.
Definition: ConstString.h:40
"lldb/Breakpoint/BreakpointOptions.h" Class that manages the options on a breakpoint or breakpoint lo...
virtual StructuredData::DictionarySP OSPlugin_RegisterInfo(StructuredData::ObjectSP os_plugin_object_sp)
std::shared_ptr< Object > ObjectSP
virtual ConstString GetSyntheticTypeName(const StructuredData::ObjectSP &implementor)
virtual lldb::SearchDepth ScriptedBreakpointResolverSearchDepth(StructuredData::GenericSP implementor_sp)
virtual bool RunScriptBasedCommand(StructuredData::GenericSP impl_obj_sp, llvm::StringRef args, ScriptedCommandSynchronicity synchronicity, lldb_private::CommandReturnObject &cmd_retobj, Status &error, const lldb_private::ExecutionContext &exe_ctx)
virtual Status SetBreakpointCommandCallback(BreakpointOptions *bp_options, std::unique_ptr< BreakpointOptions::CommandData > &data_up)
This one is for deserialization:
virtual Status ExportFunctionDefinitionToInterpreter(StringList &function_def)
virtual StructuredData::GenericSP OSPlugin_CreatePluginObject(const char *class_name, lldb::ProcessSP process_sp)
std::shared_ptr< Generic > GenericSP
virtual StructuredData::GenericSP CreateFrameRecognizer(const char *class_name)
virtual Status SetBreakpointCommandCallback(BreakpointOptions *bp_options, const char *callback_text)
virtual bool ScriptedBreakpointResolverSearchCallback(StructuredData::GenericSP implementor_sp, SymbolContext *sym_ctx)
This base class provides an interface to stack frames.
Definition: StackFrame.h:40
ScriptLanguage
Script interpreter types.
virtual lldb::ValueObjectSP GetSyntheticValue(const StructuredData::ObjectSP &implementor)
virtual StructuredData::GenericSP CreateScriptedBreakpointResolver(const char *class_name, StructuredDataImpl *args_data, lldb::BreakpointSP &bkpt_sp)
An error handling class.
Definition: Status.h:44
virtual bool GetScriptedSummary(const char *function_name, lldb::ValueObjectSP valobj, StructuredData::ObjectSP &callee_wrapper_sp, const TypeSummaryOptions &options, std::string &retval)