diff --git a/Data/Scripts/001_Technical/009_Deprecation.rb b/Data/Scripts/001_Technical/009_Deprecation.rb new file mode 100644 index 000000000..0168bb52e --- /dev/null +++ b/Data/Scripts/001_Technical/009_Deprecation.rb @@ -0,0 +1,52 @@ +# The Deprecation module is used to warn game & plugin creators of deprecated +# methods. +module Deprecation + module_function + + # Sends a warning of a deprecated method into the debug console. + # @param method_name [String] name of the deprecated method + # @param removal_version [String] name of the version the method is removed in (optional) + # @param alternative [String] preferred alternative method (optional) + def warn_method(method_name, removal_version = nil, alternative = nil) + text = _INTL('WARN: usage of deprecated method "{1}" or its alias.', method_name) + unless removal_version.nil? + text += _INTL("\nThe method is slated to be"\ + " removed in Essentials {1}.", removal_version) + end + unless alternative.nil? + text += _INTL("\nUse \"{1}\" instead.", alternative) + end + echoln text + end +end + +# The Module class is extended to allow easy deprecation of instance and class methods. +class Module + private + + # Creates a deprecated alias for an instance method. + # Using it sends a warning to the debug console. + # @param alias_name [Symbol] the name of the new alias + # @param aliased_method_name [Symbol] the name of the aliased method + # @param removal_version [String] name of the version the alias is removed in (optional) + def deprecated_instance_method_alias(alias_name, aliased_method_name, removal_version = nil) + define_method(alias_name) do |*args| + alias_full_name = format('%s#%s', self.class.name, alias_name.to_s) + aliased_method_full_name = format('%s#%s', self.class.name, aliased_method_name.to_s) + Deprecation.warn_method(alias_full_name, removal_version, aliased_method_full_name) + method(aliased_method_name).call(*args) + end + end + + # Creates a deprecated alias for a class method. + # Using it sends a warning to the debug console. + # @param (see #deprecated_instance_method_alias) + def deprecated_class_method_alias(alias_name, aliased_method_name, removal_version = nil) + self.class.send(:define_method, alias_name) do |*args| + alias_full_name = format('%s::%s', self.name, alias_name.to_s) + aliased_method_full_name = format('%s::%s', self.name, aliased_method_name.to_s) + Deprecation.warn_method(alias_full_name, removal_version, aliased_method_full_name) + method(aliased_method_name).call(*args) + end + end +end