Adding upstream version 124.0.1.upstream/124.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 565 insertions, 0 deletions

diff --git a/js/public/Printer.h b/js/public/Printer.h
new file mode 100644
index 0000000000..644ffa9176
--- /dev/null
+++ b/js/public/Printer.h
@@ -0,0 +1,565 @@
+/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ * vim: set ts=8 sts=2 et sw=2 tw=80:
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#ifndef js_Printer_h
+#define js_Printer_h
+
+#include "mozilla/Attributes.h"
+#include "mozilla/glue/Debug.h"
+#include "mozilla/Range.h"
+
+#include <stdarg.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "js/TypeDecls.h"
+#include "js/Utility.h"
+
+// [SMDOC] *Printer, Sprinter, Fprinter, ...
+//
+// # Motivation
+//
+// In many places, we want to have functions which are capable of logging
+// various data structures. Previously, we had logging functions for each
+// storage, such as using `fwrite`, `printf` or `snprintf`. In additional cases,
+// many of these logging options were using a string serializing logging
+// function, only to discard the allocated string after it had been copied to a
+// file.
+//
+// GenericPrinter is an answer to avoid excessive amount of temporary
+// allocations which are used once, and a way to make logging functions work
+// independently of the backend they are used with.
+//
+// # Design
+//
+// The GenericPrinter implements most of `put`, `printf`, `vprintf` and
+// `putChar` functions, which are implemented using `put` and `putChar`
+// functions in the derivative classes. Thus, one does not have to reimplement
+// `putString` nor `printf` for each printer.
+//
+//   // Logging the value N to whatever printer is provided such as
+//   // a file or a string.
+//   void logN(GenericPrinter& out) {
+//     out.printf("[Logging] %d\n", this->n);
+//   }
+//
+// The printing functions are infallible, from the logging functions
+// perspective. If an issue happens while printing, this would be recorded by
+// the Printer, and this can be tested using `hadOutOfMemory` function by the
+// owner of the Printer instance.
+//
+// Even in case of failure, printing functions should remain safe to use. Thus
+// calling `put` twice in a row is safe even if no check for `hadOutOfMemory` is
+// performed. This is necessary to simplify the control flow and avoid bubble up
+// failures out of logging functions.
+//
+// Note, being safe to use does not imply correctness. In case of failure the
+// correctness of the printed characters is no longer guarantee. One should use
+// `hadOutOfMemory` function to know if any failure happened which might have
+// caused incorrect content to be saved. In some cases, such as `Sprinter`,
+// where the string buffer can be extracted, the returned value would account
+// for checking `hadOutOfMemory`.
+//
+// # Implementations
+//
+// The GenericPrinter is a base class where the derivative classes are providing
+// different implementations which have their own advantages and disadvantages:
+//
+//  - Fprinter: FILE* printer. Write the content directly to a file.
+//
+//  - Sprinter: System allocator C-string buffer. Write the content to a buffer
+//    which is reallocated as more content is added. The buffer can then be
+//    extracted into a C-string or a JSString, respectively using `release` and
+//    `releaseJS`.
+//
+//  - LSprinter: LifoAlloc C-string rope. Write the content to a list of chunks
+//    in a LifoAlloc buffer, no-reallocation occur but one should use
+//    `exportInto` to serialize its content to a Sprinter or a Fprinter. This is
+//    useful to avoid reallocation copies, while using an existing LifoAlloc.
+//
+//  - SEPrinter: Roughly the same as Fprinter for stderr, except it goes through
+//    printf_stderr, which makes sure the output goes to a useful place: the
+//    Android log or the Windows debug output.
+//
+//  - EscapePrinter: Wrapper around other printers, to escape characters when
+//    necessary.
+//
+// # Print UTF-16
+//
+// The GenericPrinter only handle `char` inputs, which is good enough for ASCII
+// and Latin1 character sets. However, to handle UTF-16, one should use an
+// EscapePrinter as well as a policy for escaping characters.
+//
+// One might require different escaping policies based on the escape sequences
+// and based on the set of accepted character for the content generated. For
+// example, JSON does not specify \x<XX> escape sequences.
+//
+// Today the following escape policies exists:
+//
+//  - StringEscape: Produce C-like escape sequences: \<c>, \x<XX> and \u<XXXX>.
+//  - JSONEscape: Produce JSON escape sequences: \<c> and \u<XXXX>.
+//
+// An escape policy is defined by 2 functions:
+//
+//   bool isSafeChar(char16_t c):
+//     Returns whether a character can be printed without being escaped.
+//
+//   void convertInto(GenericPrinter& out, char16_t c):
+//     Calls the printer with the escape sequence for the character given as
+//     argument.
+//
+// To use an escape policy, the printer should be wrapped using an EscapePrinter
+// as follows:
+//
+//   {
+//     // The escaped string is surrounded by double-quotes, escape the double
+//     // quotes as well.
+//     StringEscape esc('"');
+//
+//     // Wrap our existing `GenericPrinter& out` using the `EscapePrinter`.
+//     EscapePrinter ep(out, esc);
+//
+//     // Append a sequence of characters which might contain UTF-16 characters.
+//     ep.put(chars);
+//   }
+//
+
+namespace js {
+
+class LifoAlloc;
+
+// Generic printf interface, similar to an ostream in the standard library.
+//
+// This class is useful to make generic printers which can work either with a
+// file backend, with a buffer allocated with an JSContext or a link-list
+// of chunks allocated with a LifoAlloc.
+class JS_PUBLIC_API GenericPrinter {
+ protected:
+  bool hadOOM_;  // whether reportOutOfMemory() has been called.
+
+  constexpr GenericPrinter() : hadOOM_(false) {}
+
+ public:
+  // Puts |len| characters from |s| at the current position. This function might
+  // silently fail and the error can be tested using `hadOutOfMemory()`. Calling
+  // this function or any other printing functions after a failures is accepted,
+  // but the outcome would still remain incorrect and `hadOutOfMemory()` would
+  // still report any of the previous errors.
+  virtual void put(const char* s, size_t len) = 0;
+  inline void put(const char* s) { put(s, strlen(s)); }
+
+  // Put a mozilla::Span / mozilla::Range of Latin1Char or char16_t characters
+  // in the output.
+  //
+  // Note that the char16_t variant is expected to crash unless putChar is
+  // overriden to handle properly the full set of WTF-16 character set.
+  virtual void put(mozilla::Span<const JS::Latin1Char> str);
+  virtual void put(mozilla::Span<const char16_t> str);
+
+  // Same as the various put function but only appending a single character.
+  //
+  // Note that the char16_t variant is expected to crash unless putChar is
+  // overriden to handle properly the full set of WTF-16 character set.
+  virtual inline void putChar(const char c) { put(&c, 1); }
+  virtual inline void putChar(const JS::Latin1Char c) { putChar(char(c)); }
+  virtual inline void putChar(const char16_t c) {
+    MOZ_CRASH("Use an EscapePrinter to handle all characters");
+  }
+
+  virtual void putString(JSContext* cx, JSString* str);
+
+  // Prints a formatted string into the buffer.
+  void printf(const char* fmt, ...) MOZ_FORMAT_PRINTF(2, 3);
+  void vprintf(const char* fmt, va_list ap) MOZ_FORMAT_PRINTF(2, 0);
+
+  // In some cases, such as handling JSRopes in a less-quadratic worse-case,
+  // it might be useful to copy content which has already been generated.
+  //
+  // If the buffer is back-readable, then this function should return `true`
+  // and `putFromIndex` should be implemented to delegate to a `put` call at
+  // the matching index and the corresponding length. To provide the index
+  // argument of `putFromIndex`, the `index` method should also be implemented
+  // to return the index within the inner buffer used by the printer.
+  virtual bool canPutFromIndex() const { return false; }
+
+  // Append to the current buffer, bytes which have previously been appended
+  // before.
+  virtual void putFromIndex(size_t index, size_t length) {
+    MOZ_CRASH("Calls to putFromIndex should be guarded by canPutFromIndex.");
+  }
+
+  // When the printer has a seekable buffer and `canPutFromIndex` returns
+  // `true`, this function can return the `index` of the next character to be
+  // added to the buffer.
+  //
+  // This function is monotonic. Thus, if the printer encounter an
+  // Out-Of-Memory issue, then the returned index should be the maximal value
+  // ever returned.
+  virtual size_t index() const { return 0; }
+
+  // In some printers, this ensure that the content is fully written.
+  virtual void flush() { /* Do nothing */
+  }
+
+  // Report that a string operation failed to get the memory it requested.
+  virtual void reportOutOfMemory();
+
+  // Return true if this Sprinter ran out of memory.
+  virtual bool hadOutOfMemory() const { return hadOOM_; }
+};
+
+// Sprintf / JSSprintf, but with unlimited and automatically allocated
+// buffering.
+class JS_PUBLIC_API StringPrinter : public GenericPrinter {
+ public:
+  // Check that the invariant holds at the entry and exit of a scope.
+  struct InvariantChecker {
+    const StringPrinter* parent;
+
+    explicit InvariantChecker(const StringPrinter* p) : parent(p) {
+      parent->checkInvariants();
+    }
+
+    ~InvariantChecker() { parent->checkInvariants(); }
+  };
+
+  JSContext* maybeCx;
+
+ private:
+  static const size_t DefaultSize;
+#ifdef DEBUG
+  bool initialized;  // true if this is initialized, use for debug builds
+#endif
+  bool shouldReportOOM;  // whether to report OOM to the maybeCx
+  char* base;            // malloc'd buffer address
+  size_t size;           // size of buffer allocated at base
+  ptrdiff_t offset;      // offset of next free char in buffer
+
+  // The arena to be used by jemalloc to allocate the string into. This is
+  // selected by the child classes when calling the constructor. JSStrings have
+  // a different arena than strings which do not belong to the JS engine, and as
+  // such when building a JSString with the intent of avoiding reallocation, the
+  // destination arena has to be selected upfront.
+  arena_id_t arena;
+
+ private:
+  [[nodiscard]] bool realloc_(size_t newSize);
+
+ protected:
+  // JSContext* parameter is optional and can be omitted if the following
+  // are not used.
+  //   * putString method with JSString
+  //   * QuoteString function with JSString
+  //   * JSONQuoteString function with JSString
+  //
+  // If JSContext* parameter is not provided, or shouldReportOOM is false,
+  // the consumer should manually report OOM on any failure.
+  explicit StringPrinter(arena_id_t arena, JSContext* maybeCx = nullptr,
+                         bool shouldReportOOM = true);
+  ~StringPrinter();
+
+  JS::UniqueChars releaseChars();
+  JSString* releaseJS(JSContext* cx);
+
+ public:
+  // Initialize this sprinter, returns false on error.
+  [[nodiscard]] bool init();
+
+  void checkInvariants() const;
+
+  // Attempt to reserve len + 1 space (for a trailing nullptr byte). If the
+  // attempt succeeds, return a pointer to the start of that space and adjust
+  // the internal content. The caller *must* completely fill this space on
+  // success.
+  char* reserve(size_t len);
+
+  // Puts |len| characters from |s| at the current position. May OOM, which must
+  // be checked by testing the return value of releaseJS() at the end of
+  // printing.
+  virtual void put(const char* s, size_t len) final;
+  using GenericPrinter::put;  // pick up |put(const char* s);|
+
+  virtual bool canPutFromIndex() const final { return true; }
+  virtual void putFromIndex(size_t index, size_t length) final {
+    MOZ_ASSERT(index <= this->index());
+    MOZ_ASSERT(index + length <= this->index());
+    put(base + index, length);
+  }
+  virtual size_t index() const final { return length(); }
+
+  virtual void putString(JSContext* cx, JSString* str) final;
+
+  size_t length() const;
+
+  // When an OOM has already been reported on the Sprinter, this function will
+  // forward this error to the JSContext given in the Sprinter initialization.
+  //
+  // If no JSContext had been provided or the Sprinter is configured to not
+  // report OOM, then nothing happens.
+  void forwardOutOfMemory();
+};
+
+class JS_PUBLIC_API Sprinter : public StringPrinter {
+ public:
+  explicit Sprinter(JSContext* maybeCx = nullptr, bool shouldReportOOM = true)
+      : StringPrinter(js::MallocArena, maybeCx, shouldReportOOM) {}
+  ~Sprinter() {}
+
+  JS::UniqueChars release() { return releaseChars(); }
+};
+
+class JS_PUBLIC_API JSSprinter : public StringPrinter {
+ public:
+  explicit JSSprinter(JSContext* cx)
+      : StringPrinter(js::StringBufferArena, cx, true) {}
+  ~JSSprinter() {}
+
+  JSString* release(JSContext* cx) { return releaseJS(cx); }
+};
+
+// Fprinter, print a string directly into a file.
+class JS_PUBLIC_API Fprinter final : public GenericPrinter {
+ private:
+  FILE* file_;
+  bool init_;
+
+ public:
+  explicit Fprinter(FILE* fp);
+
+  constexpr Fprinter() : file_(nullptr), init_(false) {}
+
+#ifdef DEBUG
+  ~Fprinter();
+#endif
+
+  // Initialize this printer, returns false on error.
+  [[nodiscard]] bool init(const char* path);
+  void init(FILE* fp);
+  bool isInitialized() const { return file_ != nullptr; }
+  void flush() override;
+  void finish();
+
+  // Puts |len| characters from |s| at the current position. Errors may be
+  // detected with hadOutOfMemory() (which will be set for any fwrite() error,
+  // not just OOM.)
+  void put(const char* s, size_t len) override;
+  using GenericPrinter::put;  // pick up |put(const char* s);|
+};
+
+// SEprinter, print using printf_stderr (goes to Android log, Windows debug,
+// else just stderr).
+class SEprinter final : public GenericPrinter {
+ public:
+  constexpr SEprinter() {}
+
+  // Puts |len| characters from |s| at the current position. Ignores errors.
+  virtual void put(const char* s, size_t len) override {
+    printf_stderr("%.*s", int(len), s);
+  }
+  using GenericPrinter::put;  // pick up |put(const char* s);|
+};
+
+// LSprinter, is similar to Sprinter except that instead of using an
+// JSContext to allocate strings, it use a LifoAlloc as a backend for the
+// allocation of the chunk of the string.
+class JS_PUBLIC_API LSprinter final : public GenericPrinter {
+ private:
+  struct Chunk {
+    Chunk* next;
+    size_t length;
+
+    char* chars() { return reinterpret_cast<char*>(this + 1); }
+    char* end() { return chars() + length; }
+  };
+
+ private:
+  LifoAlloc* alloc_;  // LifoAlloc used as a backend of chunk allocations.
+  Chunk* head_;
+  Chunk* tail_;
+  size_t unused_;
+
+ public:
+  explicit LSprinter(LifoAlloc* lifoAlloc);
+  ~LSprinter();
+
+  // Copy the content of the chunks into another printer, such that we can
+  // flush the content of this printer to a file.
+  void exportInto(GenericPrinter& out) const;
+
+  // Drop the current string, and let them be free with the LifoAlloc.
+  void clear();
+
+  // Puts |len| characters from |s| at the current position.
+  virtual void put(const char* s, size_t len) override;
+  using GenericPrinter::put;  // pick up |put(const char* s);|
+};
+
+// Escaping printers work like any other printer except that any added character
+// are checked for escaping sequences. This one would escape a string such that
+// it can safely be embedded in a JS string.
+template <typename Delegate, typename Escape>
+class JS_PUBLIC_API EscapePrinter final : public GenericPrinter {
+  size_t lengthOfSafeChars(const char* s, size_t len) {
+    for (size_t i = 0; i < len; i++) {
+      if (!esc.isSafeChar(uint8_t(s[i]))) {
+        return i;
+      }
+    }
+    return len;
+  }
+
+ private:
+  Delegate& out;
+  Escape& esc;
+
+ public:
+  EscapePrinter(Delegate& out, Escape& esc) : out(out), esc(esc) {}
+  ~EscapePrinter() {}
+
+  using GenericPrinter::put;
+  void put(const char* s, size_t len) override {
+    const char* b = s;
+    while (len) {
+      size_t index = lengthOfSafeChars(b, len);
+      if (index) {
+        out.put(b, index);
+        len -= index;
+        b += index;
+      }
+      if (len) {
+        esc.convertInto(out, char16_t(uint8_t(*b)));
+        len -= 1;
+        b += 1;
+      }
+    }
+  }
+
+  inline void putChar(const char c) override {
+    if (esc.isSafeChar(char16_t(uint8_t(c)))) {
+      out.putChar(char(c));
+      return;
+    }
+    esc.convertInto(out, char16_t(uint8_t(c)));
+  }
+
+  inline void putChar(const JS::Latin1Char c) override {
+    if (esc.isSafeChar(char16_t(c))) {
+      out.putChar(char(c));
+      return;
+    }
+    esc.convertInto(out, char16_t(c));
+  }
+
+  inline void putChar(const char16_t c) override {
+    if (esc.isSafeChar(c)) {
+      out.putChar(char(c));
+      return;
+    }
+    esc.convertInto(out, c);
+  }
+
+  // Forward calls to delegated printer.
+  bool canPutFromIndex() const override { return out.canPutFromIndex(); }
+  void putFromIndex(size_t index, size_t length) final {
+    out.putFromIndex(index, length);
+  }
+  size_t index() const final { return out.index(); }
+  void flush() final { out.flush(); }
+  void reportOutOfMemory() final { out.reportOutOfMemory(); }
+  bool hadOutOfMemory() const final { return out.hadOutOfMemory(); }
+};
+
+class JS_PUBLIC_API JSONEscape {
+ public:
+  bool isSafeChar(char16_t c);
+  void convertInto(GenericPrinter& out, char16_t c);
+};
+
+class JS_PUBLIC_API StringEscape {
+ private:
+  const char quote = '\0';
+
+ public:
+  explicit StringEscape(const char quote = '\0') : quote(quote) {}
+
+  bool isSafeChar(char16_t c);
+  void convertInto(GenericPrinter& out, char16_t c);
+};
+
+// A GenericPrinter that formats everything at a nested indentation level.
+class JS_PUBLIC_API IndentedPrinter final : public GenericPrinter {
+  GenericPrinter& out_;
+  // The number of indents to insert at the beginning of each line.
+  uint32_t indentLevel_;
+  // The number of spaces to insert for each indent.
+  uint32_t indentAmount_;
+  // Whether we have seen a line ending and should insert an indent at the
+  // next line fragment.
+  bool pendingIndent_;
+
+  // Put an indent to `out_`
+  void putIndent();
+  // Put `s` to `out_`, inserting an indent if we need to
+  void putWithMaybeIndent(const char* s, size_t len);
+
+ public:
+  explicit IndentedPrinter(GenericPrinter& out, uint32_t indentLevel = 0,
+                           uint32_t indentAmount = 2)
+      : out_(out),
+        indentLevel_(indentLevel),
+        indentAmount_(indentAmount),
+        pendingIndent_(false) {}
+
+  // Automatically insert and remove and indent for a scope
+  class AutoIndent {
+    IndentedPrinter& printer_;
+
+   public:
+    explicit AutoIndent(IndentedPrinter& printer) : printer_(printer) {
+      printer_.setIndentLevel(printer_.indentLevel() + 1);
+    }
+    ~AutoIndent() { printer_.setIndentLevel(printer_.indentLevel() - 1); }
+  };
+
+  uint32_t indentLevel() const { return indentLevel_; }
+  void setIndentLevel(uint32_t indentLevel) { indentLevel_ = indentLevel; }
+
+  virtual void put(const char* s, size_t len) override;
+  using GenericPrinter::put;  // pick up |inline void put(const char* s);|
+};
+
+// Map escaped code to the letter/symbol escaped with a backslash.
+extern const char js_EscapeMap[];
+
+// Return a C-string containing the chars in str, with any non-printing chars
+// escaped. If the optional quote parameter is present and is not '\0', quotes
+// (as specified by the quote argument) are also escaped, and the quote
+// character is appended at the beginning and end of the result string.
+// The returned string is guaranteed to contain only ASCII characters.
+extern JS_PUBLIC_API JS::UniqueChars QuoteString(JSContext* cx, JSString* str,
+                                                 char quote = '\0');
+
+// Appends the quoted string to the given Sprinter. Follows the same semantics
+// as QuoteString from above.
+extern JS_PUBLIC_API void QuoteString(Sprinter* sp, JSString* str,
+                                      char quote = '\0');
+
+// Appends the quoted string to the given Sprinter. Follows the same
+// Appends the JSON quoted string to the given Sprinter.
+extern JS_PUBLIC_API void JSONQuoteString(StringPrinter* sp, JSString* str);
+
+// Internal implementation code for QuoteString methods above.
+enum class QuoteTarget { String, JSON };
+
+template <QuoteTarget target, typename CharT>
+void JS_PUBLIC_API QuoteString(Sprinter* sp,
+                               const mozilla::Range<const CharT>& chars,
+                               char quote = '\0');
+
+}  // namespace js
+
+#endif  // js_Printer_h