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