rainman 0.1.0

data/lib/rainman/exceptions.rb

@@ -0,0 +1,43 @@
+module Rainman
+  # AlreadyImplemented is raised when attempting to create a driver action
+  # that has already been defined.
+  class AlreadyImplemented < StandardError
+    def initialize(method)
+      super "Method #{method.inspect} already exists!"
+    end
+  end
+
+  # InvalidHandler is raised when attempting to access a handler that has
+  # not yet been registered.
+  class InvalidHandler < StandardError
+    def initialize(handler)
+      super "Handler #{handler.inspect} is invalid! Maybe you need to " <<
+            "call 'register_handler #{handler.inspect}'?"
+    end
+  end
+
+  # NoHandler is raised when attempting to do something that needs a handler,
+  # but no default or current handler can be found.
+  class NoHandler < StandardError
+    def initialize
+      super "No handler is set! Maybe you need to " <<
+            "call 'set_default_handler'?"
+    end
+  end
+
+  # MissingParameter is raised when trying to send a request to a runner that
+  # is missing parameters/arguments.
+  class MissingParameter < StandardError
+    def initialize(param)
+      super "Missing parameter #{param.inspect}!"
+    end
+  end
+
+  # MissingBlock is raised when trying to run an action that is missing a
+  # required block parameter.
+  class MissingBlock < LocalJumpError
+    def initialize(method)
+      super "Can't call #{method.inspect} without a block!"
+    end
+  end
+end

data/lib/rainman/handler.rb

@@ -0,0 +1,37 @@
+module Rainman
+  # The Handler module contains methods that are added to handler classes at
+  # runtime. They are available as class methods.
+  module Handler
+    # Public: The name of this handler.
+    #
+    # Returns a Symbol.
+    def handler_name
+      @handler_name
+    end
+
+    # Public: Get the the handler's parent_klass.
+    #
+    # Returns Rainman::Driver.self
+    def parent_klass
+      @parent_klass
+    end
+
+    # These instance methods are available to handler instances.
+    module InstanceMethods
+      # Public: A Runner is automatically available to handler instances.
+      #
+      # Returns a Rainman::Runner.
+      def runner
+        @runner ||= Rainman::Runner.new(self)
+      end
+    end
+
+    # Public: Extended hook; this adds the InstanceMethods module to handler
+    # classes.
+    #
+    # base - The Module/Class that was extended with this module.
+    def self.extended(base)
+      base.send(:include, InstanceMethods)
+    end
+  end
+end

data/lib/rainman/runner.rb

@@ -0,0 +1,81 @@
+module Rainman
+  # The Runner class delegates actions to handlers. It runs validations
+  # before executing the action.
+  #
+  # Examples
+  #
+  #   Runner.new(current_handler_instance).tap do |r|
+  #     r.transfer
+  #   end
+  class Runner
+    # Public: Gets the handler Class.
+    attr_reader :handler
+
+    # Public: Initialize a runner.
+    #
+    # handler - A handler Class instance.
+    #
+    # Examples
+    #
+    #   Runner.new(current_handler_instance)
+    def initialize(handler)
+      @handler = handler
+    end
+
+    # Public: Get the Symbol name of the handler.
+    #
+    # Returns a Symbol.
+    def name
+      handler.class.handler_name
+    end
+
+    # Public: Get the handler's parent_klass
+    #
+    # Returns Rainman::Driver.self
+    def parent_klass
+      handler.class.parent_klass
+    end
+
+    # Public: Delegates the given method to the handler.
+    #
+    # context - Set the context for the method (class/instance)
+    # method  - The method to send to the handler.
+    # args    - Arguments to be supplied to the method (optional).
+    # block   - Block to be supplied to the method (optional).
+    #
+    # Examples
+    #
+    #   execute(handler, :register)
+    #   execute(handler.parent_class, :register, { params: [] })
+    #   execute(handler, :register, :one, :argument) do
+    #     # some code
+    #   end
+    #
+    # Raises MissingParameter if validation fails due to missing parameters.
+    #
+    # Returns the result of the handler action.
+    def execute(context, method, *args, &block)
+      # verify params here
+      context.send(method, *args, &block)
+    end
+
+    # Internal: Method missing hook used to proxy methods to a handler.
+    #
+    # method - The missing method name.
+    # args   - Arguments to be supplied to the method (optional).
+    # block  - Block to be supplied to the method (optional).
+    #
+    # Raises NameError if handler does not respond to method.
+    #
+    # Returns the value of execute.
+    def method_missing(method, *args, &block)
+      if handler.respond_to?(method)
+        execute(handler, method, *args, &block)
+      elsif parent_klass.respond_to?(method)
+        execute(parent_klass, method, *args, &block)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/rainman/support.rb

