contrib/llvm/tools/lldb/source/Plugins/ScriptInterpreter/Python/PythonDataObjects.h

   1 //===-- PythonDataObjects.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_PLUGINS_SCRIPTINTERPRETER_PYTHON_PYTHONDATAOBJECTS_H
  11 #define LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_PYTHONDATAOBJECTS_H
  12
  13 #ifndef LLDB_DISABLE_PYTHON
  14
  15 // LLDB Python header must be included first
  16 #include "lldb-python.h"
  17
  18 #include "lldb/Utility/Flags.h"
  19
  20 #include "lldb/Host/File.h"
  21 #include "lldb/Interpreter/OptionValue.h"
  22 #include "lldb/Utility/ConstString.h"
  23 #include "lldb/Utility/StructuredData.h"
  24 #include "lldb/lldb-defines.h"
  25
  26 #include "llvm/ADT/ArrayRef.h"
  27
  28 namespace lldb_private {
  29
  30 class PythonBytes;
  31 class PythonString;
  32 class PythonList;
  33 class PythonDictionary;
  34 class PythonInteger;
  35
  36 class StructuredPythonObject : public StructuredData::Generic {
  37 public:
  38   StructuredPythonObject() : StructuredData::Generic() {}
  39
  40   StructuredPythonObject(void *obj) : StructuredData::Generic(obj) {
  41     Py_XINCREF(GetValue());
  42   }
  43
  44   ~StructuredPythonObject() override {
  45     if (Py_IsInitialized())
  46       Py_XDECREF(GetValue());
  47     SetValue(nullptr);
  48   }
  49
  50   bool IsValid() const override { return GetValue() && GetValue() != Py_None; }
  51
  52   void Dump(Stream &s, bool pretty_print = true) const override;
  53
  54 private:
  55   DISALLOW_COPY_AND_ASSIGN(StructuredPythonObject);
  56 };
  57
  58 enum class PyObjectType {
  59   Unknown,
  60   None,
  61   Integer,
  62   Dictionary,
  63   List,
  64   String,
  65   Bytes,
  66   ByteArray,
  67   Module,
  68   Callable,
  69   Tuple,
  70   File
  71 };
  72
  73 enum class PyRefType {
  74   Borrowed, // We are not given ownership of the incoming PyObject.
  75             // We cannot safely hold it without calling Py_INCREF.
  76   Owned     // We have ownership of the incoming PyObject.  We should
  77             // not call Py_INCREF.
  78 };
  79
  80 enum class PyInitialValue { Invalid, Empty };
  81
  82 class PythonObject {
  83 public:
  84   PythonObject() : m_py_obj(nullptr) {}
  85
  86   PythonObject(PyRefType type, PyObject *py_obj) : m_py_obj(nullptr) {
  87     Reset(type, py_obj);
  88   }
  89
  90   PythonObject(const PythonObject &rhs) : m_py_obj(nullptr) { Reset(rhs); }
  91
  92   virtual ~PythonObject() { Reset(); }
  93
  94   void Reset() {
  95     // Avoid calling the virtual method since it's not necessary
  96     // to actually validate the type of the PyObject if we're
  97     // just setting to null.
  98     if (Py_IsInitialized())
  99       Py_XDECREF(m_py_obj);
 100     m_py_obj = nullptr;
 101   }
 102
 103   void Reset(const PythonObject &rhs) {
 104     // Avoid calling the virtual method if it's not necessary
 105     // to actually validate the type of the PyObject.
 106     if (!rhs.IsValid())
 107       Reset();
 108     else
 109       Reset(PyRefType::Borrowed, rhs.m_py_obj);
 110   }
 111
 112   // PythonObject is implicitly convertible to PyObject *, which will call the
 113   // wrong overload.  We want to explicitly disallow this, since a PyObject
 114   // *always* owns its reference.  Therefore the overload which takes a
 115   // PyRefType doesn't make sense, and the copy constructor should be used.
 116   void Reset(PyRefType type, const PythonObject &ref) = delete;
 117
 118   virtual void Reset(PyRefType type, PyObject *py_obj) {
 119     if (py_obj == m_py_obj)
 120       return;
 121
 122     if (Py_IsInitialized())
 123       Py_XDECREF(m_py_obj);
 124
 125     m_py_obj = py_obj;
 126
 127     // If this is a borrowed reference, we need to convert it to
 128     // an owned reference by incrementing it.  If it is an owned
 129     // reference (for example the caller allocated it with PyDict_New()
 130     // then we must *not* increment it.
 131     if (Py_IsInitialized() && type == PyRefType::Borrowed)
 132       Py_XINCREF(m_py_obj);
 133   }
 134
 135   void Dump() const {
 136     if (m_py_obj)
 137       _PyObject_Dump(m_py_obj);
 138     else
 139       puts("NULL");
 140   }
 141
 142   void Dump(Stream &strm) const;
 143
 144   PyObject *get() const { return m_py_obj; }
 145
 146   PyObject *release() {
 147     PyObject *result = m_py_obj;
 148     m_py_obj = nullptr;
 149     return result;
 150   }
 151
 152   PythonObject &operator=(const PythonObject &other) {
 153     Reset(PyRefType::Borrowed, other.get());
 154     return *this;
 155   }
 156
 157   PyObjectType GetObjectType() const;
 158
 159   PythonString Repr() const;
 160
 161   PythonString Str() const;
 162
 163   static PythonObject ResolveNameWithDictionary(llvm::StringRef name,
 164                                                 const PythonDictionary &dict);
 165
 166   template <typename T>
 167   static T ResolveNameWithDictionary(llvm::StringRef name,
 168                                      const PythonDictionary &dict) {
 169     return ResolveNameWithDictionary(name, dict).AsType<T>();
 170   }
 171
 172   PythonObject ResolveName(llvm::StringRef name) const;
 173
 174   template <typename T> T ResolveName(llvm::StringRef name) const {
 175     return ResolveName(name).AsType<T>();
 176   }
 177
 178   bool HasAttribute(llvm::StringRef attribute) const;
 179
 180   PythonObject GetAttributeValue(llvm::StringRef attribute) const;
 181
 182   bool IsValid() const;
 183
 184   bool IsAllocated() const;
 185
 186   bool IsNone() const;
 187
 188   template <typename T> T AsType() const {
 189     if (!T::Check(m_py_obj))
 190       return T();
 191     return T(PyRefType::Borrowed, m_py_obj);
 192   }
 193
 194   StructuredData::ObjectSP CreateStructuredObject() const;
 195
 196 protected:
 197   PyObject *m_py_obj;
 198 };
 199
 200 class PythonBytes : public PythonObject {
 201 public:
 202   PythonBytes();
 203   explicit PythonBytes(llvm::ArrayRef<uint8_t> bytes);
 204   PythonBytes(const uint8_t *bytes, size_t length);
 205   PythonBytes(PyRefType type, PyObject *o);
 206   PythonBytes(const PythonBytes &object);
 207
 208   ~PythonBytes() override;
 209
 210   static bool Check(PyObject *py_obj);
 211
 212   // Bring in the no-argument base class version
 213   using PythonObject::Reset;
 214
 215   void Reset(PyRefType type, PyObject *py_obj) override;
 216
 217   llvm::ArrayRef<uint8_t> GetBytes() const;
 218
 219   size_t GetSize() const;
 220
 221   void SetBytes(llvm::ArrayRef<uint8_t> stringbytes);
 222
 223   StructuredData::StringSP CreateStructuredString() const;
 224 };
 225
 226 class PythonByteArray : public PythonObject {
 227 public:
 228   PythonByteArray();
 229   explicit PythonByteArray(llvm::ArrayRef<uint8_t> bytes);
 230   PythonByteArray(const uint8_t *bytes, size_t length);
 231   PythonByteArray(PyRefType type, PyObject *o);
 232   PythonByteArray(const PythonBytes &object);
 233
 234   ~PythonByteArray() override;
 235
 236   static bool Check(PyObject *py_obj);
 237
 238   // Bring in the no-argument base class version
 239   using PythonObject::Reset;
 240
 241   void Reset(PyRefType type, PyObject *py_obj) override;
 242
 243   llvm::ArrayRef<uint8_t> GetBytes() const;
 244
 245   size_t GetSize() const;
 246
 247   void SetBytes(llvm::ArrayRef<uint8_t> stringbytes);
 248
 249   StructuredData::StringSP CreateStructuredString() const;
 250 };
 251
 252 class PythonString : public PythonObject {
 253 public:
 254   PythonString();
 255   explicit PythonString(llvm::StringRef string);
 256   explicit PythonString(const char *string);
 257   PythonString(PyRefType type, PyObject *o);
 258   PythonString(const PythonString &object);
 259
 260   ~PythonString() override;
 261
 262   static bool Check(PyObject *py_obj);
 263
 264   // Bring in the no-argument base class version
 265   using PythonObject::Reset;
 266
 267   void Reset(PyRefType type, PyObject *py_obj) override;
 268
 269   llvm::StringRef GetString() const;
 270
 271   size_t GetSize() const;
 272
 273   void SetString(llvm::StringRef string);
 274
 275   StructuredData::StringSP CreateStructuredString() const;
 276 };
 277
 278 class PythonInteger : public PythonObject {
 279 public:
 280   PythonInteger();
 281   explicit PythonInteger(int64_t value);
 282   PythonInteger(PyRefType type, PyObject *o);
 283   PythonInteger(const PythonInteger &object);
 284
 285   ~PythonInteger() override;
 286
 287   static bool Check(PyObject *py_obj);
 288
 289   // Bring in the no-argument base class version
 290   using PythonObject::Reset;
 291
 292   void Reset(PyRefType type, PyObject *py_obj) override;
 293
 294   int64_t GetInteger() const;
 295
 296   void SetInteger(int64_t value);
 297
 298   StructuredData::IntegerSP CreateStructuredInteger() const;
 299 };
 300
 301 class PythonList : public PythonObject {
 302 public:
 303   PythonList() {}
 304   explicit PythonList(PyInitialValue value);
 305   explicit PythonList(int list_size);
 306   PythonList(PyRefType type, PyObject *o);
 307   PythonList(const PythonList &list);
 308
 309   ~PythonList() override;
 310
 311   static bool Check(PyObject *py_obj);
 312
 313   // Bring in the no-argument base class version
 314   using PythonObject::Reset;
 315
 316   void Reset(PyRefType type, PyObject *py_obj) override;
 317
 318   uint32_t GetSize() const;
 319
 320   PythonObject GetItemAtIndex(uint32_t index) const;
 321
 322   void SetItemAtIndex(uint32_t index, const PythonObject &object);
 323
 324   void AppendItem(const PythonObject &object);
 325
 326   StructuredData::ArraySP CreateStructuredArray() const;
 327 };
 328
 329 class PythonTuple : public PythonObject {
 330 public:
 331   PythonTuple() {}
 332   explicit PythonTuple(PyInitialValue value);
 333   explicit PythonTuple(int tuple_size);
 334   PythonTuple(PyRefType type, PyObject *o);
 335   PythonTuple(const PythonTuple &tuple);
 336   PythonTuple(std::initializer_list<PythonObject> objects);
 337   PythonTuple(std::initializer_list<PyObject *> objects);
 338
 339   ~PythonTuple() override;
 340
 341   static bool Check(PyObject *py_obj);
 342
 343   // Bring in the no-argument base class version
 344   using PythonObject::Reset;
 345
 346   void Reset(PyRefType type, PyObject *py_obj) override;
 347
 348   uint32_t GetSize() const;
 349
 350   PythonObject GetItemAtIndex(uint32_t index) const;
 351
 352   void SetItemAtIndex(uint32_t index, const PythonObject &object);
 353
 354   StructuredData::ArraySP CreateStructuredArray() const;
 355 };
 356
 357 class PythonDictionary : public PythonObject {
 358 public:
 359   PythonDictionary() {}
 360   explicit PythonDictionary(PyInitialValue value);
 361   PythonDictionary(PyRefType type, PyObject *o);
 362   PythonDictionary(const PythonDictionary &dict);
 363
 364   ~PythonDictionary() override;
 365
 366   static bool Check(PyObject *py_obj);
 367
 368   // Bring in the no-argument base class version
 369   using PythonObject::Reset;
 370
 371   void Reset(PyRefType type, PyObject *py_obj) override;
 372
 373   uint32_t GetSize() const;
 374
 375   PythonList GetKeys() const;
 376
 377   PythonObject GetItemForKey(const PythonObject &key) const;
 378   void SetItemForKey(const PythonObject &key, const PythonObject &value);
 379
 380   StructuredData::DictionarySP CreateStructuredDictionary() const;
 381 };
 382
 383 class PythonModule : public PythonObject {
 384 public:
 385   PythonModule();
 386   PythonModule(PyRefType type, PyObject *o);
 387   PythonModule(const PythonModule &dict);
 388
 389   ~PythonModule() override;
 390
 391   static bool Check(PyObject *py_obj);
 392
 393   static PythonModule BuiltinsModule();
 394
 395   static PythonModule MainModule();
 396
 397   static PythonModule AddModule(llvm::StringRef module);
 398
 399   static PythonModule ImportModule(llvm::StringRef module);
 400
 401   // Bring in the no-argument base class version
 402   using PythonObject::Reset;
 403
 404   void Reset(PyRefType type, PyObject *py_obj) override;
 405
 406   PythonDictionary GetDictionary() const;
 407 };
 408
 409 class PythonCallable : public PythonObject {
 410 public:
 411   struct ArgInfo {
 412     size_t count;
 413     bool is_bound_method : 1;
 414     bool has_varargs : 1;
 415     bool has_kwargs : 1;
 416   };
 417
 418   PythonCallable();
 419   PythonCallable(PyRefType type, PyObject *o);
 420   PythonCallable(const PythonCallable &dict);
 421
 422   ~PythonCallable() override;
 423
 424   static bool Check(PyObject *py_obj);
 425
 426   // Bring in the no-argument base class version
 427   using PythonObject::Reset;
 428
 429   void Reset(PyRefType type, PyObject *py_obj) override;
 430
 431   ArgInfo GetNumArguments() const;
 432
 433   PythonObject operator()();
 434
 435   PythonObject operator()(std::initializer_list<PyObject *> args);
 436
 437   PythonObject operator()(std::initializer_list<PythonObject> args);
 438
 439   template <typename Arg, typename... Args>
 440   PythonObject operator()(const Arg &arg, Args... args) {
 441     return operator()({arg, args...});
 442   }
 443 };
 444
 445 class PythonFile : public PythonObject {
 446 public:
 447   PythonFile();
 448   PythonFile(File &file, const char *mode);
 449   PythonFile(const char *path, const char *mode);
 450   PythonFile(PyRefType type, PyObject *o);
 451
 452   ~PythonFile() override;
 453
 454   static bool Check(PyObject *py_obj);
 455
 456   using PythonObject::Reset;
 457
 458   void Reset(PyRefType type, PyObject *py_obj) override;
 459   void Reset(File &file, const char *mode);
 460
 461   static uint32_t GetOptionsFromMode(llvm::StringRef mode);
 462
 463   bool GetUnderlyingFile(File &file) const;
 464 };
 465
 466 } // namespace lldb_private
 467
 468 #endif
 469
 470 #endif // LLDB_PLUGINS_SCRIPTINTERPRETER_PYTHON_PYTHONDATAOBJECTS_H