Class: Pry::Hooks

Inherits:
Object show all
Defined in:
lib/pry/hooks.rb

Overview

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 Pry::Hooks#add_hook method.

Examples:

Adding a hook for the :before_session event.

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

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Hooks) initialize

A new instance of Hooks



29
30
31
 
# File 'lib/pry/hooks.rb', line 29

def initialize
  @hooks = {}
end

Class Method Details

+ (Pry::Hooks) from_hash(hash)

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

Parameters:

  • hash (Hash) —

    The hash to convert to Pry::Hooks.

Returns:

  • (Pry::Hooks) —

    The resulting Pry::Hooks instance.



20
21
22
23
24
25
26
27
 
# 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

Instance Method Details

- (Object) [](event_name)

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



54
55
56
57
58
 
# 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

- (Object) []=(event_name, callable)

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



62
63
64
65
66
 
# 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

- (Pry:Hooks) add_hook(event_name, hook_name, callable = nil) { ... }

Add a new hook to be executed for the name even.

Examples:

Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }

Parameters:

  • event_name (Symbol) —

    The name of the event.

  • hook_name (Symbol) —

    The name of the hook.

  • callable (#call) (defaults to: nil) —

    The callable.

Yields:

  • The block to use as the callable (if callable parameter not provided)

Returns:

  • (Pry:Hooks) —

    Returns the receiver.



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# 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

- (Object) clear_all

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

Examples:

my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
my_hooks.clear_all


239
240
241
 
# File 'lib/pry/hooks.rb', line 239

def clear_all
  @hooks = {}
end

- (#call) delete_hook(event_name, hook_name)

Delete a hook for an event.

Examples:

my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
my_hooks.delete_hook(:before_session, :say_hi)

Parameters:

  • event_name (Symbol) —

    The name of the event.

  • hook_name (Symbol) —

    The name of the hook. to delete.

Returns:

  • (#call) —

    The deleted hook.



208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# 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

- (Object) delete_hooks(event_name) Also known as: clear

Clear all hooks functions for a given event.

Examples:

my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
my_hooks.delete_hook(:before_session)

Parameters:

  • event_name (String) —

    The name of the event.



228
229
230
 
# File 'lib/pry/hooks.rb', line 228

def delete_hooks(event_name)
  @hooks[event_name] = []
end

- (Object) errors 



48
49
50
 
# File 'lib/pry/hooks.rb', line 48

def errors
  @errors ||= []
end

- (Object) exec_hook(event_name, *args, &block)

Execute the list of hooks for the event_name event.

Examples:

my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
my_hooks.exec_hook(:before_session) #=> OUTPUT: "hi!"

Parameters:

  • event_name (Symbol) —

    The name of the event.

  • args (Array) —

    The arguments to pass to each hook function.

Returns:

  • (Object) —

    The return value of the last executed hook.



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# 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

- (#call) get_hook(event_name, hook_name)

Return a specific hook for a given event.

Examples:

my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
my_hooks.get_hook(:before_session, :say_hi).call #=> "hi!"

Parameters:

  • event_name (Symbol) —

    The name of the event.

  • Symbol[ (Symbol[ hook_name The name of the hook) —

    hook_name The name of the hook

Returns:

  • (#call) —

    The requested hook.



181
182
183
184
185
 
# 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

- (Hash) get_hooks(event_name)

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).

Examples:

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>}

Parameters:

  • event_name (Symbol) —

    The name of the event.

Returns:

  • (Hash) —

    The hash of hook names / hook functions.



195
196
197
198
 
# File 'lib/pry/hooks.rb', line 195

def get_hooks(event_name)
  @hooks[event_name] ||= []
  Hash[@hooks[event_name]]
end

- (Fixnum) hook_count(event_name)

Return the number of hook functions registered for the event_name event.

Examples:

my_hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
my_hooks.count(:before_session) #=> 1

Parameters:

  • event_name (Symbol) —

    The name of the event.

Returns:

  • (Fixnum) —

    The number of hook functions for event_name.



169
170
171
172
 
# File 'lib/pry/hooks.rb', line 169

def hook_count(event_name)
  @hooks[event_name] ||= []
  @hooks[event_name].size
end

- (Boolean) hook_exists?(event_name, hook_name) (private)

Whether the hook by the name hook_name

Parameters:

  • event_name (Symbol) —

    Name of the event.

  • hook_name (Symbol) —

    Name of the hook.

Returns:

  • (Boolean) —

    Whether the hook by the name hook_name



246
247
248
 
# File 'lib/pry/hooks.rb', line 246

def hook_exists?(event_name, hook_name)
  !!@hooks[event_name].find { |name, _| name == hook_name }
end

- (Object) initialize_copy(orig)

Ensure that duplicates have their @hooks object



34
35
36
37
38
39
40
41
 
# 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

- (Pry::Hooks) merge(other)

Return a new Pry::Hooks instance containing a merge of the contents of two Pry:Hooks instances,

Examples:

hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
Pry::Hooks.new.merge(hooks)

Parameters:

  • other (Pry::Hooks) —

    The Pry::Hooks instance to merge

Returns:



100
101
102
103
104
 
# File 'lib/pry/hooks.rb', line 100

def merge(other)
  self.dup.tap do |v|
    v.merge!(other)
  end
end

- (Pry:Hooks) merge!(other)

Destructively merge the contents of two Pry:Hooks instances.

Examples:

hooks = Pry::Hooks.new.add_hook(:before_session, :say_hi) { puts "hi!" }
Pry::Hooks.new.merge!(hooks)

Parameters:

  • other (Pry::Hooks) —

    The Pry::Hooks instance to merge

Returns:

  • (Pry:Hooks) —

    Returns the receiver.



74
75
76
77
78
79
80
 
# 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

- (Object) merge_arrays(array1, array2) (private) 



82
83
84
 
# File 'lib/pry/hooks.rb', line 82

def merge_arrays(array1, array2)
  uniq_keeping_last(array1 + array2, &:first)
end

- (Object) uniq_keeping_last(input, &block) (private) 



87
88
89
90
91
 
# File 'lib/pry/hooks.rb', line 87

def uniq_keeping_last(input, &block)
  hash, output = {}, []
  input.reverse.each{ |i| hash[block[i]] ||= (output.unshift i) }
  output
end