@@ -0,0 +1,75 @@
+# This file contains a few methods from ActiveSupport that are used by
+# Rainman. If ActiveSupport has been loaded, those methods will be used rather
+# than those in this file.
+
+# From activesupport/lib/active_support/inflector/methods.rb
+class String
+  # Public: Convert a string into a constant. The constant must exist in
+  # ObjectSpace.
+  #
+  # Raises NameError if the constant does not exist.
+  #
+  # Returns a constant.
+  def constantize
+    names = split('::')
+    names.shift if names.empty? || names.first.empty?
+
+    constant = Object
+    names.each do |name|
+      constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+    end
+    constant
+  end unless respond_to?(:constantize)
+
+  # Public: Camel-case a string.
+  #
+  # Examples
+  #
+  #   "foo_bar"     #=> "FooBar"
+  #   "foo_bar/baz" #=> "FooBar::Baz"
+  #
+  # Returns a String.
+  def camelize(first_letter_in_uppercase = true)
+    if first_letter_in_uppercase
+      gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+    else
+      self[0].chr.downcase + camelize(self)[1..-1]
+    end
+  end unless respond_to?(:camelize)
+end
+
+# From lib/active_support/core_ext/hash/reverse_merge.rb
+class Hash
+  # Public: Reverse merge a hash.
+  #
+  # Example
+  #
+  #   a = { :one => :A }
+  #   b = a.reverse_merge(:one => :B, :two => :two)
+  #   a #=> { :one => :A }
+  #   b #=> { :one => :A, :two => :two }
+  #
+  # Returns a new Hash.
+  def reverse_merge(other_hash)
+    other_hash.merge(self)
+  end unless respond_to?(:reverse_merge)
+
+  # Public: Reverse merge a hash in-place.
+  #
+  # Example
+  #
+  #   a = { :one => :A }
+  #   a.reverse_merge!(:one => :B, :two => :two)
+  #   a #=> { :one => :A, :two => :two }
+  #
+  # Returns a Hash.
+  def reverse_merge!(other_hash)
+    # right wins if there is no left
+    merge!( other_hash ){|key,left,right| left }
+  end unless respond_to?(:reverse_merge!)
+
+  if respond_to?(:reverse_merge!) && ! respond_to?(:reverse_update)
+    # Alias Hash#reverse_update
+    alias_method :reverse_update, :reverse_merge!
+  end
+end

data/lib/rainman/version.rb

@@ -0,0 +1,3 @@
+module Rainman
+  VERSION = "0.1.0"
+end

data/lib/rainman.rb

@@ -0,0 +1,9 @@
+require "rainman/version"
+require "rainman/support"
+require "rainman/exceptions"
+require "rainman/handler"
+require "rainman/runner"
+require "rainman/driver"
+
+module Rainman
+end

data/rainman.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/rainman/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Justin Mazzi"]
+  gem.email         = ["jmazzi@gmail.com"]
+  gem.description   = %q{A library for writing drivers using the abstract factory pattern}
+  gem.summary       = %q{Rainman is an experiment in writing drivers and handlers. It is a Ruby implementation of the abstract factory pattern. Abstract factories provide the general API used to interact with any number of interfaces. Interfaces perform actual operations. Rainman provides a simple DSL for implementing this design.}
+  gem.homepage      = "http://www.eng5.com"
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "rainman"
+  gem.require_paths = ["lib"]
+  gem.version       = Rainman::VERSION
+
+  gem.add_development_dependency 'rspec', '~> 2.7.0'
+  gem.add_development_dependency 'autotest-standalone', '~> 4.5.8'
+  gem.add_development_dependency 'rake', '~> 0.9.2.2'
+end

