Wrapped config.hooks{=} to error on old API.

We no longer wish to support the (undocumented!!) hash-based hooks API. When a user attempts to use this API
Pry will raise a `Pry::ObsoleteError` exception with a message telling them to use `Pry::Hooks` instead.

lib/pry/config.rb

@@ -42,7 +42,18 @@ class Pry
     # @example
     #   Pry.hooks :before_session => proc { puts "hello" },
     #     :after_session => proc { puts "goodbye" }
-    attr_accessor :hooks
+    attr_reader :hooks
+
+    # FIXME:
+    # This is a hack to alert people of the new API.
+    # @param [Pry::Hooks] v Only accept `Pry::Hooks` now!
+    def hooks=(v)
+      if v.is_a?(Hash)
+        raise ObsoleteError, "Hash is now obsolete! Use a Pry::Hooks object instead! http://rubydoc.info/github/pry/pry/master/Pry/Hooks"
+      end
+
+      @hooks = v
+    end
 
     # Get/Set the stack of input objects that a Pry instance switches
     # to when its current input object encounters EOF.

lib/pry/hooks.rb

@@ -24,14 +24,24 @@ class Pry
       @errors ||= []
     end
 
+    # FIXME:
+    # This is a hack to alert people of the new API.
+    def [](*)
+      raise ObsoleteError, "`Pry.hooks[]` is no longer supported. Please use the new Pry::Hooks API! http://rubydoc.info/github/pry/pry/master/Pry/Hooks"
+    end
+
+    # FIXME:
+    # This is a hack to alert people of the new API.
+    def []=(*)
+      raise ObsoleteError, "`Pry.hooks[]=` is no longer supported. Please use the new Pry::Hooks API! http://rubydoc.info/github/pry/pry/master/Pry/Hooks"
+    end
+
     # Destructively merge the contents of two `Pry:Hooks` instances.
     # @param [Pry::Hooks] other The `Pry::Hooks` instance to merge
-
-
-
-    # TODO: implement by iterating over parameter and only overwriting
-    # elements in receiver if they exist in parameter, and adding
-    # other paramater elements to the end of the original's array
+    # @return [Pry:Hooks] Returns the receiver.
+    # @example
+    #   hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   Pry::Hooks.new.merge!(hooks)
     def merge!(other)
       @hooks.merge!(other.dup.hooks) do |key, v1, v2|
         merge_arrays(v1, v2)
@@ -55,6 +65,9 @@ class Pry
     # Return a new `Pry::Hooks` instance containing a merge of the contents of two `Pry:Hooks` instances,
     # @param [Pry::Hooks] other The `Pry::Hooks` instance to merge
     # @return [Pry::Hooks] The new hash.
+    # @example
+    #   hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   Pry::Hooks.new.merge(hooks)
     def merge(other)
       self.dup.tap do |v|
         v.merge!(other)
@@ -66,6 +79,9 @@ class Pry
     # @param [Symbol] hook_name The name of the hook.
     # @param [#call] callable The callable.
     # @yield The block to use as the callable (if `callable` parameter not provided)
+    # @return [Pry:Hooks] Returns the receiver.
+    # @example
+    #   Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
     def add_hook(event_name, hook_name, callable=nil, &block)
       @hooks[event_name] ||= []
 
@@ -87,6 +103,9 @@ class Pry
     # @param [Symbol] event_name The name of the event.
     # @param [Array] args The arguments to pass to each hook function.
     # @return [Object] The return value of the last executed hook.
+    # @example
+    #   my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   my_hooks.exec_hook(:before_session) #=> OUTPUT: "hi!"
     def exec_hook(event_name, *args, &block)
       @hooks[event_name] ||= []
 
@@ -107,6 +126,9 @@ class Pry
     # Return the number of hook functions registered for the `event_name` event.
     # @param [Symbol] event_name The name of the event.
     # @return [Fixnum] The number of hook functions for `event_name`.
+    # @example
+    #   my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   my_hooks.count(:before_session) #=> 1
     def hook_count(event_name)
       @hooks[event_name] ||= []
       @hooks[event_name].size
@@ -116,6 +138,9 @@ class Pry
     # @param [Symbol] event_name The name of the event.
     # @param [Symbol[ hook_name The name of the hook
     # @return [#call] The requested hook.
