Transparent (unobtrusive) Observers for your Rubies.
Sentinel is a very small library that provides a way to add what we call “Transparent Observers” to your Ruby code. This means that you do not need to modify the observed methods (following the most common implementation of Observers), just use a mixin and declare your observers.
First, install it as you would any regular Ruby gem.
To use it, first you’ll need an observer class with the Sentinel mixin. This class contains the methods to be notified and the configuration specifying what subject methods will be observed. See an example below:
class MyObserver
include Sentinel
observe MyClass, :instance_method
observe MyClass, :class_method, :method_to_notify => :notify_class_method, :class_method => true #to observe a class method
def self.notify(options, *args)
puts "Do your thing! Called from #{options[:subject]}"
end
def self.notify_class_method(options, *args)
puts "Called class_method! Returned #{options[:result]}"
end
end
As you can see, Sentinel can observe both class and instance methods. The notify method is the default one if you don’t specify the :method_to_notify option. Now, our actual class:
class MyClass
def instance_method
puts "Hi from the instance method!"
end
def self.class_method
puts "Hi from the class method!"
end
end
And… that’s it! Every time the subject (in this case, MyClass) method is called, the specified observer method will be called too. By default, the observer method is called after the subject method execution, but you can call it before it too (we’ll see that in the next example).
The parameters passed to the subject method are passed to the observer method via the *args array. The observer method also receives an options hash with the key :subject, which contains the actual subject object and the key :result, which contains the return of the observed method in case you intercepted the call after its execution.
Below is an example showing the interception before the execution:
class MyObserver
include Sentinel
observe MyClass, :instance_method, :intercept => :before
def self.notify(options, *args)
puts "Called from #{options[:subject]} with arguments #{args.inspect}"
end
end
- Fork the project.
- Make your feature addition or bug fix.
- Add tests for it. This is important so I don’t break it in a
future version unintentionally. - Commit, do not mess with rakefile, version, or history.
(if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull) - Send me a pull request. Bonus points for topic branches.
sentinel is released under the MIT license. See MIT LICENSE.