data/spec/integration_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+require File.expand_path('../../example/domain.rb', __FILE__)
+
+describe "Rainman integration" do
+  describe Domain do
+    describe "handlers" do
+      subject { Domain.handlers }
+
+      its([:enom])    { should == Domain::Enom }
+      its([:opensrs]) { should == Domain::Opensrs }
+    end
+
+    its(:default_handler) { should == :opensrs }
+
+    it "has instance methods for each namespace/action" do
+      methods = subject.instance_methods.map(&:to_sym)
+      methods.should include(:nameservers, :list, :transfer)
+    end
+
+    describe "Opensrs integration" do
+      its(:list)              { should == :opensrs_list }
+      its(:transfer)          { should == :opensrs_transfer }
+      its("nameservers.list") { should == :opensrs_ns_list }
+    end
+
+    describe "Enom integration" do
+      before :all do
+        subject.set_default_handler :enom
+      end
+
+      after :all do
+        subject.set_default_handler :opensrs
+      end
+
+      its(:list)              { should == :enom_list }
+      its(:transfer)          { should == :enom_transfer }
+      its("nameservers.list") { should == :enom_ns_list }
+    end
+  end
+end

data/spec/rainman/driver_spec.rb

@@ -0,0 +1,323 @@
+require 'spec_helper'
+
+
+describe "Rainman::Driver" do
+  before do
+    Rainman::Driver.instance_variable_set(:@all, [])
+    @module = Module.new do
+      def self.name
+        'MissDaisy'
+      end
+    end
+    @module.extend Rainman::Driver
+    Object.send(:remove_const, :MissDaisy) if Object.const_defined?(:MissDaisy)
+    Object.const_set(:MissDaisy, @module)
+  end
+
+  describe "::extended" do
+    it "extends base with base" do
+      m = Module.new
+      m.should_receive(:extend).with(m)
+      Rainman::Driver.extended(m)
+    end
+  end
+
+  describe "::all" do
+    it "returns an array of registered drivers" do
+      Rainman::Driver.all.should == [@module]
+    end
+  end
+
+  describe "#handlers" do
+    it "returns an empty hash" do
+      @module.handlers.should == {}
+    end
+
+    it "raises exception when accessing an unknown key" do
+      expect { @module.handlers[:foo] }.to raise_error(Rainman::InvalidHandler)
+    end
+
+    it "raises exception when accessing a nil key" do
+      expect { @module.handlers[nil] }.to raise_error(Rainman::NoHandler)
+    end
+  end
+
+  describe "#with_handler" do
+    before do
+      @klass = Class.new do
+        def hi; :hi_handler!; end
+        def self.handler_name; :blah; end
+      end
+      @handler = @klass.new
+      runner = Rainman::Runner.new(@handler)
+      @handler.stub(:runner).and_return(runner)
+      @module.stub(:current_handler_instance).and_return(@handler)
+    end
+
+    it "should temporarily change the current handler" do
+      old_handler = :old_lady
+      @module.should_receive(:set_current_handler).with(:blah)
+      @module.should_receive(:set_current_handler).with(old_handler)
+      @module.stub(:current_handler).and_return(old_handler)
+      @module.with_handler(:blah) {}
+    end
+
+    it "should raise an error without a block" do
+      expect { @module.with_handler(:blah) }.to raise_error(Rainman::MissingBlock)
+    end
+
+    it "yields the runner" do
+      res = @module.with_handler :blah do |runner|
+        runner.should be_a(Rainman::Runner)
+        runner.hi
+      end
+      res.should == :hi_handler!
+    end
+  end
+
+  describe "#set_default_handler" do
+    it "sets @default_handler" do
+      @module.set_default_handler :blah
+      @module.instance_variable_get(:@default_handler).should == :blah
+    end
+  end
+
+  describe "#default_handler" do
+    it "gets @default_handler" do
+      expected = @module.instance_variable_get(:@default_handler)
+      @module.default_handler.should eq(expected)
+    end
+  end
+
+  describe "#included" do
+    it "extends base with Forwardable" do
+      klass = Class.new
+      klass.should_receive(:extend).with(::Forwardable)
+      klass.stub(:def_delegators)
+      klass.send(:include, @module)
+    end
+
+    it "sets up delegation for singleton methods" do
+      klass = Class.new
+      klass.should_receive(:def_delegators).with(@module, *@module.singleton_methods)
+      klass.send(:include, @module)
+    end
+  end
+
+  describe "#handler_instances" do
+    it "returns @handler_instances" do
+      @module.send(:handler_instances).should == {}
+      @module.instance_variable_set(:@handler_instances, { :foo => :test })
+      @module.send(:handler_instances).should == { :foo => :test }
+    end
+
+    it "should call handler_setup if it exists" do
+      module MissDaisy
+        extend Rainman::Driver
+        class WithSetup
+          attr_reader :setup
+
+          def setup_handler
+            @setup = true
+          end
+        end
+
+        class WithoutSetup
+          attr_reader :setup
+        end
+
+        register_handler :with_setup
+        register_handler :without_setup
+        define_action :setup
+      end
+
+      MissDaisy.set_current_handler :with_setup
+      MissDaisy.setup.should be_true
+      MissDaisy.set_current_handler :without_setup
+      MissDaisy.setup.should_not be_true
+    end
+  end
+
+  describe "#set_current_handler" do
+    it "sets @current_handler" do
+      @module.set_current_handler :blah
+      @module.instance_variable_get(:@current_handler).should == :blah
+      @module.set_current_handler :other
+      @module.instance_variable_get(:@current_handler).should == :other
+    end
+  end
+
+  describe "#current_handler_instance" do
+    before do
+      @class = Class.new
+      @klass = @class.new
+      @module.handlers[:abc] = @class
+      @module.send(:set_current_handler, :abc)
+    end
+
+    it "returns the handler instance" do
+      @module.send(:handler_instances).merge!(:abc => @klass)
+      @module.send(:current_handler_instance).should == @klass
+    end
+
+    it "sets the handler instance" do
+      @module.handlers[:abc] = @class
+      @class.should_receive(:new).and_return(@klass)
+      @module.send(:current_handler_instance).should be_a(@class)
+    end
+  end
+
+  describe "#current_handler" do
+    it "returns @current_handler if set" do
+      @module.instance_variable_set(:@current_handler, :blah)
+      @module.send(:current_handler).should == :blah
+    end
+
+    it "returns @default_handler if @current_handler is not set" do
+      @module.instance_variable_set(:@current_handler, nil)
+      @module.instance_variable_set(:@default_handler, :blah)
+      @module.send(:current_handler).should == :blah
+    end
+  end
+
+  describe "#register_handler" do
+    before do
+      @bob = Class.new do
+        def self.name; 'Bob'; end
+      end
+      @module.const_set(:Bob, @bob)
+    end
+
+    it "adds the handler to handlers" do
+      @module.send(:register_handler, :bob)
+      @module.handlers.should have_key(:bob)
+      @module.handlers[:bob].should == @bob
+    end
+
+    it "extends handler with handler methods" do
+      @bob.should_receive(:extend).with(Rainman::Handler)
+      @module.send(:register_handler, :bob)
+    end
+  end
+
+  describe "#define_action" do
+    it "creates the method" do
+      @module.should_not respond_to(:blah)
+      @module.send(:define_action, :blah)
+      @module.should respond_to(:blah)
+
+      klass = Class.new.new
+      runner = Rainman::Runner.new(klass)
+      klass.stub(:runner).and_return(runner)
+      @module.stub(:current_handler_instance).and_return(klass)
+      runner.should_receive(:send).with(:blah)
+
+      @module.blah
+    end
+  end
+
+  describe "#create_method" do
+    it "raises AlreadyImplemented if the method has been defined" do
+      @module.instance_eval do
+        def blah; end
+      end
+
+      expect do
+        @module.send(:create_method, :blah)
+      end.to raise_error(Rainman::AlreadyImplemented)
+    end
+
+    it "adds the method" do
+      @module.should_not respond_to(:blah)
+      @module.send(:create_method, :blah, lambda { :hi })
+      @module.should respond_to(:blah)
+      @module.blah.should == :hi
+    end
+  end
+
+  describe "#inject_handler_methods" do
+    before do
+      @bob = Class.new do
+        def self.name; 'Bob'; end
+      end
+      @module.const_set(:Bob, @bob)
+    end
+
+    it "extends Handler" do
+      @bob.should_receive(:extend).with(Rainman::Handler)
+      @module.send(:inject_handler_methods, @bob, :bob)
+    end
+
+    it "sets @handler_name class var" do
+      @module.send(:inject_handler_methods, @bob, :bob)
+      @bob.handler_name.should == :bob
+    end
+  end
+
+  describe "#namespace" do
+    def create_ns_class(name, base)
+      klass = Class.new do
+        def hi; self.class.handler_name; end
+        def bye; :nonono!; end
+        def self.handler_name; name; end
+        def self.validations; { :global => Rainman::Option.new(:global) }; end
+      end
+
+      set_const(base, name.to_s.camelize.to_sym, klass)
+    end
+
+    def set_const(base, name, const)
+      base.send(:remove_const, name) if base.const_defined?(name)
+      base.const_set(name, const)
+    end
+
+    before do
+      create_ns_class :abc, @module
+      create_ns_class :xyz, @module
+      create_ns_class :bob, @module::Abc
+      create_ns_class :bob, @module::Xyz
+
+      @module.send(:register_handler, :abc)
+      @module.send(:register_handler, :xyz)
+      @module.set_default_handler :abc
+      @module.send(:namespace, :bob) do
+        define_action :hi
+      end
+    end
+
+    it "sets an instance variable" do
+      [:abc, :xyz].each do |name|
+        @module.with_handler(name) { |h| h.bob.hi }
+        ivar = @module.instance_variable_get(:@bob)
+        ivar.should be_a(Hash)
+        ivar.should have_key(name)
+        ivar[name].should be_a(Module)
+      end
+    end
+
+    it "raises exception calling a method that isn't registered" do
+      expect { @module.bob.bye }.to raise_error(NoMethodError)
+    end
+
+    it "raises no exception calling a method that is registered" do
+      @module.bob.hi.should == "MissDaisy::Abc::Bob"
+    end
+
+    it "creates a method for the namespace" do
+      @module.should respond_to(:bob)
+    end
+
+    it "returns an anonymous Module" do
+      @module.bob.should be_a(Module)
+    end
+
+    it "uses the right handler" do
+      [:abc, :xyz].each do |h|
+        expected = "MissDaisy::#{h.to_s.capitalize}::Bob"
+        @module.with_handler(h) do |handler|
+          handler.bob.hi.should == expected
+        end
+      end
+    end
+  end
+end

