1 module ActiveSupport
2 # Callbacks are hooks into the lifecycle of an object that allow you to trigger logic
3 # before or after an alteration of the object state.
4 #
5 # Mixing in this module allows you to define callbacks in your class.
6 #
7 # Example:
8 # class Storage
9 # include ActiveSupport::Callbacks
10 #
11 # define_callbacks :before_save, :after_save
12 # end
13 #
14 # class ConfigStorage < Storage
15 # before_save :saving_message
16 # def saving_message
17 # puts "saving..."
18 # end
19 #
20 # after_save do |object|
21 # puts "saved"
22 # end
23 #
24 # def save
25 # run_callbacks(:before_save)
26 # puts "- save"
27 # run_callbacks(:after_save)
28 # end
29 # end
30 #
31 # config = ConfigStorage.new
32 # config.save
33 #
34 # Output:
35 # saving...
36 # - save
37 # saved
38 #
39 # Callbacks from parent classes are inherited.
40 #
41 # Example:
42 # class Storage
43 # include ActiveSupport::Callbacks
44 #
45 # define_callbacks :before_save, :after_save
46 #
47 # before_save :prepare
48 # def prepare
49 # puts "preparing save"
50 # end
51 # end
52 #
53 # class ConfigStorage < Storage
54 # before_save :saving_message
55 # def saving_message
56 # puts "saving..."
57 # end
58 #
59 # after_save do |object|
60 # puts "saved"
61 # end
62 #
63 # def save
64 # run_callbacks(:before_save)
65 # puts "- save"
66 # run_callbacks(:after_save)
67 # end
68 # end
69 #
70 # config = ConfigStorage.new
71 # config.save
72 #
73 # Output:
74 # preparing save
75 # saving...
76 # - save
77 # saved
78 module Callbacks
79 class CallbackChain < Array
80 def self.build(kind, *methods, &block)
81 methods, options = extract_options(*methods, &block)
82 methods.map! { |method| Callback.new(kind, method, options) }
83 new(methods)
84 end
85
86 def run(object, options = {}, &terminator)
87 enumerator = options[:enumerator] || :each
88
89 unless block_given?
90 send(enumerator) { |callback| callback.call(object) }
91 else
92 send(enumerator) do |callback|
93 result = callback.call(object)
94 break result if terminator.call(result, object)
95 end
96 end
97 end
98
99 # TODO: Decompose into more Array like behavior
100 def replace_or_append!(chain)
101 if index = index(chain)
102 self[index] = chain
103 else
104 self << chain
105 end
106 self
107 end
108
109 def find(callback, &block)
110 select { |c| c == callback && (!block_given? || yield(c)) }.first
111 end
112
113 def delete(callback)
114 super(callback.is_a?(Callback) ? callback : find(callback))
115 end
116
117 private
118 def self.extract_options(*methods, &block)
119 methods.flatten!
120 options = methods.extract_options!
121 methods << block if block_given?
122 return methods, options
123 end
124
125 def extract_options(*methods, &block)
126 self.class.extract_options(*methods, &block)
127 end
128 end
129
130 class Callback
131 attr_reader :kind, :method, :identifier, :options
132
133 def initialize(kind, method, options = {})
134 @kind = kind
135 @method = method
136 @identifier = options[:identifier]
137 @options = options
138 end
139
140 def ==(other)
141 case other
142 when Callback
143 (self.identifier && self.identifier == other.identifier) || self.method == other.method
144 else
145 (self.identifier && self.identifier == other) || self.method == other
146 end
147 end
148
149 def eql?(other)
150 self == other
151 end
152
153 def dup
154 self.class.new(@kind, @method, @options.dup)
155 end
156
157 def hash
158 if @identifier
159 @identifier.hash
160 else
161 @method.hash
162 end
163 end
164
165 def call(*args, &block)
166 evaluate_method(method, *args, &block) if should_run_callback?(*args)
167 rescue LocalJumpError
168 raise ArgumentError,
169 "Cannot yield from a Proc type filter. The Proc must take two " +
170 "arguments and execute #call on the second argument."
171 end
172
173 private
174 def evaluate_method(method, *args, &block)
175 case method
176 when Symbol
177 object = args.shift
178 object.send(method, *args, &block)
179 when String
180 eval(method, args.first.instance_eval { binding })
181 when Proc, Method
182 method.call(*args, &block)
183 else
184 if method.respond_to?(kind)
185 method.send(kind, *args, &block)
186 else
187 raise ArgumentError,
188 "Callbacks must be a symbol denoting the method to call, a string to be evaluated, " +
189 "a block to be invoked, or an object responding to the callback method."
190 end
191 end
192 end
193
194 def should_run_callback?(*args)
195 [options[:if]].flatten.compact.all? { |a| evaluate_method(a, *args) } &&
196 ![options[:unless]].flatten.compact.any? { |a| evaluate_method(a, *args) }
197 end
198 end
199
200 def self.included(base)
201 base.extend ClassMethods
202 end
203
204 module ClassMethods
205 def define_callbacks(*callbacks)
206 callbacks.each do |callback|
207 class_eval <<-"end_eval"
208 def self.#{callback}(*methods, &block) # def self.before_save(*methods, &block)
209 callbacks = CallbackChain.build(:#{callback}, *methods, &block) # callbacks = CallbackChain.build(:before_save, *methods, &block)
210 @#{callback}_callbacks ||= CallbackChain.new # @before_save_callbacks ||= CallbackChain.new
211 @#{callback}_callbacks.concat callbacks # @before_save_callbacks.concat callbacks
212 end # end
213 #
214 def self.#{callback}_callback_chain # def self.before_save_callback_chain
215 @#{callback}_callbacks ||= CallbackChain.new # @before_save_callbacks ||= CallbackChain.new
216 #
217 if superclass.respond_to?(:#{callback}_callback_chain) # if superclass.respond_to?(:before_save_callback_chain)
218 CallbackChain.new( # CallbackChain.new(
219 superclass.#{callback}_callback_chain + # superclass.before_save_callback_chain +
220 @#{callback}_callbacks # @before_save_callbacks
221 ) # )
222 else # else
223 @#{callback}_callbacks # @before_save_callbacks
224 end # end
225 end # end
226 end_eval
227 end
228 end
229 end
230
231 # Runs all the callbacks defined for the given options.
232 #
233 # If a block is given it will be called after each callback receiving as arguments:
234 #
235 # * the result from the callback
236 # * the object which has the callback
237 #
238 # If the result from the block evaluates to false, the callback chain is stopped.
239 #
240 # Example:
241 # class Storage
242 # include ActiveSupport::Callbacks
243 #
244 # define_callbacks :before_save, :after_save
245 # end
246 #
247 # class ConfigStorage < Storage
248 # before_save :pass
249 # before_save :pass
250 # before_save :stop
251 # before_save :pass
252 #
253 # def pass
254 # puts "pass"
255 # end
256 #
257 # def stop
258 # puts "stop"
259 # return false
260 # end
261 #
262 # def save
263 # result = run_callbacks(:before_save) { |result, object| result == false }
264 # puts "- save" if result
265 # end
266 # end
267 #
268 # config = ConfigStorage.new
269 # config.save
270 #
271 # Output:
272 # pass
273 # pass
274 # stop
275 def run_callbacks(kind, options = {}, &block)
276 self.class.send("#{kind}_callback_chain").run(self, options, &block)
277 end
278 end
279 end