diff options
Diffstat (limited to 'activesupport/lib/active_support/callbacks.rb')
| -rw-r--r-- | activesupport/lib/active_support/callbacks.rb | 155 |
1 files changed, 80 insertions, 75 deletions
diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb index 7166c21268..a02793bde9 100644 --- a/activesupport/lib/active_support/callbacks.rb +++ b/activesupport/lib/active_support/callbacks.rb @@ -5,22 +5,24 @@ require 'active_support/core_ext/kernel/reporting' require 'active_support/core_ext/kernel/singleton_class' module ActiveSupport - # \Callbacks are code hooks that are run at key points in an object's lifecycle. - # The typical use case is to have a base class define a set of callbacks relevant - # to the other functionality it supplies, so that subclasses can install callbacks - # that enhance or modify the base functionality without needing to override - # or redefine methods of the base class. + # Callbacks are code hooks that are run at key points in an object's lifecycle. + # The typical use case is to have a base class define a set of callbacks + # relevant to the other functionality it supplies, so that subclasses can + # install callbacks that enhance or modify the base functionality without + # needing to override or redefine methods of the base class. # - # Mixing in this module allows you to define the events in the object's lifecycle - # that will support callbacks (via +ClassMethods.define_callbacks+), set the instance - # methods, procs, or callback objects to be called (via +ClassMethods.set_callback+), - # and run the installed callbacks at the appropriate times (via +run_callbacks+). + # Mixing in this module allows you to define the events in the object's + # lifecycle that will support callbacks (via +ClassMethods.define_callbacks+), + # set the instance methods, procs, or callback objects to be called (via + # +ClassMethods.set_callback+), and run the installed callbacks at the + # appropriate times (via +run_callbacks+). # - # Three kinds of callbacks are supported: before callbacks, run before a certain event; - # after callbacks, run after the event; and around callbacks, blocks that surround the - # event, triggering it when they yield. Callback code can be contained in instance - # methods, procs or lambdas, or callback objects that respond to certain predetermined - # methods. See +ClassMethods.set_callback+ for details. + # Three kinds of callbacks are supported: before callbacks, run before a + # certain event; after callbacks, run after the event; and around callbacks, + # blocks that surround the event, triggering it when they yield. Callback code + # can be contained in instance methods, procs or lambdas, or callback objects + # that respond to certain predetermined methods. See +ClassMethods.set_callback+ + # for details. # # class Record # include ActiveSupport::Callbacks @@ -61,10 +63,11 @@ module ActiveSupport # Runs the callbacks for the given event. # # Calls the before and around callbacks in the order they were set, yields - # the block (if given one), and then runs the after callbacks in reverse order. + # the block (if given one), and then runs the after callbacks in reverse + # order. # - # If the callback chain was halted, returns +false+. Otherwise returns the result - # of the block, or +true+ if no block is given. + # If the callback chain was halted, returns +false+. Otherwise returns the + # result of the block, or +true+ if no block is given. # # run_callbacks :save do # save @@ -182,17 +185,17 @@ module ActiveSupport # Compile around filters with conditions into proxy methods # that contain the conditions. # - # For `set_callback :save, :around, :filter_name, :if => :condition': + # For `set_callback :save, :around, :filter_name, if: :condition': # - # def _conditional_callback_save_17 - # if condition - # filter_name do + # def _conditional_callback_save_17 + # if condition + # filter_name do + # yield self + # end + # else # yield self # end - # else - # yield self # end - # end def define_conditional_callback name = "_conditional_callback_#{@kind}_#{next_id}" @klass.class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1 @@ -211,7 +214,7 @@ module ActiveSupport # Options support the same options as filters themselves (and support # symbols, string, procs, and objects), so compile a conditional - # expression based on the options + # expression based on the options. def recompile_options! conditions = ["true"] @@ -230,19 +233,19 @@ module ActiveSupport # # Arrays:: Used in conditions. This is used to specify # multiple conditions. Used internally to - # merge conditions from skip_* filters - # Symbols:: A method to call - # Strings:: Some content to evaluate - # Procs:: A proc to call with the object - # Objects:: An object with a before_foo method on it to call + # merge conditions from skip_* filters. + # Symbols:: A method to call. + # Strings:: Some content to evaluate. + # Procs:: A proc to call with the object. + # Objects:: An object with a <tt>before_foo</tt> method on it to call. # # All of these objects are compiled into methods and handled # the same after this point: # - # Arrays:: Merged together into a single filter - # Symbols:: Already methods - # Strings:: class_eval'ed into methods - # Procs:: define_method'ed into methods + # Arrays:: Merged together into a single filter. + # Symbols:: Already methods. + # Strings:: class_eval'ed into methods. + # Procs:: define_method'ed into methods. # Objects:: # a method is created that calls the before_foo method # on the object. @@ -294,7 +297,7 @@ module ActiveSupport end end - # An Array with a compile method + # An Array with a compile method. class CallbackChain < Array #:nodoc:# attr_reader :name, :config @@ -351,7 +354,6 @@ module ActiveSupport # This is used internally to append, prepend and skip callbacks to the # CallbackChain. - # def __update_callbacks(name, filters = [], block = nil) #:nodoc: type = [:before, :after, :around].include?(filters.first) ? filters.shift : :before options = filters.last.is_a?(Hash) ? filters.pop : {} @@ -367,8 +369,8 @@ module ActiveSupport # Install a callback for the given event. # # set_callback :save, :before, :before_meth - # set_callback :save, :after, :after_meth, :if => :condition - # set_callback :save, :around, lambda { |r, &block| stuff; result = block.call; stuff } + # set_callback :save, :after, :after_meth, if: :condition + # set_callback :save, :around, ->(r, &block) { stuff; result = block.call; stuff } # # The second arguments indicates whether the callback is to be run +:before+, # +:after+, or +:around+ the event. If omitted, +:before+ is assumed. This @@ -376,29 +378,29 @@ module ActiveSupport # # set_callback :save, :before_meth # - # The callback can specified as a symbol naming an instance method; as a proc, - # lambda, or block; as a string to be instance evaluated; or as an object that - # responds to a certain method determined by the <tt>:scope</tt> argument to - # +define_callback+. + # The callback can specified as a symbol naming an instance method; as a + # proc, lambda, or block; as a string to be instance evaluated; or as an + # object that responds to a certain method determined by the <tt>:scope</tt> + # argument to +define_callback+. # # If a proc, lambda, or block is given, its body is evaluated in the context # of the current object. It can also optionally accept the current object as # an argument. # - # Before and around callbacks are called in the order that they are set; after - # callbacks are called in the reverse order. - # + # Before and around callbacks are called in the order that they are set; + # after callbacks are called in the reverse order. + # # Around callbacks can access the return value from the event, if it # wasn't halted, from the +yield+ call. # # ===== Options # - # * <tt>:if</tt> - A symbol naming an instance method or a proc; the callback - # will be called only when it returns a true value. - # * <tt>:unless</tt> - A symbol naming an instance method or a proc; the callback - # will be called only when it returns a false value. - # * <tt>:prepend</tt> - If true, the callback will be prepended to the existing - # chain rather than appended. + # * <tt>:if</tt> - A symbol naming an instance method or a proc; the + # callback will be called only when it returns a +true+ value. + # * <tt>:unless</tt> - A symbol naming an instance method or a proc; the + # callback will be called only when it returns a +false+ value. + # * <tt>:prepend</tt> - If +true+, the callback will be prepended to the + # existing chain rather than appended. def set_callback(name, *filter_list, &block) mapped = nil @@ -417,11 +419,12 @@ module ActiveSupport end end - # Skip a previously set callback. Like +set_callback+, <tt>:if</tt> or <tt>:unless</tt> - # options may be passed in order to control when the callback is skipped. + # Skip a previously set callback. Like +set_callback+, <tt>:if</tt> or + # <tt>:unless</tt> options may be passed in order to control when the + # callback is skipped. # # class Writer < Person - # skip_callback :validate, :before, :check_membership, :if => lambda { self.age > 18 } + # skip_callback :validate, :before, :check_membership, if: -> { self.age > 18 } # end def skip_callback(name, *filter_list, &block) __update_callbacks(name, filter_list, block) do |target, chain, type, filters, options| @@ -463,24 +466,25 @@ module ActiveSupport # # ===== Options # - # * <tt>:terminator</tt> - Determines when a before filter will halt the callback - # chain, preventing following callbacks from being called and the event from being - # triggered. This is a string to be eval'ed. The result of the callback is available - # in the <tt>result</tt> variable. + # * <tt>:terminator</tt> - Determines when a before filter will halt the + # callback chain, preventing following callbacks from being called and + # the event from being triggered. This is a string to be eval'ed. The + # result of the callback is available in the +result+ variable. # - # define_callbacks :validate, :terminator => "result == false" + # define_callbacks :validate, terminator: 'result == false' # # In this example, if any before validate callbacks returns +false+, - # other callbacks are not executed. Defaults to "false", meaning no value + # other callbacks are not executed. Defaults to +false+, meaning no value # halts the chain. # - # * <tt>:skip_after_callbacks_if_terminated</tt> - Determines if after callbacks should be terminated - # by the <tt>:terminator</tt> option. By default after callbacks executed no matter - # if callback chain was terminated or not. - # Option makes sence only when <tt>:terminator</tt> option is specified. + # * <tt>:skip_after_callbacks_if_terminated</tt> - Determines if after + # callbacks should be terminated by the <tt>:terminator</tt> option. By + # default after callbacks executed no matter if callback chain was + # terminated or not. Option makes sense only when <tt>:terminator</tt> + # option is specified. # - # * <tt>:scope</tt> - Indicates which methods should be executed when an object - # is used as a callback. + # * <tt>:scope</tt> - Indicates which methods should be executed when an + # object is used as a callback. # # class Audit # def before(caller) @@ -505,20 +509,21 @@ module ActiveSupport # end # end # - # In the above case whenever you save an account the method <tt>Audit#before</tt> will - # be called. On the other hand + # In the above case whenever you save an account the method + # <tt>Audit#before</tt> will be called. On the other hand # - # define_callbacks :save, :scope => [:kind, :name] + # define_callbacks :save, scope: [:kind, :name] # - # would trigger <tt>Audit#before_save</tt> instead. That's constructed by calling - # <tt>#{kind}_#{name}</tt> on the given instance. In this case "kind" is "before" and - # "name" is "save". In this context +:kind+ and +:name+ have special meanings: +:kind+ - # refers to the kind of callback (before/after/around) and +:name+ refers to the - # method on which callbacks are being defined. + # would trigger <tt>Audit#before_save</tt> instead. That's constructed + # by calling <tt>#{kind}_#{name}</tt> on the given instance. In this + # case "kind" is "before" and "name" is "save". In this context +:kind+ + # and +:name+ have special meanings: +:kind+ refers to the kind of + # callback (before/after/around) and +:name+ refers to the method on + # which callbacks are being defined. # # A declaration like # - # define_callbacks :save, :scope => [:name] + # define_callbacks :save, scope: [:name] # # would call <tt>Audit#save</tt>. def define_callbacks(*callbacks) |