js/public/Warnings.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /*
   8  * Functionality for issuing and handling warnings.
   9  *
  10  * Warnings are situations that aren't inherently full-blown errors (and perhaps
  11  * for spec compliance *can't* be), but that may represent dubious programming
  12  * practice that embeddings may wish to know about.
  13  *
  14  * SpiderMonkey recognizes an unspecified set of syntactic patterns and runtime
  15  * behaviors as triggering a warning.  Embeddings may also recognize and report
  16  * additional warnings.
  17  */
  18
  19 #ifndef js_Warnings_h
  20 #define js_Warnings_h
  21
  22 #include "mozilla/Assertions.h"  // MOZ_ASSERT
  23 #include "mozilla/Attributes.h"  // MOZ_FORMAT_PRINTF, MOZ_RAII
  24
  25 #include "jstypes.h"  // JS_PUBLIC_API
  26
  27 struct JS_PUBLIC_API JSContext;
  28 class JSErrorReport;
  29
  30 namespace JS {
  31
  32 /**
  33  * Report a warning represented by the sprintf-like conversion of ASCII format
  34  * filled from trailing ASCII arguments.
  35  *
  36  * Return true iff the warning was successfully reported without reporting an
  37  * error (or being upgraded into one).
  38  */
  39 extern JS_PUBLIC_API bool WarnASCII(JSContext* cx, const char* format, ...)
  40     MOZ_FORMAT_PRINTF(2, 3);
  41
  42 /**
  43  * Report a warning represented by the sprintf-like conversion of Latin-1 format
  44  * filled from trailing Latin-1 arguments.
  45  *
  46  * Return true iff the warning was successfully reported without reporting an
  47  * error (or being upgraded into one).
  48  */
  49 extern JS_PUBLIC_API bool WarnLatin1(JSContext* cx, const char* format, ...)
  50     MOZ_FORMAT_PRINTF(2, 3);
  51
  52 /**
  53  * Report a warning represented by the sprintf-like conversion of UTF-8 format
  54  * filled from trailing UTF-8 arguments.
  55  *
  56  * Return true iff the warning was successfully reported without reporting an
  57  * error (or being upgraded into one).
  58  */
  59 extern JS_PUBLIC_API bool WarnUTF8(JSContext* cx, const char* format, ...)
  60     MOZ_FORMAT_PRINTF(2, 3);
  61
  62 using WarningReporter = void (*)(JSContext* cx, JSErrorReport* report);
  63
  64 extern JS_PUBLIC_API WarningReporter GetWarningReporter(JSContext* cx);
  65
  66 extern JS_PUBLIC_API WarningReporter
  67 SetWarningReporter(JSContext* cx, WarningReporter reporter);
  68
  69 /**
  70  * A simple RAII class that clears the registered warning reporter on
  71  * construction and restores it on destruction.
  72  *
  73  * A fresh warning reporter *may* be set while an instance of this class is
  74  * live, but it must be unset in LIFO fashion by the time that instance is
  75  * destroyed.
  76  */
  77 class MOZ_RAII JS_PUBLIC_API AutoSuppressWarningReporter {
  78   JSContext* context_;
  79   WarningReporter prevReporter_;
  80
  81  public:
  82   explicit AutoSuppressWarningReporter(JSContext* cx) : context_(cx) {
  83     prevReporter_ = SetWarningReporter(context_, nullptr);
  84   }
  85
  86   ~AutoSuppressWarningReporter() {
  87 #ifdef DEBUG
  88     WarningReporter reporter =
  89 #endif
  90         SetWarningReporter(context_, prevReporter_);
  91     MOZ_ASSERT(reporter == nullptr, "Unexpected WarningReporter active");
  92     SetWarningReporter(context_, prevReporter_);
  93   }
  94 };
  95
  96 }  // namespace JS
  97
  98 #endif  // js_Warnings_h