Add "deprecate" module

diff --git a/atom/common/api/lib/deprecate.coffee b/atom/common/api/lib/deprecate.coffee
new file mode 100644 (file)
index 0000000..070a9fe
--- /dev/null
+++ b/atom/common/api/lib/deprecate.coffee
@@ -0,0 +1,62 @@
+# Deprecate a method.
+deprecate = (oldName, newName, fn) ->
+  warned = false
+  ->
+    unless warned or process.noDeprecation
+      warned = true
+      deprecate.warn oldName, newName
+    fn.apply this, arguments
+
+# The method is renamed.
+deprecate.rename = (object, oldName, newName) ->
+  warned = false
+  newMethod = ->
+    unless warned or process.noDeprecation
+      warned = true
+      deprecate.warn oldName, newName
+    this[newName].apply this, arguments
+  if typeof object is 'function'
+    object.prototype[oldName] = newMethod
+  else
+    object[oldName] = newMethod
+
+# Forward the method to member.
+deprecate.member = (object, method, member) ->
+  warned = false
+  object.prototype[method] = ->
+    unless warned or process.noDeprecation
+      warned = true
+      deprecate.warn method, "#{member}.#{method}"
+    this[member][method].apply this[member], arguments
+
+# Deprecate a property.
+deprecate.property = (object, property, method) ->
+  Object.defineProperty object, property,
+    get: ->
+      warned = false
+      unless warned or process.noDeprecation
+        warned = true
+        deprecate.warn "#{property} property", "#{method} method"
+      this[method]()
+
+# Deprecate an event.
+deprecate.event = (emitter, oldName, newName, fn) ->
+  warned = false
+  emitter.on newName, ->
+    if @listenerCount(oldName) > 0  # there is listeners for old API.
+      unless warned or process.noDeprecation
+        warned = true
+        deprecate.warn "'#{oldName}' event", "'#{newName}' event"
+      fn.apply this, arguments
+
+# Print deprecate warning.
+deprecate.warn = (oldName, newName) ->
+  message = "#{oldName} is deprecated. Use #{newName} instead."
+  if process.throwDeprecation
+    throw new Error(message)
+  else if process.traceDeprecation
+    console.trace message
+  else
+    console.warn "(electron) #{message}"
+
+module.exports = deprecate

diff --git a/filenames.gypi b/filenames.gypi
index 0e70347..b39362b 100644 (file)
--- a/filenames.gypi
+++ b/filenames.gypi
@@ -37,6 +37,7 @@
       'atom/common/api/lib/callbacks-registry.coffee',
       'atom/common/api/lib/clipboard.coffee',
       'atom/common/api/lib/crash-reporter.coffee',
+      'atom/common/api/lib/deprecate.coffee',
       'atom/common/api/lib/native-image.coffee',
       'atom/common/api/lib/shell.coffee',
       'atom/common/lib/init.coffee',