argible 0.1.0

data/README

@@ -0,0 +1,90 @@
+= ARGIBLE
+
+by {Michael Ward}[http://m2ward.blogspot.com]
+
+== DESCRIPTION:
+
+A gem that allows for automatic resolution of a methods argument values.
+
+== SYNOPSIS:
+
+Argible was created to simplify Actions within your Ruby on Rails Controllers.  Argible annotated action methods will
+allow your actions to define argument.  These argument names will be used in conjunction with request parameters to
+automatically resolve of these argument values.
+
+== INSTALL:
+
+You can download Argible from here[http://rubyforge.org/projects/argible] or install it with the following command.
+
+<tt>$ gem install argible</tt>
+
+To use as a Rails plug-in unpack the gem into your applications <tt>vendor/plugin</tt> directory:
+
+<tt>$ gem unpack argible</tt>
+
+== USAGE:
+
+Have a look at the following Controller:
+
+  class FoobarController < ApplicationController
+
+    argible
+    def action_one(alpha)
+      ...
+    end
+
+    argible(:date => Date.method(:parse))
+    def action_two(date)
+      ...
+    end
+
+    argible(:date => lambda {|v| Date.parse(v) } )
+    def action_three(date)
+      ...
+    end
+
+    argible(:value => :to_i)
+    def action_four(value)
+      ...
+    end
+  end
+
+The first method *action_one* is annotated with the method *argible*.  When the action_one action method is executed
+Argible will intercept the call and look up the request parameter value associated with *alpha*.  Then action_one will
+be called with this resolved value.
+
+The second action *action_two* provides an example of how more complex processing can occur on argument values.  As in
+the first example the argument *date* is resolved against the request parameters.  This value will then be passed to the
+Date#parse method.  The result from Date#parse will then be used when *action_two* is called. **NOTE:** any method can
+be used, Date#parse is simply used as an example.
+
+The action *action_three* provides an example of using a Proc (lambda) as alternative to a named method.
+
+The fourth example action *action_four* illustrates how you can call methods directly on the String value returned from
+the request parameter
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007 Michael Ward
+
+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/init.rb

@@ -0,0 +1,3 @@
+require 'argible'
+
+ActionController::Base.send(:include, ::Argible)

data/lib/argible.rb

@@ -0,0 +1,143 @@
+require 'parse_tree'
+
+module Argible
+
+  # defines information about the method being annotated
+  class MethodDefinition
+    attr_accessor :name, :options
+    attr_reader :arguments
+
+    def initialize(options)
+      @options = options
+    end
+
+    def arguments=(arguments)
+      @arguments = arguments.select { |arg| arg.is_a?(Symbol) } # Only grab argument names
+    end
+  end
+
+  class ArgumentResolver
+    class << self; attr_accessor :resolver; end
+
+    # By default resolves argument values from request parameters
+    @resolver = lambda do |object, argument_name|
+      return object.send(:params)[argument_name.to_s]
+    end
+
+    def self.resolve(object, argument_name)
+      return @resolver.call(object, argument_name)
+    end
+  end
+
+  class UnknownArgumentError < ArgumentError
+
+    def initialize(class_name, method_name, key)
+      super("#{class_name}##{method_name}' does not include an argument named: #{key}" )
+    end
+
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods) # Adding class methods
+    base.send(:include, InstanceMethods)
+  end
+
+  module ClassMethods
+
+    # Used to annotate methods that should have their argument values automatically resolved
+    #
+    #   argible
+    #   def annotated_method(foo, bar)
+    #     ...
+    #   end
+    #
+    def argible(options = {})
+      @method_definition = MethodDefinition.new(options)
+    end
+
+    # Callback to alert Argible of the method being annotated
+    def method_added(method_name)
+
+      unless @method_definition.nil?
+        @method_definition.name = method_name
+        @method_definition.arguments = get_arguments(method_name)
+
+        # Add class instance variable 'argible_methods' if it does not already exist
+        unless self.respond_to?(:argible_methods)
+          class << self; attr_accessor :argible_methods; end
+          self.instance_variable_set(:@argible_methods, Hash.new)
+        end
+
+        self.argible_methods[method_name] = @method_definition
+
+        @method_definition = nil # clearing to prevent infinite loop
+
+        build_alias_method(method_name)
+      end
+    end
+
+    private
+
+    def get_arguments(method_name)
+      ParseTree.new.parse_tree_for_method(self, method_name)[2][1][1][1..-1]
+    end
+
+    # 1. Determine all arguments
+    # 1. Resolve argument values
+    # 2. Process arguments
+    #    A. method to call on value
+    #    B. pass to Proc
+    #    B. pass to Method
+    #
+    # argible(
+    #   :one => :to_i,                          # call method on argument value
+    #   :two => lambda{ |value| return value }, # Proc to run
+    #   :three => method(:alt_name)             # method to call
+    #)
+    def build_alias_method(method_name)
+      original_method = "__argible_#{method_name}".to_sym
+      alias_method(original_method, method_name)
+
+      # define the proxying method
+      define_method(method_name) do
+        method_definition = self.class.argible_methods[method_name]
+        arguments = {}
+
+        method_definition.arguments.collect do |name|
+          arguments[name] = ArgumentResolver.resolve(self, name)
+        end
+
+        process_argible_options(method_definition, arguments)
+
+        self.send(original_method, *arguments.values)
+      end
+    end
+
+  end
+
+  module InstanceMethods
+
+    private
+
+    # responsible for resolving argument value
+    def resolve_argument(name)
+      return params[name.to_s]
+    end
+
+    def process_argible_options(method_definition, arguments)
+      method_definition.options.each do |key, value|
+        unless arguments.include?(key) # only process key if it exists in the method argument list
+          raise UnknownArgumentError.new(self.class, method_definition.name, key)
+        end
+
+        if value.is_a?(Method) or value.is_a?(Proc)
+          arguments[key] = value.call(arguments[key])
+        elsif value.is_a?(Symbol)
+          arguments[key] = arguments[key].send(value)
+        end
+      end
+    end
+
+  end
+
+end

data/spec/argible_spec.rb

@@ -0,0 +1,140 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe ::Argible, " method added callback" do
+
+  class FooBar
+    include ::Argible
+
+    argible
+    def alpha(beta, gamma); end
+
+    argible(:junk => :to_i)
+    def no_arg_method; end
+
+    def not_annotated; end
+  end
+
+  it "should only cache argible annotated methods" do
+    FooBar.argible_methods.should include(:alpha)
+    FooBar.argible_methods.should_not include(:not_annotated)
+  end
+
+  it "should be able to determine each argument by name (Symbol)" do
+    arguments = FooBar.argible_methods[:alpha].arguments
+    arguments[0].should == :beta
+    arguments[1].should == :gamma
+  end
+
+  it "should create alias for annotated methods" do
+    FooBar.instance_methods.should include('__argible_alpha')
+    FooBar.instance_methods.should_not include('__argible_not_annotated')
+  end
+
+  it "should raise error when argible options reference an unknown argument" do
+    FooBar.argible_methods[:no_arg_method].arguments.length.should == 0
+
+    begin
+      FooBar.new.no_arg_method
+      fail("UnknownArgumentError should have been raised")
+    rescue ::Argible::UnknownArgumentError => e
+      e.message.should == "FooBar#no_arg_method' does not include an argument named: junk" 
+    end
+  end
+
+  it "should add argible_methods instance variable to child classes" do
+    class ArgibleizedParent
+      include ::Argible
+    end
+
+    class Child < ArgibleizedParent
+
+      argible
+      def method_one; end
+    end
+
+    Child.should respond_to(:argible_methods)
+  end
+
+end
+
+describe ::Argible, "proxied methods" do
+
+  it "should resolve argument name from params hash (RoR)" do
+    class Zoo # Class under test
+      include ::Argible
+
+      attr_reader :animals, :price
+
+      def initialize; @animals = []; end
+
+      argible
+      def add(animal)
+        @animals << animal
+      end
+    end
+
+    zoo = Zoo.new
+    zoo.should_receive(:params).and_return({'animal' => 'Grizzly Bear'})
+
+    zoo.add # calling the argible-ized method
+    zoo.animals.should include('Grizzly Bear')
+  end
+
+  it "should be able to delegate to referenced Method" do
+
+    class Person
+      include ::Argible
+
+      attr_reader :dob
+
+      argible(:date => Date.method(:parse))
+      def birth_date(date)
+        @dob = date
+      end
+
+    end
+
+    person = Person.new
+    person.should_receive(:params).and_return('date' => "1-2-2007")
+    person.birth_date
+
+    person.dob.should == Date.civil(2007, 2, 1)
+  end
+
+  it "should be able to delegate to Proc (lambda)" do
+
+    class FooBar
+
+      argible(:number => lambda{|v| v.to_i * 10})
+      def calculate(number)
+        return number
+      end
+    end
+
+    foobar = FooBar.new
+    foobar.should_receive(:params).and_return('number' => "99")
+    foobar.calculate.should == 990
+  end
+
+  it "should be able to call method directly on resolved value" do
+    class FooBar
+
+      argible(:value => :to_i)
+      def echo(value)
+        return value
+      end
+    end
+
+    foobar = FooBar.new
+    foobar.should_receive(:params).and_return('value' => "1985")
+    foobar.echo.should == 1985
+  end
+
+end
+
+
+# TODO might look at supporting arguments:
+#   :four => :@four,                        # set instance variable
+
+# TODO might want to handle argument default values (i.e.  foo(bar=99, baz={})   )
+

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'rubygems'
+require 'spec'
+
+require File.dirname(__FILE__) + '/../lib/argible'

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.4
+specification_version: 1
+name: argible
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2007-08-20 00:00:00 -05:00
+summary: automatically resolves method argument values
+require_paths: 
+- lib
+email: argible-developer@rubyforge.org
+homepage: http://argible.rubyforge.org
+rubyforge_project: argible
+description: 
+autorequire: argible
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Michael Ward
+files: 
+- lib/argible.rb
+- spec/argible_spec.rb
+- spec/spec_helper.rb
+- init.rb
+- README
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ParseTree
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.0.0
+    version: