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

#initializeHooks

Returns a new instance of Hooks


25
26
27
# File 'lib/pry/hooks.rb', line 25

def initialize
  @hooks = Hash.new { |h, k| h[k] = [] }
end

Class Method Details

.defaultObject


15
16
17
18
19
20
21
22
23
# File 'lib/pry/hooks.rb', line 15

def self.default
  hooks = new
  hooks.add_hook(:before_session, :default) do |_out, _target, pry_instance|
    next if pry_instance.quiet?

    pry_instance.run_command('whereami --quiet')
  end
  hooks
end

Instance Method Details

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

Add a new hook to be executed for the event_name event.

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 no callable provided).

Returns:

  • (Pry:Hooks)

    The receiver.

Raises:

  • (ArgumentError)

81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# File 'lib/pry/hooks.rb', line 81

def add_hook(event_name, hook_name, callable = nil, &block)
  event_name = event_name.to_s

  # 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

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

  # 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_hooks(event_name)

This method returns an undefined value.

Clear all hooks functions for a given event.

Parameters:

  • event_name (String)

    The name of the event.


165
166
167
# File 'lib/pry/hooks.rb', line 165

def clear_event_hooks(event_name)
  @hooks[event_name.to_s] = []
end

#delete_hook(event_name, hook_name) ⇒ #call

Returns The deleted hook.

Parameters:

  • event_name (Symbol)

    The name of the event.

  • hook_name (Symbol)

    The name of the hook. to delete.

Returns:

  • (#call)

    The deleted hook.


147
148
149
150
151
152
153
154
155
156
157
158
159
# File 'lib/pry/hooks.rb', line 147

def delete_hook(event_name, hook_name)
  deleted_callable = nil

  @hooks[event_name.to_s].delete_if do |current_hook_name, callable|
    if current_hook_name == hook_name
      deleted_callable = callable
      true
    else
      false
    end
  end
  deleted_callable
end

#errorsObject


39
40
41
# File 'lib/pry/hooks.rb', line 39

def errors
  @errors ||= []
end

#exec_hook(event_name, *args, &block) ⇒ Object

Execute the list of hooks for the event_name event.

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.


108
109
110
111
112
113
114
115
116
117
# File 'lib/pry/hooks.rb', line 108

def exec_hook(event_name, *args, &block)
  @hooks[event_name.to_s].map do |_hook_name, callable|
    begin
      callable.call(*args, &block)
    rescue RescuableException => e
      errors << e
      e
    end
  end.last
end

#get_hook(event_name, hook_name) ⇒ #call

Returns a specific hook for a given event.

Parameters:

  • event_name (Symbol)

    The name of the event.

  • hook_name (Symbol)

    The name of the hook

Returns:

  • (#call)

    a specific hook for a given event.


128
129
130
131
132
133
# File 'lib/pry/hooks.rb', line 128

def get_hook(event_name, hook_name)
  hook = @hooks[event_name.to_s].find do |current_hook_name, _callable|
    current_hook_name == hook_name
  end
  hook.last if hook
end

#get_hooks(event_name) ⇒ Hash

Note:

Modifying the returned hash does not alter the hooks, use

add_hook/delete_hook for that.

Parameters:

  • event_name (Symbol)

    The name of the event.

Returns:

  • (Hash)

    The hash of hook names / hook functions.


139
140
141
# File 'lib/pry/hooks.rb', line 139

def get_hooks(event_name)
  Hash[@hooks[event_name.to_s]]
end

#hook_count(event_name) ⇒ Fixnum

Returns The number of hook functions for event_name.

Parameters:

  • event_name (Symbol)

    The name of the event.

Returns:

  • (Fixnum)

    The number of hook functions for event_name.


121
122
123
# File 'lib/pry/hooks.rb', line 121

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

#hook_exists?(event_name, hook_name) ⇒ Boolean

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


172
173
174
# File 'lib/pry/hooks.rb', line 172

def hook_exists?(event_name, hook_name)
  @hooks[event_name.to_s].map(&:first).include?(hook_name)
end

#initialize_copy(_orig) ⇒ Object

Ensure that duplicates have their @hooks object.


30
31
32
33
34
35
36
37
# File 'lib/pry/hooks.rb', line 30

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) ⇒ Pry::Hooks

Returns 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:

  • (Pry::Hooks)

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


69
70
71
72
73
# File 'lib/pry/hooks.rb', line 69

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

#merge!(other) ⇒ Pry:Hooks

Destructively merge the contents of two Pry:Hooks instances.

Parameters:

  • other (Pry::Hooks)

    The Pry::Hooks instance to merge

Returns:

  • (Pry:Hooks)

    The receiver.

See Also:


48
49
50
51
52
53
54
55
56
57
58
59
60
61
# File 'lib/pry/hooks.rb', line 48

def merge!(other)
  @hooks.merge!(other.dup.hooks) do |_key, array, other_array|
    temp_hash = {}
    output = []

    (array + other_array).reverse_each do |pair|
      temp_hash[pair.first] ||= output.unshift(pair)
    end

    output
  end

  self
end