Add a logging layer to address common issues (#381)

3 files changed, 48 insertions, 0 deletions

diff --git a/lib/hashie.rb b/lib/hashie.rb
index 55a986f..ba51861 100644
--- a/lib/hashie.rb
+++ b/lib/hashie.rb
@@ -1,6 +1,22 @@
+require 'logger'
 require 'hashie/version'
 
 module Hashie
+  # The logger that Hashie uses for reporting errors.
+  #
+  # @return [Logger]
+  def self.logger
+    @logger ||= Logger.new(STDOUT)
+  end
+
+  # Sets the logger that Hashie uses for reporting errors.
+  #
+  # @param logger [Logger] The logger to set as Hashie's logger.
+  # @return [void]
+  def self.logger=(logger)
+    @logger = logger
+  end
+
   autoload :Clash,              'hashie/clash'
   autoload :Dash,               'hashie/dash'
   autoload :Hash,               'hashie/hash'
@@ -8,6 +24,7 @@ module Hashie
   autoload :Trash,              'hashie/trash'
   autoload :Rash,               'hashie/rash'
   autoload :Array,              'hashie/array'
+  autoload :Utils,              'hashie/utils'
 
   module Extensions
     autoload :Coercion,          'hashie/extensions/coercion'
diff --git a/lib/hashie/mash.rb b/lib/hashie/mash.rb
index 0cae7ea..67143c6 100644
--- a/lib/hashie/mash.rb
+++ b/lib/hashie/mash.rb
@@ -109,6 +109,8 @@ module Hashie
     # a string before it is set, and Hashes will be converted
     # into Mashes for nesting purposes.
     def custom_writer(key, value, convert = true) #:nodoc:
+      key_as_symbol = key.to_sym
+      log_built_in_message(key_as_symbol) if methods.include?(key_as_symbol)
       regular_writer(convert_key(key), convert ? convert_value(value) : value)
     end
 
@@ -295,5 +297,18 @@ module Hashie
         val
       end
     end
+
+    private
+
+    def log_built_in_message(method_key)
+      method_information = Hashie::Utils.method_information(method(method_key))
+
+      Hashie.logger.warn(
+        'You are setting a key that conflicts with a built-in method ' \
+        "#{self.class}##{method_key} #{method_information}. " \
+        'This can cause unexpected behavior when accessing the key via as a ' \
+        'property. You can still access the key via the #[] method.'
+      )
+    end
   end
 end
diff --git a/lib/hashie/utils.rb b/lib/hashie/utils.rb
new file mode 100644
index 0000000..d8e05fe
--- /dev/null
+++ b/lib/hashie/utils.rb
@@ -0,0 +1,16 @@
+module Hashie
+  # A collection of helper methods that can be used throughout the gem.
+  module Utils
+    # Describes a method by where it was defined.
+    #
+    # @param bound_method [Method] The method to describe.
+    # @return [String]
+    def self.method_information(bound_method)
+      if bound_method.source_location
+        "defined at #{bound_method.source_location.join(':')}"
+      else
+        "defined in #{bound_method.owner}"
+      end
+    end
+  end
+end