1 /* See license.txt for terms of usage */
  2 
  3 define([
  4     "firebug/lib/trace"
  5 ],
  6 function(FBTrace) {
  7 "use strict";
  8 
  9 // ********************************************************************************************* //
 10 // Constants
 11 
 12 const Cc = Components.classes;
 13 const Ci = Components.interfaces;
 14 
 15 var consoleService = Cc["@mozilla.org/consoleservice;1"].getService(Ci["nsIConsoleService"]);
 16 
 17 var naggedCache = new WeakMap();
 18 
 19 // ********************************************************************************************* //
 20 // Module implementation
 21 
 22 /**
 23  * @name Deprecated
 24  * @lib Utility to warn and manage deprecations
 25  */
 26 var Deprecated = {};
 27 
 28 /**
 29  * Wraps a function to display a deprecation warning message
 30  * each time that function is called.
 31  *
 32  * @param {string} msg The message to display
 33  * @param {function} fnc The function to wrap
 34  * @param {Array or Array-like Object} [args] The arguments to pass to the wrapped function
 35  *
 36  * @returns {function} The wrapped function
 37  */
 38 Deprecated.deprecated = function(msg, fnc, args)
 39 {
 40     return function deprecationWrapper()
 41     {
 42         if (!naggedCache.has(fnc))
 43         {
 44             log(msg, Components.stack.caller);
 45 
 46             naggedCache.set(fnc, true);
 47         }
 48 
 49         return fnc.apply(this, args || arguments);
 50     }
 51 };
 52 
 53 /**
 54  * displays a message for deprecation
 55  *
 56  * @param {String} msg The message to display
 57  */
 58 Deprecated.log = function(msg)
 59 {
 60     return log(msg, Components.stack.caller);
 61 }
 62 
 63 // xxxFlorent: might have to be improved. Don't hesitate to tell what you think about it
 64 /**
 65  * define and marks a property as deprecated. The defined property is read-only.
 66  *
 67  * @param {object} obj The object for  which we define the new property
 68  * @param {string} propName The name of the property
 69  * @param {string} msg The deprecation message
 70  * @param {*} value The value returned when accessing the property
 71  *
 72  */
 73 Deprecated.deprecatedROProp = function(obj, propName, msg, value)
 74 {
 75     var descriptor = {
 76         get: Deprecated.deprecated(msg, function(){ return value; }),
 77     };
 78 
 79     Object.defineProperty(obj, propName, descriptor);
 80 };
 81 
 82 
 83 // ********************************************************************************************* //
 84 // Local helpers
 85 
 86 function log(msg, caller)
 87 {
 88     var explain = "Deprecated function, " + msg;
 89 
 90     if (FBTrace)
 91         FBTrace.sysout(explain, getStackDump(caller));
 92 
 93     if (consoleService)
 94         consoleService.logStringMessage(explain + " " + caller.toString());
 95 }
 96 
 97 function getStackDump(startFrame)
 98 {
 99     var lines = [];
100 
101     for (var frame = startFrame; frame; frame = frame.caller)
102         lines.push(frame.filename + " (" + frame.lineNumber + ")");
103 
104     return lines.join("\n");
105 };
106 
107 // ********************************************************************************************* //
108 // Registration
109 
110 return Deprecated;
111 
112 // ********************************************************************************************* //
113 });
114