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