Class | CallbackList |
In: |
lib/callbacks.rb
|
Parent: | Object |
This class manages a list of callbacks.
Callbacks are managed by the class CallbackList. When they are added, a priority (just a number or anything Comparable with other priorities) is specified. The biggest the priority is, the earliest the callback will be considered.
Callbacks are processed for a given set of objects as long as they return false. If you want to stop processing, you must return true. Example :
cbl = CallbackList::new c1 = false c2 = false c3 = false cbl.add(10) { c1 = true; 1 } cbl.add(5) { c2 = true; true } cbl.add(0) { c3 = true } cbl.process('aa') puts "#{c1} #{c2} #{c3}"
This example would display "true true false" as callbacks processing was stopped after the second callback returned true.
In XMPP4R, callbacks’ priorities are quite normalized since we want to be able to "cascade" callbacks in a clean way. Here are values your code should take into account :
>= 200: | logging & debugging callbacks. Those callbacks should not consume elements. |
100-199: | Where Helpers register their callbacks. The normal value is 100, and Helpers shouldn’t register something else unless there’s a very good reason to. |
< 100: | all those numbers are normally available for your application. That’s enough, don’t you think ? |
Create a new list of callbacks
# File lib/callbacks.rb, line 43 43: def initialize 44: @list = [] 45: end
Add a callback to the list
List will be sorted afterwards
prio: | [Integer] the callback’s priority, the higher, the sooner. |
ref: | [String] the callback’s reference |
block: | [Block] a block to execute |
return: | [Jabber::CallbackList] The list, for chaining |
# File lib/callbacks.rb, line 56 56: def add(prio = 0, ref = nil, proc = nil, &block) 57: block = proc if proc 58: @list.push(Callback::new(prio, ref, block)) 59: @list.sort! { |a, b| b.priority <=> a.priority } 60: self 61: end
Delete a callback by reference
ref: | [String] the reference of the callback to delete |
return: | [CallBackList] The list, for chaining |
# File lib/callbacks.rb, line 67 67: def delete(ref) 68: @list.delete_if { |item| item.ref == ref } 69: self 70: end
Number of elements in the list
return: | [Integer] The number of elements |
# File lib/callbacks.rb, line 75 75: def length 76: @list.length 77: end
Process an element through all my callbacks. returns e.consumed?
e: | [Object] The elements to pass to the callback. You can pass |
several, but of course, you block must know how to handle them.
return: | [Boolean] true if the element has been consumed |
# File lib/callbacks.rb, line 84 84: def process(*e) 85: # process through callbacks 86: @list.each do |item| 87: return true if item.block.call(*e) == true 88: end 89: false 90: end