data/spec/rainman/exceptions_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe "Rainman Exceptions" do
+
+  def self.test_exception(klass, opts = {})
+    describe "#{klass.to_s}" do
+      it "raises with message" do
+        const = Rainman.const_get(klass)
+        args  = opts[:args] || []
+        mesg  = opts[:message]
+        expect { raise const, *args }.to raise_error(const, mesg)
+      end
+    end
+  end
+
+  test_exception :AlreadyImplemented,
+    :args    => :blah,
+    :message => "Method :blah already exists!"
+
+  test_exception :InvalidHandler,
+    :args    => :blah,
+    :message => "Handler :blah is invalid! Maybe you need to call " <<
+                "'register_handler :blah'?"
+
+  test_exception :NoHandler,
+    :message => "No handler is set! Maybe you need to call " <<
+                "'set_default_handler'?"
+
+  test_exception :MissingParameter,
+    :args    => :blah,
+    :message => "Missing parameter :blah!"
+
+  test_exception :MissingBlock,
+    :args    => :blah,
+    :message => "Can't call :blah without a block!"
+end

data/spec/rainman/handler_spec.rb

@@ -0,0 +1,27 @@
+require 'spec_helper'
+
+describe Rainman::Handler do
+  before do
+    Rainman::Driver.instance_variable_set(:@all, [])
+    @module = Module.new do
+      def self.name
+        'MissDaisy'
+      end
+    end
+    @module.extend Rainman::Driver
+    Object.send(:remove_const, :MissDaisy) if Object.const_defined?(:MissDaisy)
+    Object.const_set(:MissDaisy, @module)
+
+    @class = Class.new do
+      extend Rainman::Handler
+    end
+    @class.instance_variable_set(:@handler_name, :blah)
+  end
+
+  describe "#handler_name" do
+    it "returns @handler_name" do
+      @class.handler_name.should == :blah
+      @class.handler_name.should eq @class.instance_variable_get(:@handler_name)
+    end
+  end
+end