argible 0.1.0 → 0.1.1

data/README

@@ -1,4 +1,4 @@
-= ARGIBLE
+= ARGIBLE: A dynamic method argument resolver for Ruby
 
 by {Michael Ward}[http://m2ward.blogspot.com]
 
@@ -29,39 +29,51 @@ Have a look at the following Controller:
   class FoobarController < ApplicationController
 
     argible
-    def action_one(alpha)
+    def action_one(alpha, beta)
       ...
     end
 
-    argible(:date => Date.method(:parse))
-    def action_two(date)
+    argible(:date => Date.method(:parse)) # process argument value for 'date' by passing it to Date#parse
+    def action_two(alpha, date)
       ...
     end
 
-    argible(:date => lambda {|v| Date.parse(v) } )
+    argible(:date => lambda {|v| Date.parse(v) } ) # process argument value for 'date' by passing it to the Proc
     def action_three(date)
       ...
     end
 
-    argible(:value => :to_i)
-    def action_four(value)
+    argible(:count => :to_i) # invoke the :to_i method on the resolved value for 'count'
+    def action_four(count)
+      ...
+    end
+
+    argible(:the_name => :@first_name) # resolves the value for 'the_name' and sets it to the instance variable @first_name
+    def action_five
+      p @first_name # this instance variable has been set automatically by Argible
       ...
     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 first method, *action_one*, is annotated with the method +argible+.  When this action method is executed
+Argible will intercept the call and look up the request parameter value associated with the argument names +alpha+ and
++beta+.  Then the action_one method will be called with these resolved values.
+
+The second action, *action_two*, provides an example of how more complex processing can occur on argument
+values.  As in the first example the both arguments, +alpha+ and +date+, will be resolved against the request parameters.
+However the resolved value for +date+ will then be passed to the <tt>Date#parse</tt> method.  The returned value from
+<tt>Date#parse</tt> method call will then be used as the argument value for +date+ when +action_two+ is called. **NOTE:** any
+method can be used, Date#parse is simply used as an example.
 
-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 third example action, *action_three*, provides an example of using a Proc (lambda) as alternative to a named method.
 
-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.  Assume request parameter hash was <tt>{'count' => "1985"}</tt> then the Integer value
++1985+ would be passed as the argument value for the argument named <tt>'count'</tt>.
 
-The fourth example action *action_four* illustrates how you can call methods directly on the String value returned from
-the request parameter
+The final example action, *action_five*, demonstrates how you can automatically set the value of an instance variable
+without requiring a method argument of the same name.  This example works because <tt>:my_name</tt> points to a symbol
+begining with a '@' character.  Without this '@' on the right hand side Argible would raise a Argible::UnknownArgumentError.
 
 
 == LICENSE:

data/lib/argible.rb

@@ -1,41 +1,8 @@
 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
+Dir[File.join(File.dirname(__FILE__), 'argible/**/*.rb')].sort.each { |lib| require lib }
 
-  class UnknownArgumentError < ArgumentError
-
-    def initialize(class_name, method_name, key)
-      super("#{class_name}##{method_name}' does not include an argument named: #{key}" )
-    end
-
-  end
+module Argible
 
   def self.included(base)
     base.extend(ClassMethods) # Adding class methods
@@ -51,11 +18,20 @@ module Argible
     #     ...
     #   end
     #
+    # The +options+ Hash passed in can define custom processing to occur on a per argument basis.  For example:
+    #
+    #   argible(
+    #     :one => :to_i,                          # call method 'to_i' on the argument value
+    #     :two => lambda{ |value| return value }, # defines a Proc to run (resolved argumnet value passed to Proc)
+    #     :three => method(:meth_name),           # method to call (resolved argumnet value passed to Method)
+    #     :four => :@four                         # argument value is set to the instance variable of name (i.e. @four)
+    #   )
+    #
     def argible(options = {})
       @method_definition = MethodDefinition.new(options)
     end
 
-    # Callback to alert Argible of the method being annotated
+    # This callback is used by Argible to determine which methods have been annotated with the argible() method.
     def method_added(method_name)
 
       unless @method_definition.nil?
@@ -82,18 +58,6 @@ module Argible
       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)
@@ -119,21 +83,20 @@ module Argible
 
     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)
+          if(value.is_a?(Symbol) and value.to_s =~ /^@/)
+            self.instance_variable_set(value, ArgumentResolver.resolve(self, key)) # set instance variable
+          else
+            raise UnknownArgumentError.new(self.class, method_definition.name, key)
+          end
+        else
+          if value.is_a?(Method) or value.is_a?(Proc)
+            arguments[key] = value.call(arguments[key])
+          elsif value.is_a?(Symbol) # method to be invoked on value
+            arguments[key] = arguments[key].send(value)
+          end
         end
       end
     end

data/lib/argible/argument_resolver.rb

@@ -0,0 +1,24 @@
+module Argible
+
+  # This class defines the method/proc that will be called to resolve an arguments value.  By default this
+  # implementation will resolve an arguments value through RoR's request parameters.  It is possible to plug-in an
+  # alternate resolver implementation like so (in the example all arguments values will resolve to the value 'foobar'):
+  #
+  #   ::Argible::ArgumentResolver.resolver = lambda do |instance, argument_name|
+  #     return "foobar"
+  #   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
+  
+end

data/lib/argible/method_definition.rb

@@ -0,0 +1,17 @@
+module Argible
+
+  # defines information about the method being annotated
+  class MethodDefinition # :nodoc:
+    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
+
+end

data/lib/argible/unknown_argument_error.rb

@@ -0,0 +1,17 @@
+module Argible
+
+  # As the name implies, this error occurs when an argible annotated method references an argument name that does NOT
+  # exist in the method signature.
+  #
+  #   argible(:junk => :to_i)
+  #   def my_method(arg1, arg2); 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
+
+end

data/lib/argible/version.rb

@@ -0,0 +1,8 @@
+module Argible # :nodoc:
+  module VERSION # :nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 1
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/spec/argible_spec.rb

@@ -130,11 +130,24 @@ describe ::Argible, "proxied methods" do
     foobar.echo.should == 1985
   end
 
-end
+  it "should be able to directly set instance variable (even without associated argument name)" do
+
+    class FooBar
+
+      argible(:name => :@name)
+      def change_name
+        return @name
+      end
+    end
 
+    foobar = FooBar.new
+    foobar.should_receive(:params).and_return('name' => "Regan")
 
-# TODO might look at supporting arguments:
-#   :four => :@four,                        # set instance variable
+    foobar.change_name
+    foobar.instance_variable_get(:@name).should == "Regan" # instance variable set correctly
+  end
+
+end
 
 # TODO might want to handle argument default values (i.e.  foo(bar=99, baz={})   )
 

metadata

@@ -3,8 +3,8 @@ 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
+  version: 0.1.1
+date: 2007-08-22 00:00:00 -05:00
 summary: automatically resolves method argument values
 require_paths: 
 - lib
@@ -29,6 +29,10 @@ post_install_message:
 authors: 
 - Michael Ward
 files: 
+- lib/argible/argument_resolver.rb
+- lib/argible/method_definition.rb
+- lib/argible/unknown_argument_error.rb
+- lib/argible/version.rb
 - lib/argible.rb
 - spec/argible_spec.rb
 - spec/spec_helper.rb