class Pry::Hooks

Implements a hooks system for Pry. A hook is a callable that is associated with an event. A number of events are currently provided by Pry, these include: `:when_started`, `:before_session`, `:after_session`. A hook must have a name, and is connected with an event by the `#add_hook` method. @example Adding a hook for the `:before_session` event.

Pry.config.hooks.add_hook(:before_session, :say_hi) do
  puts "hello"
end

Public Class Methods

from_hash(hash) click to toggle source

Converts a hash to a `Pry::Hooks` instance. All hooks defined this way are anonymous. This functionality is primarily to provide backwards-compatibility with the old hash-based hook system in Pry versions < 0.9.8 @param [Hash] hash The hash to convert to `Pry::Hooks`. @return [Pry::Hooks] The resulting `Pry::Hooks` instance.

# File lib/pry/hooks.rb, line 20
def self.from_hash(hash)
  instance = new
  hash.each do |k, v|
    instance.add_hook(k, nil, v)
  end

  instance
end
new() click to toggle source
# File lib/pry/hooks.rb, line 29
def initialize
  @hooks = {}
end

Public Instance Methods

[](event_name) click to toggle source

FIXME: This is a hack to alert people of the new API.

# File lib/pry/hooks.rb, line 54
def [](event_name)
  warn "`Pry.hooks[]` is deprecated! Please use the new `Pry::Hooks` API! http://rubydoc.info/github/pry/pry/master/Pry/Hooks"

  get_hook(event_name, nil)
end
[]=(event_name, callable) click to toggle source

FIXME: This is a hack to alert people of the new API.

# File lib/pry/hooks.rb, line 62
def []=(event_name, callable)
  warn "`Pry.hooks[]=` is deprecated! Please use the new `Pry::Hooks` API! http://rubydoc.info/github/pry/pry/master/Pry/Hooks"

  add_hook(event_name, nil, callable)
end
add_hook(event_name, hook_name, callable=nil, &block) click to toggle source

Add a new hook to be executed for the `name` even. @param [Symbol] event_name The name of the event. @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!" }
# File lib/pry/hooks.rb, line 114
def add_hook(event_name, hook_name, callable=nil, &block)
  @hooks[event_name] ||= []

  # do not allow duplicates, but allow multiple `nil` hooks
  # (anonymous hooks)
  if hook_exists?(event_name, hook_name) && !hook_name.nil?
    raise ArgumentError, "Hook with name '#{hook_name}' already defined!"
  end

  if !block && !callable
    raise ArgumentError, "Must provide a block or callable."
  end

  # ensure we only have one anonymous hook
  @hooks[event_name].delete_if { |h, k| h.nil? } if hook_name.nil?

  if block
    @hooks[event_name] << [hook_name, block]
  elsif callable
    @hooks[event_name] << [hook_name, callable]
  end

  self
end
clear(event_name) click to toggle source
Alias for: delete_hooks
clear_all() click to toggle source

Remove all events and hooks, clearing out the Pry::Hooks instance completely. @example

my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
my_hooks.clear_all
# File lib/pry/hooks.rb, line 239
def clear_all
  @hooks = {}
end
delete_hook(event_name, hook_name) click to toggle source

Delete a hook for an event. @param [Symbol] event_name The name of the event. @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)
# File lib/pry/hooks.rb, line 208
def delete_hook(event_name, hook_name)
  @hooks[event_name] ||= []
  deleted_callable = nil

  @hooks[event_name].delete_if do |current_hook_name, callable|
    if current_hook_name == hook_name
      deleted_callable = callable
      true
    else
      false
    end
  end
  deleted_callable
end
delete_hooks(event_name) click to toggle source

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)
# File lib/pry/hooks.rb, line 228
def delete_hooks(event_name)
  @hooks[event_name] = []
end
Also aliased as: clear
errors() click to toggle source
# File lib/pry/hooks.rb, line 48
def errors
  @errors ||= []
end
exec_hook(event_name, *args, &block) click to toggle source

Execute the list of hooks for the `event_name` event. @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!"
# File lib/pry/hooks.rb, line 146
def exec_hook(event_name, *args, &block)
  @hooks[event_name] ||= []

  # silence warnings to get rid of 1.8's "warning: multiple values
  # for a block parameter" warnings
  Pry::Helpers::BaseHelpers.silence_warnings do
    @hooks[event_name].map do |hook_name, callable|
      begin
        callable.call(*args, &block)
      rescue RescuableException => e
        errors << e
        e
      end
    end.last
  end
end
get_hook(event_name, hook_name) click to toggle source

Return a specific hook for a given event. @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!"
# File lib/pry/hooks.rb, line 181
def get_hook(event_name, hook_name)
  @hooks[event_name] ||= []
  hook = @hooks[event_name].find { |current_hook_name, callable| current_hook_name == hook_name }
  hook.last if hook
end
get_hooks(event_name) click to toggle source

Return the hash of hook names / hook functions for a given event. (Note that modifying the returned hash does not 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>}
# File lib/pry/hooks.rb, line 195
def get_hooks(event_name)
  @hooks[event_name] ||= []
  Hash[@hooks[event_name]]
end
hook_count(event_name) click to toggle source

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
# File lib/pry/hooks.rb, line 169
def hook_count(event_name)
  @hooks[event_name] ||= []
  @hooks[event_name].size
end
hook_exists?(event_name, hook_name) click to toggle source

@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`

# File lib/pry/hooks.rb, line 246
def hook_exists?(event_name, hook_name)
  !!(@hooks[event_name] && @hooks[event_name].find { |name, _| name == hook_name })
end
initialize_copy(orig) click to toggle source

Ensure that duplicates have their @hooks object

# File lib/pry/hooks.rb, line 34
def initialize_copy(orig)
  hooks_dup = @hooks.dup
  @hooks.each do |k, v|
    hooks_dup[k] = v.dup
  end

  @hooks = hooks_dup
end
merge(other) click to toggle source

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)
# File lib/pry/hooks.rb, line 100
def merge(other)
  self.dup.tap do |v|
    v.merge!(other)
  end
end
merge!(other) click to toggle source

Destructively merge the contents of two `Pry:Hooks` instances. @param [Pry::Hooks] other The `Pry::Hooks` instance to merge @return [Pry:Hooks] Returns the receiver. @example

hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
Pry::Hooks.new.merge!(hooks)
# File lib/pry/hooks.rb, line 74
def merge!(other)
  @hooks.merge!(other.dup.hooks) do |key, v1, v2|
    merge_arrays(v1, v2)
  end

  self
end

Protected Instance Methods

hooks() click to toggle source
# File lib/pry/hooks.rb, line 43
def hooks
  @hooks
end