sentinel 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Lucas Húngaro
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,71 @@
+h1. Sentinel
+
+Transparent (unobtrusive) Observers for your Rubies.
+
+h2. Why?
+
+Developed for an specific need we had at "Busk":http://www.busk.com, 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.
+
+h2. How?
+
+First, install the gem:
+
+<pre>
+$ [sudo] gem install sentinel
+</pre>
+
+Then, add it as a dependency in your code using your favorite way (a simple require or mechanisms the bundler gem). 
+
+To use it, first you'll need an observer class that responds to a method called *_notify_* (which can be a class or instance method). All the observed method's arguments will be passed to this method, hence the _args_ splat.
+
+<pre>
+class MyObserver
+  def self.notify(*args)
+    puts "Do your thing!"
+  end
+end
+</pre>
+
+Then, simple include the _Sentinel_ module in the class and declare the observer. Sentinel can observe both class and instance methods:
+
+<pre>
+class MyClass
+  include Sentinel
+
+  def instance_method
+    puts "Hi from the instance method!"
+  end
+
+  def self.class_method
+    puts "Hi from the class method!"
+  end
+
+  observe :instance_method, :notify => MyObserver
+  observe :class_method, :notify => MyObserver, :class_method => true #to observe a class method
+end
+</pre>
+
+If we wanted to use instances of the Observer instead of the class itself, the declarations would be:
+
+<pre>
+  observe :instance_method, :notify => MyObserver.new
+  observe :class_method, :notify => MyObserver.new, :class_method => true #to observe a class method
+</pre>
+  
+In summary, any object that responds to *_notify_* will be accepted.
+
+And... that's it! Every time the observed method is called, the _notify_ method from the defined Observer will be called *before* it, then it will run normally.
+
+h2. Note on Patches/Pull Requests
+ 
+* 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.
+
+h3. Copyright
+
+Copyright (c) 2010 Lucas Húngaro. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,47 @@
+# encoding: utf-8
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sentinel"
+    gem.summary = %Q{Transparent (unobtrusive) Observers for your Ruby code}
+    gem.description = %Q{Transparent (unobtrusive) Observers for your Ruby code}
+    gem.email = "lucashungaro@gmail.com"
+    gem.homepage = "http://github.com/lucashungaro/sentinel"
+    gem.authors = ["Lucas Húngaro"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "mocha", ">= 0.9.8"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "sentinel #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/sentinel.rb

@@ -0,0 +1,34 @@
+module Sentinel
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+  
+  module ClassMethods
+    def observe(method_name, options = {})
+      unless options[:notify]
+        raise ArgumentError.new("You should provide the :notify option")
+      end
+      body = <<-CODE
+        define_method "#{method_name}_with_observer" do |*args|
+          options[:notify].notify(*args)
+          self.send("#{method_name}_without_observer", *args)
+        end
+
+        alias_method "#{method_name}_without_observer", method_name
+        alias_method method_name, "#{method_name}_with_observer"
+      CODE
+      
+      if options[:class_method]
+
+        metaclass = class << self; self; end
+
+        metaclass.instance_eval do
+          eval body
+        end
+        
+      else
+        eval body
+      end
+    end
+  end
+end

data/sentinel.gemspec

@@ -0,0 +1,62 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sentinel}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Lucas H\303\272ngaro"]
+  s.date = %q{2010-01-19}
+  s.description = %q{Transparent (unobtrusive) Observers for your Ruby code}
+  s.email = %q{lucashungaro@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.textile"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.textile",
+     "Rakefile",
+     "VERSION",
+     "lib/sentinel.rb",
+     "sentinel.gemspec",
+     "spec/fixtures/my_observer.rb",
+     "spec/fixtures/subject.rb",
+     "spec/sentinel_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/lucashungaro/sentinel}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Transparent (unobtrusive) Observers for your Ruby code}
+  s.test_files = [
+    "spec/fixtures/my_observer.rb",
+     "spec/fixtures/subject.rb",
+     "spec/sentinel_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<mocha>, [">= 0.9.8"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<mocha>, [">= 0.9.8"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<mocha>, [">= 0.9.8"])
+  end
+end
+

data/spec/fixtures/my_observer.rb

@@ -0,0 +1,5 @@
+class MyObserver
+  def self.notify(*args)
+    "Observing!"
+  end
+end

data/spec/fixtures/subject.rb

@@ -0,0 +1,25 @@
+class Subject
+  def instance_method
+    "hi from instance method!"
+  end
+  
+  def self.class_method
+    "hi from class method!"
+  end
+  
+  def instance_method_with_params(*params)
+    "hi from instance method with params!"
+  end
+  
+  def self.class_method_with_params(*params)
+    "hi from class method with params!"
+  end
+  
+  def instance_returning_something
+    42
+  end
+  
+  def self.class_returning_something
+    42
+  end
+end

data/spec/sentinel_spec.rb

@@ -0,0 +1,63 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require File.expand_path(File.dirname(__FILE__) + '/fixtures/my_observer')
+require File.expand_path(File.dirname(__FILE__) + '/fixtures/subject')
+
+describe Sentinel, "defining an observer for a method" do
+  before(:all) do
+    Subject.send(:include, Sentinel)
+  end
+  
+  context "with the minimum required options" do
+    it "should notify the specified Observer when calling a class method" do
+      Subject.send(:observe, :instance_method, :notify => MyObserver)
+      MyObserver.expects(:notify)
+
+      Subject.new.instance_method
+    end
+    
+    it "should notify the specified Observer when calling an instance method" do
+      Subject.send(:observe, :class_method, :notify => MyObserver, :class_method => true)
+      MyObserver.expects(:notify)
+      
+      Subject.class_method
+    end
+    
+    it "should not modify the observed methods output" do
+      Subject.send(:observe, :class_returning_something, :notify => MyObserver, :class_method => true)
+      Subject.send(:observe, :instance_returning_something, :notify => MyObserver)
+      
+      MyObserver.expects(:notify).twice
+
+      Subject.class_returning_something.should == 42
+      Subject.new.instance_returning_something.should == 42
+    end
+    
+    context "observing methods with parameters" do
+      it "should pass all parameters of the observed methods to the Observer" do
+        Subject.send(:observe, :class_method_with_params, :notify => MyObserver, :class_method => true)
+        Subject.send(:observe, :instance_method_with_params, :notify => MyObserver)
+
+        MyObserver.expects(:notify).twice.with("texto", 1)
+
+        Subject.class_method_with_params("texto", 1)
+        Subject.new.instance_method_with_params("texto", 1)
+      end
+    end
+  end
+  
+  context "without the minimum required options" do
+    it "should raise ArgumentError when the observer of an instance method is not defined" do
+      MyObserver.expects(:notify).never
+      Subject.expects(:observe).raises(ArgumentError)
+      
+      Subject.send(:observe, :instance_method) rescue nil
+    end
+
+    it "should raise ArgumentError when the observer of a class method is not defined" do
+      MyObserver.expects(:notify).never
+      Subject.expects(:observe).raises(ArgumentError)
+      
+      Subject.send(:observe, :class_method, :class_method => true) rescue nil
+    end
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'sentinel'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: sentinel
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- "Lucas H\xC3\xBAngaro"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-19 00:00:00 -02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.9.8
+    version: 
+description: Transparent (unobtrusive) Observers for your Ruby code
+email: lucashungaro@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.textile
+- Rakefile
+- VERSION
+- lib/sentinel.rb
+- sentinel.gemspec
+- spec/fixtures/my_observer.rb
+- spec/fixtures/subject.rb
+- spec/sentinel_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/lucashungaro/sentinel
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Transparent (unobtrusive) Observers for your Ruby code
+test_files: 
+- spec/fixtures/my_observer.rb
+- spec/fixtures/subject.rb
+- spec/sentinel_spec.rb
+- spec/spec_helper.rb