Class: CMDx::Callbacks

Inherits:
Object
  • Object
show all
Defined in:
lib/cmdx/callbacks.rb

Overview

Registry of lifecycle callbacks invoked by Runtime. Callbacks can be method names (Symbols dispatched via task.send), blocks/Procs (instance_exec'd on the task), or arbitrary #call objects.

Each registration may carry :if / :unless gates (Symbol, Proc, or any #call-able). Gates are evaluated against the task before the callback is invoked; non-passing gates skip the callback silently.

Constant Summary collapse

EVENTS =

Callback event names Runtime dispatches.

Set[
  :before_validation,
  :before_execution,
  :around_execution,
  :after_execution,
  :on_complete,
  :on_interrupted,
  :on_success,
  :on_skipped,
  :on_failed,
  :on_ok,
  :on_ko
].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Callbacks

Returns a new instance of Callbacks.



30
31
32
 
# File 'lib/cmdx/callbacks.rb', line 30

def initialize
  @registry = {}
end

Instance Attribute Details

#registry ⇒ Object (readonly)

Returns the value of attribute registry.



28
29
30
 
# File 'lib/cmdx/callbacks.rb', line 28

def registry
  @registry
end

Instance Method Details

#around(event, task, &body) { ... } ⇒ void

This method returns an undefined value.

Wraps block with every callback registered for event as a nested chain (outer-first by declaration order). Each callback receives a continuation it must invoke exactly once: Symbol callbacks get it as their block (use yield); Procs/blocks are instance_exec'd on the task with (task, continuation); arbitrary callables receive (task, continuation). Gates skip individual links silently while still running the body.

Parameters:

  • event (Symbol)
  • task (Task)
  • body (#call) —

    inner continuation (Runtime lifecycle body)

Yields:

  • the innermost link — the lifecycle body to wrap

Raises:

  • (CallbackError) —

    when a callback fails to invoke its continuation



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/cmdx/callbacks.rb', line 156

def around(event, task, &body)
  callbacks = registry[event]
  return yield if callbacks.nil? || callbacks.empty?

  callbacks.reverse_each.reduce(body) do |succ, (callable, options)|
    lambda do
      next succ.call unless Util.satisfied?(options[:if], options[:unless], task)

      called = false
      cont = lambda do
        called = true
        succ.call
      end

      invoke(callable, task, cont, &cont)

      called || raise(CallbackError, <<~MSG.chomp)
        #{event} callback did not invoke its continuation.
        See https://drexed.github.io/cmdx/callbacks/#around_execution-the-wrap-the-whole-thing-hook
      MSG
    end
  end.call
end

#count ⇒ Integer

Returns total callbacks across all events.

Returns:

  • (Integer) —

    total callbacks across all events



118
119
120
 
# File 'lib/cmdx/callbacks.rb', line 118

def count
  registry.each_value.sum(&:size)
end

#deregister(event, callable = nil) ⇒ Callbacks

Drops callbacks registered for event. With no callable, removes every callback for event. With a callable, removes only the entries whose callback matches callable by == (works for Symbol method names, classes/modules, and any callable held by reference). When the last entry for event is removed, the key itself is dropped.

Parameters:

  • event (Symbol) —

    one of EVENTS

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

    optional specific callback to remove

Returns:

Raises:

  • (ArgumentError) —

    when event is unknown



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/cmdx/callbacks.rb', line 83

def deregister(event, callable = nil)
  unless EVENTS.include?(event)
    raise ArgumentError, <<~MSG.chomp
      unknown callback event #{event.inspect}, must be one of #{EVENTS.to_a.inspect}.
      See https://drexed.github.io/cmdx/callbacks/#what-callbacks-exist
    MSG
  end

  if callable.nil?
    registry.delete(event)
  elsif (entries = registry[event])
    entries.reject! { |cb, _opts| cb == callable }
    registry.delete(event) if entries.empty?
  end

  self
end

#empty? ⇒ Boolean

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/cmdx/callbacks.rb', line 108

def empty?
  registry.empty?
end

#initialize_copy(source) ⇒ void

This method returns an undefined value.

Parameters:

  • source (Callbacks) —

    registry to duplicate



36
37
38
 
# File 'lib/cmdx/callbacks.rb', line 36

def initialize_copy(source)
  @registry = source.registry.transform_values(&:dup)
end

#key?(event) ⇒ Boolean

Returns whether a callback is registered under name.

Parameters:

  • name (Symbol)

Returns:

  • (Boolean) —

    whether a callback is registered under name



103
104
105
 
# File 'lib/cmdx/callbacks.rb', line 103

def key?(event)
  registry.key?(event)
end

#process(event, task) ⇒ void

This method returns an undefined value.

Fires each callback registered for event against task. Skips any callback whose :if/:unless gates fail.

Parameters:

  • event (Symbol)
  • task (Task)

Raises:

  • (ArgumentError) —

    when a callback is neither a Symbol nor responds to #call



129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/cmdx/callbacks.rb', line 129

def process(event, task)
  return if empty?

  callbacks = registry[event]
  return if callbacks.nil? || callbacks.empty?

  callbacks.each do |callable, options|
    next unless Util.satisfied?(options[:if], options[:unless], task)

    invoke(callable, task)
  end
end

#register(event, callable = nil, **options, &block) { ... } ⇒ Callbacks

Adds a callback for event.

Parameters:

  • event (Symbol) —

    one of EVENTS

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

    method name or callable; pass either this or a block

  • block (#call, nil) —

    callback body when callable is omitted

  • options (Hash{Symbol => Object})

Options Hash (**options):

  • :if (Symbol, Proc, #call) —

    gate that must evaluate truthy

  • :unless (Symbol, Proc, #call) —

    gate that must evaluate falsy

Yields:

  • the callback body

Returns:

Raises:

  • (ArgumentError) —

    when both callable and a block are given, when the callback type is invalid, or when event is unknown



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/cmdx/callbacks.rb', line 52

def register(event, callable = nil, **options, &block)
  callback = callable || block

  if callable && block
    raise ArgumentError, "callback: provide either a callable or a block, not both"
  elsif !callback.is_a?(Symbol) && !callback.respond_to?(:call)
    raise ArgumentError, <<~MSG.chomp
      callback must be a Symbol or respond to #call (got #{callback.class}).
      See https://drexed.github.io/cmdx/callbacks/#how-do-i-register-one
    MSG
  elsif !EVENTS.include?(event)
    raise ArgumentError, <<~MSG.chomp
      unknown callback event #{event.inspect}, must be one of #{EVENTS.to_a.inspect}.
      See https://drexed.github.io/cmdx/callbacks/#what-callbacks-exist
    MSG
  end

  (registry[event] ||= []) << [callback, options.freeze]
  self
end

#size ⇒ Integer

Returns number of distinct events with callbacks.

Returns:

  • (Integer) —

    number of distinct events with callbacks



113
114
115
 
# File 'lib/cmdx/callbacks.rb', line 113

def size
  registry.size
end