contrib/llvm/tools/lldb/include/lldb/Utility/Stream.h

   1 //===-- Stream.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 liblldb_Stream_h_
  11 #define liblldb_Stream_h_
  12
  13 #include "lldb/Utility/Flags.h"
  14 #include "lldb/lldb-defines.h"
  15 #include "lldb/lldb-enumerations.h" // for ByteOrder::eByteOrderInvalid
  16 #include "llvm/ADT/StringRef.h"     // for StringRef
  17 #include "llvm/Support/FormatVariadic.h"
  18
  19 #include <stdarg.h>
  20 #include <stddef.h>    // for size_t
  21 #include <stdint.h>    // for uint32_t, uint64_t, uint8_t
  22 #include <type_traits> // for forward
  23
  24 namespace lldb_private {
  25
  26 //----------------------------------------------------------------------
  27 /// @class Stream Stream.h "lldb/Utility/Stream.h"
  28 /// A stream class that can stream formatted output to a file.
  29 //----------------------------------------------------------------------
  30 class Stream {
  31 public:
  32   //------------------------------------------------------------------
  33   /// \a m_flags bit values.
  34   //------------------------------------------------------------------
  35   enum {
  36     eBinary = (1 << 0) ///< Get and put data as binary instead of as the default
  37                        /// string mode.
  38   };
  39
  40   //------------------------------------------------------------------
  41   /// Construct with flags and address size and byte order.
  42   ///
  43   /// Construct with dump flags \a flags and the default address size. \a
  44   /// flags can be any of the above enumeration logical OR'ed together.
  45   //------------------------------------------------------------------
  46   Stream(uint32_t flags, uint32_t addr_size, lldb::ByteOrder byte_order);
  47
  48   //------------------------------------------------------------------
  49   /// Construct a default Stream, not binary, host byte order and host addr
  50   /// size.
  51   ///
  52   //------------------------------------------------------------------
  53   Stream();
  54
  55   //------------------------------------------------------------------
  56   /// Destructor
  57   //------------------------------------------------------------------
  58   virtual ~Stream();
  59
  60   //------------------------------------------------------------------
  61   // Subclasses must override these methods
  62   //------------------------------------------------------------------
  63
  64   //------------------------------------------------------------------
  65   /// Flush the stream.
  66   ///
  67   /// Subclasses should flush the stream to make any output appear if the
  68   /// stream has any buffering.
  69   //------------------------------------------------------------------
  70   virtual void Flush() = 0;
  71
  72   //------------------------------------------------------------------
  73   /// Output character bytes to the stream.
  74   ///
  75   /// Appends \a src_len characters from the buffer \a src to the stream.
  76   ///
  77   /// @param[in] src
  78   ///     A buffer containing at least \a src_len bytes of data.
  79   ///
  80   /// @param[in] src_len
  81   ///     A number of bytes to append to the stream.
  82   ///
  83   /// @return
  84   ///     The number of bytes that were appended to the stream.
  85   //------------------------------------------------------------------
  86   virtual size_t Write(const void *src, size_t src_len) = 0;
  87
  88   //------------------------------------------------------------------
  89   // Member functions
  90   //------------------------------------------------------------------
  91   size_t PutChar(char ch);
  92
  93   //------------------------------------------------------------------
  94   /// Set the byte_order value.
  95   ///
  96   /// Sets the byte order of the data to extract. Extracted values will be
  97   /// swapped if necessary when decoding.
  98   ///
  99   /// @param[in] byte_order
 100   ///     The byte order value to use when extracting data.
 101   ///
 102   /// @return
 103   ///     The old byte order value.
 104   //------------------------------------------------------------------
 105   lldb::ByteOrder SetByteOrder(lldb::ByteOrder byte_order);
 106
 107   //------------------------------------------------------------------
 108   /// Format a C string from a printf style format and variable arguments and
 109   /// encode and append the resulting C string as hex bytes.
 110   ///
 111   /// @param[in] format
 112   ///     A printf style format string.
 113   ///
 114   /// @param[in] ...
 115   ///     Any additional arguments needed for the printf format string.
 116   ///
 117   /// @return
 118   ///     The number of bytes that were appended to the stream.
 119   //------------------------------------------------------------------
 120   size_t PrintfAsRawHex8(const char *format, ...)
 121       __attribute__((__format__(__printf__, 2, 3)));
 122
 123   //------------------------------------------------------------------
 124   /// Format a C string from a printf style format and variable arguments and
 125   /// encode and append the resulting C string as hex bytes.
 126   ///
 127   /// @param[in] format
 128   ///     A printf style format string.
 129   ///
 130   /// @param[in] ...
 131   ///     Any additional arguments needed for the printf format string.
 132   ///
 133   /// @return
 134   ///     The number of bytes that were appended to the stream.
 135   //------------------------------------------------------------------
 136   size_t PutHex8(uint8_t uvalue);
 137
 138   size_t PutNHex8(size_t n, uint8_t uvalue);
 139
 140   size_t PutHex16(uint16_t uvalue,
 141                   lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
 142
 143   size_t PutHex32(uint32_t uvalue,
 144                   lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
 145
 146   size_t PutHex64(uint64_t uvalue,
 147                   lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
 148
 149   size_t PutMaxHex64(uint64_t uvalue, size_t byte_size,
 150                      lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
 151   size_t PutFloat(float f,
 152                   lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
 153
 154   size_t PutDouble(double d,
 155                    lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
 156
 157   size_t PutLongDouble(long double ld,
 158                        lldb::ByteOrder byte_order = lldb::eByteOrderInvalid);
 159
 160   size_t PutPointer(void *ptr);
 161
 162   // Append \a src_len bytes from \a src to the stream as hex characters (two
 163   // ascii characters per byte of input data)
 164   size_t
 165   PutBytesAsRawHex8(const void *src, size_t src_len,
 166                     lldb::ByteOrder src_byte_order = lldb::eByteOrderInvalid,
 167                     lldb::ByteOrder dst_byte_order = lldb::eByteOrderInvalid);
 168
 169   // Append \a src_len bytes from \a s to the stream as binary data.
 170   size_t PutRawBytes(const void *s, size_t src_len,
 171                      lldb::ByteOrder src_byte_order = lldb::eByteOrderInvalid,
 172                      lldb::ByteOrder dst_byte_order = lldb::eByteOrderInvalid);
 173
 174   size_t PutCStringAsRawHex8(const char *s);
 175
 176   //------------------------------------------------------------------
 177   /// Output a NULL terminated C string \a cstr to the stream \a s.
 178   ///
 179   /// @param[in] cstr
 180   ///     A NULL terminated C string.
 181   ///
 182   /// @return
 183   ///     A reference to this class so multiple things can be streamed
 184   ///     in one statement.
 185   //------------------------------------------------------------------
 186   Stream &operator<<(const char *cstr);
 187
 188   Stream &operator<<(llvm::StringRef str);
 189
 190   //------------------------------------------------------------------
 191   /// Output a pointer value \a p to the stream \a s.
 192   ///
 193   /// @param[in] p
 194   ///     A void pointer.
 195   ///
 196   /// @return
 197   ///     A reference to this class so multiple things can be streamed
 198   ///     in one statement.
 199   //------------------------------------------------------------------
 200   Stream &operator<<(const void *p);
 201
 202   //------------------------------------------------------------------
 203   /// Output a character \a ch to the stream \a s.
 204   ///
 205   /// @param[in] ch
 206   ///     A printable character value.
 207   ///
 208   /// @return
 209   ///     A reference to this class so multiple things can be streamed
 210   ///     in one statement.
 211   //------------------------------------------------------------------
 212   Stream &operator<<(char ch);
 213
 214   //------------------------------------------------------------------
 215   /// Output a uint8_t \a uval to the stream \a s.
 216   ///
 217   /// @param[in] uval
 218   ///     A uint8_t value.
 219   ///
 220   /// @return
 221   ///     A reference to this class so multiple things can be streamed
 222   ///     in one statement.
 223   //------------------------------------------------------------------
 224   Stream &operator<<(uint8_t uval);
 225
 226   //------------------------------------------------------------------
 227   /// Output a uint16_t \a uval to the stream \a s.
 228   ///
 229   /// @param[in] uval
 230   ///     A uint16_t value.
 231   ///
 232   /// @return
 233   ///     A reference to this class so multiple things can be streamed
 234   ///     in one statement.
 235   //------------------------------------------------------------------
 236   Stream &operator<<(uint16_t uval);
 237
 238   //------------------------------------------------------------------
 239   /// Output a uint32_t \a uval to the stream \a s.
 240   ///
 241   /// @param[in] uval
 242   ///     A uint32_t value.
 243   ///
 244   /// @return
 245   ///     A reference to this class so multiple things can be streamed
 246   ///     in one statement.
 247   //------------------------------------------------------------------
 248   Stream &operator<<(uint32_t uval);
 249
 250   //------------------------------------------------------------------
 251   /// Output a uint64_t \a uval to the stream \a s.
 252   ///
 253   /// @param[in] uval
 254   ///     A uint64_t value.
 255   ///
 256   /// @return
 257   ///     A reference to this class so multiple things can be streamed
 258   ///     in one statement.
 259   //------------------------------------------------------------------
 260   Stream &operator<<(uint64_t uval);
 261
 262   //------------------------------------------------------------------
 263   /// Output a int8_t \a sval to the stream \a s.
 264   ///
 265   /// @param[in] sval
 266   ///     A int8_t value.
 267   ///
 268   /// @return
 269   ///     A reference to this class so multiple things can be streamed
 270   ///     in one statement.
 271   //------------------------------------------------------------------
 272   Stream &operator<<(int8_t sval);
 273
 274   //------------------------------------------------------------------
 275   /// Output a int16_t \a sval to the stream \a s.
 276   ///
 277   /// @param[in] sval
 278   ///     A int16_t value.
 279   ///
 280   /// @return
 281   ///     A reference to this class so multiple things can be streamed
 282   ///     in one statement.
 283   //------------------------------------------------------------------
 284   Stream &operator<<(int16_t sval);
 285
 286   //------------------------------------------------------------------
 287   /// Output a int32_t \a sval to the stream \a s.
 288   ///
 289   /// @param[in] sval
 290   ///     A int32_t value.
 291   ///
 292   /// @return
 293   ///     A reference to this class so multiple things can be streamed
 294   ///     in one statement.
 295   //------------------------------------------------------------------
 296   Stream &operator<<(int32_t sval);
 297
 298   //------------------------------------------------------------------
 299   /// Output a int64_t \a sval to the stream \a s.
 300   ///
 301   /// @param[in] sval
 302   ///     A int64_t value.
 303   ///
 304   /// @return
 305   ///     A reference to this class so multiple things can be streamed
 306   ///     in one statement.
 307   //------------------------------------------------------------------
 308   Stream &operator<<(int64_t sval);
 309
 310   //------------------------------------------------------------------
 311   /// Output an address value to this stream.
 312   ///
 313   /// Put an address \a addr out to the stream with optional \a prefix and \a
 314   /// suffix strings.
 315   ///
 316   /// @param[in] addr
 317   ///     An address value.
 318   ///
 319   /// @param[in] addr_size
 320   ///     Size in bytes of the address, used for formatting.
 321   ///
 322   /// @param[in] prefix
 323   ///     A prefix C string. If nullptr, no prefix will be output.
 324   ///
 325   /// @param[in] suffix
 326   ///     A suffix C string. If nullptr, no suffix will be output.
 327   //------------------------------------------------------------------
 328   void Address(uint64_t addr, uint32_t addr_size, const char *prefix = nullptr,
 329                const char *suffix = nullptr);
 330
 331   //------------------------------------------------------------------
 332   /// Output an address range to this stream.
 333   ///
 334   /// Put an address range \a lo_addr - \a hi_addr out to the stream with
 335   /// optional \a prefix and \a suffix strings.
 336   ///
 337   /// @param[in] lo_addr
 338   ///     The start address of the address range.
 339   ///
 340   /// @param[in] hi_addr
 341   ///     The end address of the address range.
 342   ///
 343   /// @param[in] addr_size
 344   ///     Size in bytes of the address, used for formatting.
 345   ///
 346   /// @param[in] prefix
 347   ///     A prefix C string. If nullptr, no prefix will be output.
 348   ///
 349   /// @param[in] suffix
 350   ///     A suffix C string. If nullptr, no suffix will be output.
 351   //------------------------------------------------------------------
 352   void AddressRange(uint64_t lo_addr, uint64_t hi_addr, uint32_t addr_size,
 353                     const char *prefix = nullptr, const char *suffix = nullptr);
 354
 355   //------------------------------------------------------------------
 356   /// Output a C string to the stream.
 357   ///
 358   /// Print a C string \a cstr to the stream.
 359   ///
 360   /// @param[in] cstr
 361   ///     The string to be output to the stream.
 362   //------------------------------------------------------------------
 363   size_t PutCString(llvm::StringRef cstr);
 364
 365   //------------------------------------------------------------------
 366   /// Output and End of Line character to the stream.
 367   //------------------------------------------------------------------
 368   size_t EOL();
 369
 370   //------------------------------------------------------------------
 371   /// Get the address size in bytes.
 372   ///
 373   /// @return
 374   ///     The size of an address in bytes that is used when outputting
 375   ///     address and pointer values to the stream.
 376   //------------------------------------------------------------------
 377   uint32_t GetAddressByteSize() const;
 378
 379   //------------------------------------------------------------------
 380   /// The flags accessor.
 381   ///
 382   /// @return
 383   ///     A reference to the Flags member variable.
 384   //------------------------------------------------------------------
 385   Flags &GetFlags();
 386
 387   //------------------------------------------------------------------
 388   /// The flags const accessor.
 389   ///
 390   /// @return
 391   ///     A const reference to the Flags member variable.
 392   //------------------------------------------------------------------
 393   const Flags &GetFlags() const;
 394
 395   //------------------------------------------------------------------
 396   //// The byte order accessor.
 397   ////
 398   //// @return
 399   ////     The byte order.
 400   //------------------------------------------------------------------
 401   lldb::ByteOrder GetByteOrder() const;
 402
 403   //------------------------------------------------------------------
 404   /// Get the current indentation level.
 405   ///
 406   /// @return
 407   ///     The current indentation level as an integer.
 408   //------------------------------------------------------------------
 409   int GetIndentLevel() const;
 410
 411   //------------------------------------------------------------------
 412   /// Indent the current line in the stream.
 413   ///
 414   /// Indent the current line using the current indentation level and print an
 415   /// optional string following the indentation spaces.
 416   ///
 417   /// @param[in] s
 418   ///     A C string to print following the indentation. If nullptr, just
 419   ///     output the indentation characters.
 420   //------------------------------------------------------------------
 421   size_t Indent(const char *s = nullptr);
 422   size_t Indent(llvm::StringRef s);
 423
 424   //------------------------------------------------------------------
 425   /// Decrement the current indentation level.
 426   //------------------------------------------------------------------
 427   void IndentLess(int amount = 2);
 428
 429   //------------------------------------------------------------------
 430   /// Increment the current indentation level.
 431   //------------------------------------------------------------------
 432   void IndentMore(int amount = 2);
 433
 434   //------------------------------------------------------------------
 435   /// Output an offset value.
 436   ///
 437   /// Put an offset \a uval out to the stream using the printf format in \a
 438   /// format.
 439   ///
 440   /// @param[in] offset
 441   ///     The offset value.
 442   ///
 443   /// @param[in] format
 444   ///     The printf style format to use when outputting the offset.
 445   //------------------------------------------------------------------
 446   void Offset(uint32_t offset, const char *format = "0x%8.8x: ");
 447
 448   //------------------------------------------------------------------
 449   /// Output printf formatted output to the stream.
 450   ///
 451   /// Print some formatted output to the stream.
 452   ///
 453   /// @param[in] format
 454   ///     A printf style format string.
 455   ///
 456   /// @param[in] ...
 457   ///     Variable arguments that are needed for the printf style
 458   ///     format string \a format.
 459   //------------------------------------------------------------------
 460   size_t Printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
 461
 462   size_t PrintfVarArg(const char *format, va_list args);
 463
 464   template <typename... Args> void Format(const char *format, Args &&... args) {
 465     PutCString(llvm::formatv(format, std::forward<Args>(args)...).str());
 466   }
 467
 468   //------------------------------------------------------------------
 469   /// Output a quoted C string value to the stream.
 470   ///
 471   /// Print a double quoted NULL terminated C string to the stream using the
 472   /// printf format in \a format.
 473   ///
 474   /// @param[in] cstr
 475   ///     A NULL terminated C string value.
 476   ///
 477   /// @param[in] format
 478   ///     The optional C string format that can be overridden.
 479   //------------------------------------------------------------------
 480   void QuotedCString(const char *cstr, const char *format = "\"%s\"");
 481
 482   //------------------------------------------------------------------
 483   /// Set the address size in bytes.
 484   ///
 485   /// @param[in] addr_size
 486   ///     The new size in bytes of an address to use when outputting
 487   ///     address and pointer values.
 488   //------------------------------------------------------------------
 489   void SetAddressByteSize(uint32_t addr_size);
 490
 491   //------------------------------------------------------------------
 492   /// Set the current indentation level.
 493   ///
 494   /// @param[in] level
 495   ///     The new indentation level.
 496   //------------------------------------------------------------------
 497   void SetIndentLevel(int level);
 498
 499   //------------------------------------------------------------------
 500   /// Output a SLEB128 number to the stream.
 501   ///
 502   /// Put an SLEB128 \a uval out to the stream using the printf format in \a
 503   /// format.
 504   ///
 505   /// @param[in] uval
 506   ///     A uint64_t value that was extracted as a SLEB128 value.
 507   ///
 508   /// @param[in] format
 509   ///     The optional printf format that can be overridden.
 510   //------------------------------------------------------------------
 511   size_t PutSLEB128(int64_t uval);
 512
 513   //------------------------------------------------------------------
 514   /// Output a ULEB128 number to the stream.
 515   ///
 516   /// Put an ULEB128 \a uval out to the stream using the printf format in \a
 517   /// format.
 518   ///
 519   /// @param[in] uval
 520   ///     A uint64_t value that was extracted as a ULEB128 value.
 521   ///
 522   /// @param[in] format
 523   ///     The optional printf format that can be overridden.
 524   //------------------------------------------------------------------
 525   size_t PutULEB128(uint64_t uval);
 526
 527 protected:
 528   //------------------------------------------------------------------
 529   // Member variables
 530   //------------------------------------------------------------------
 531   Flags m_flags;        ///< Dump flags.
 532   uint32_t m_addr_size; ///< Size of an address in bytes.
 533   lldb::ByteOrder
 534       m_byte_order;   ///< Byte order to use when encoding scalar types.
 535   int m_indent_level; ///< Indention level.
 536
 537   size_t _PutHex8(uint8_t uvalue, bool add_prefix);
 538 };
 539
 540 } // namespace lldb_private
 541
 542 #endif // liblldb_Stream_h_