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