+    # @example
+    #   my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   my_hooks.get_hook(:before_session, :say_hi).call #=> "hi!"
     def get_hook(event_name, hook_name)
       @hooks[event_name] ||= []
       hook = @hooks[event_name].find { |current_hook_name, callable| current_hook_name == hook_name }
@@ -127,6 +152,9 @@ class Pry
     # alter the hooks, use add_hook/delete_hook for that).
     # @param [Symbol] event_name The name of the event.
     # @return [Hash] The hash of hook names / hook functions.
+    # @example
+    #   my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   my_hooks.get_hooks(:before_session) #=> {:say_hi=>#<Proc:0x00000101645e18@(pry):9>}
     def get_hooks(event_name)
       @hooks[event_name] ||= []
       Hash[@hooks[event_name]]
@@ -137,6 +165,9 @@ class Pry
     # @param [Symbol] hook_name The name of the hook.
     #   to delete.
     # @return [#call] The deleted hook.
+    # @example
+    #   my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   my_hooks.delete_hook(:before_session, :say_hi)
     def delete_hook(event_name, hook_name)
       @hooks[event_name] ||= []
       deleted_callable = nil
@@ -154,6 +185,9 @@ class Pry
 
     # Clear all hooks functions for a given event.
     # @param [String] event_name The name of the event.
+    # @example
+    #   my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
+    #   my_hooks.delete_hook(:before_session)
     def delete_hooks(event_name)
       @hooks[event_name] = []
     end
@@ -163,7 +197,6 @@ class Pry
     # @param [Symbol] event_name Name of the event.
     # @param [Symbol] hook_name Name of the hook.
     # @return [Boolean] Whether the hook by the name `hook_name`
-    #   is defined for the event.
     def hook_exists?(event_name, hook_name)
       !!@hooks[event_name].find { |name, _| name == hook_name }
     end

lib/pry/pry_instance.rb

@@ -7,7 +7,6 @@ class Pry
   attr_accessor :commands
   attr_accessor :print
   attr_accessor :exception_handler
-  attr_accessor :hooks
   attr_accessor :input_stack
 
   attr_accessor :custom_completions
@@ -25,6 +24,21 @@ class Pry
 
   attr_accessor :backtrace
 
+  # Special treatment for hooks as we want to alert people of the
+  # changed API
+  attr_reader :hooks
+
+  # FIXME:
+  # This is a hack to alert people of the new API.
+  # @param [Pry::Hooks] v Only accept `Pry::Hooks` now!
+  def hooks=(v)
+    if v.is_a?(Hash)
+      raise ObsoleteError, "Error: Hash is now obsolete! Use a Pry::Hooks object instead! http://rubydoc.info/github/pry/pry/master/Pry/Hooks"
+    end
+
+    @hooks = v
+  end
+
   # Create a new `Pry` object.
   # @param [Hash] options The optional configuration parameters.
   # @option options [#readline] :input The object to use for input.

test/test_hooks.rb

@@ -415,6 +415,52 @@ describe Pry::Hooks do
         end
       end
     end
+  end
+
+  describe "obsolete API" do
+    describe "Pry.config.hooks" do
+      it 'should raise a Pry::ObsoleteError when assigning a hash' do
+        begin
+          Pry.config.hooks = {}
+        rescue => ex
+        end
+
+        ex.is_a?(Pry::ObsoleteError).should == true
+      end
+
+      describe "Pry.config.hooks[]" do
+        it 'should raise a Pry::ObsoleteError when accessing it in a hash style, Pry.config.hooks[]' do
+          begin
+            Pry.config.hooks[:before_session]
+          rescue => ex
+          end
+
+          ex.is_a?(Pry::ObsoleteError).should == true
+        end
+
+        it 'should raise a Pry::ObsoleteError when accessing it in a hash style, Pry.config.hooks[]=' do
+          begin
+            Pry.config.hooks[:before_session]
+          rescue => ex
+          end
+
+          ex.is_a?(Pry::ObsoleteError).should == true
+        end
 
       end
+
+    end
+
+    describe "Pry.start" do
+      it 'should raise a Pry::ObsoleteError when passing in a :hooks option with a hash' do
+        begin
+          Pry.start binding, :hooks => { :before_session => proc { puts 'yo' } }
+        rescue => ex
+        end
+
+        ex.is_a?(Pry::ObsoleteError).should == true
+      end
+
+    end
+  end
 end