toolkit/modules/Deprecated.jsm

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 "use strict";
   6
   7 this.EXPORTED_SYMBOLS = [ "Deprecated" ];
   8
   9 const Cu = Components.utils;
  10 const Ci = Components.interfaces;
  11 const PREF_DEPRECATION_WARNINGS = "devtools.errorconsole.deprecation_warnings";
  12
  13 Cu.import("resource://gre/modules/Services.jsm");
  14
  15 // A flag that indicates whether deprecation warnings should be logged.
  16 let logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
  17
  18 Services.prefs.addObserver(PREF_DEPRECATION_WARNINGS,
  19   function (aSubject, aTopic, aData) {
  20     logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
  21   }, false);
  22
  23 /**
  24  * Build a callstack log message.
  25  *
  26  * @param nsIStackFrame aStack
  27  *        A callstack to be converted into a string log message.
  28  */
  29 function stringifyCallstack (aStack) {
  30   // If aStack is invalid, use Components.stack (ignoring the last frame).
  31   if (!aStack || !(aStack instanceof Ci.nsIStackFrame)) {
  32     aStack = Components.stack.caller;
  33   }
  34
  35   let frame = aStack.caller;
  36   let msg = "";
  37   // Get every frame in the callstack.
  38   while (frame) {
  39     msg += frame.filename + " " + frame.lineNumber +
  40       " " + frame.name + "\n";
  41     frame = frame.caller;
  42   }
  43   return msg;
  44 }
  45
  46 this.Deprecated = {
  47   /**
  48    * Log a deprecation warning.
  49    *
  50    * @param string aText
  51    *        Deprecation warning text.
  52    * @param string aUrl
  53    *        A URL pointing to documentation describing deprecation
  54    *        and the way to address it.
  55    * @param nsIStackFrame aStack
  56    *        An optional callstack. If it is not provided a
  57    *        snapshot of the current JavaScript callstack will be
  58    *        logged.
  59    */
  60   warning: function (aText, aUrl, aStack) {
  61     if (!logWarnings) {
  62       return;
  63     }
  64
  65     // If URL is not provided, report an error.
  66     if (!aUrl) {
  67       Cu.reportError("Error in Deprecated.warning: warnings must " +
  68         "provide a URL documenting this deprecation.");
  69       return;
  70     }
  71
  72     let textMessage = "DEPRECATION WARNING: " + aText +
  73       "\nYou may find more details about this deprecation at: " +
  74       aUrl + "\n" +
  75       // Append a callstack part to the deprecation message.
  76       stringifyCallstack(aStack);
  77
  78     // Report deprecation warning.
  79     Cu.reportError(textMessage);
  80   }
  81 };