1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/modules/Deprecated.jsm Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,81 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +"use strict";
1.9 +
1.10 +this.EXPORTED_SYMBOLS = [ "Deprecated" ];
1.11 +
1.12 +const Cu = Components.utils;
1.13 +const Ci = Components.interfaces;
1.14 +const PREF_DEPRECATION_WARNINGS = "devtools.errorconsole.deprecation_warnings";
1.15 +
1.16 +Cu.import("resource://gre/modules/Services.jsm");
1.17 +
1.18 +// A flag that indicates whether deprecation warnings should be logged.
1.19 +let logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
1.20 +
1.21 +Services.prefs.addObserver(PREF_DEPRECATION_WARNINGS,
1.22 + function (aSubject, aTopic, aData) {
1.23 + logWarnings = Services.prefs.getBoolPref(PREF_DEPRECATION_WARNINGS);
1.24 + }, false);
1.25 +
1.26 +/**
1.27 + * Build a callstack log message.
1.28 + *
1.29 + * @param nsIStackFrame aStack
1.30 + * A callstack to be converted into a string log message.
1.31 + */
1.32 +function stringifyCallstack (aStack) {
1.33 + // If aStack is invalid, use Components.stack (ignoring the last frame).
1.34 + if (!aStack || !(aStack instanceof Ci.nsIStackFrame)) {
1.35 + aStack = Components.stack.caller;
1.36 + }
1.37 +
1.38 + let frame = aStack.caller;
1.39 + let msg = "";
1.40 + // Get every frame in the callstack.
1.41 + while (frame) {
1.42 + msg += frame.filename + " " + frame.lineNumber +
1.43 + " " + frame.name + "\n";
1.44 + frame = frame.caller;
1.45 + }
1.46 + return msg;
1.47 +}
1.48 +
1.49 +const Deprecated = {
1.50 + /**
1.51 + * Log a deprecation warning.
1.52 + *
1.53 + * @param string aText
1.54 + * Deprecation warning text.
1.55 + * @param string aUrl
1.56 + * A URL pointing to documentation describing deprecation
1.57 + * and the way to address it.
1.58 + * @param nsIStackFrame aStack
1.59 + * An optional callstack. If it is not provided a
1.60 + * snapshot of the current JavaScript callstack will be
1.61 + * logged.
1.62 + */
1.63 + warning: function (aText, aUrl, aStack) {
1.64 + if (!logWarnings) {
1.65 + return;
1.66 + }
1.67 +
1.68 + // If URL is not provided, report an error.
1.69 + if (!aUrl) {
1.70 + Cu.reportError("Error in Deprecated.warning: warnings must " +
1.71 + "provide a URL documenting this deprecation.");
1.72 + return;
1.73 + }
1.74 +
1.75 + let textMessage = "DEPRECATION WARNING: " + aText +
1.76 + "\nYou may find more details about this deprecation at: " +
1.77 + aUrl + "\n" +
1.78 + // Append a callstack part to the deprecation message.
1.79 + stringifyCallstack(aStack);
1.80 +
1.81 + // Report deprecation warning.
1.82 + Cu.reportError(textMessage);
1.83 + }
1.84 +};
1.85 \ No newline at end of file
