parameters_extra 0.2.0

data/.gitignore

@@ -0,0 +1,2 @@
+pkg
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in optitron.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    parameters_extra (0.2.0)
+      ruby2ruby (~> 1.2.4)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0.4)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    callsite (0.0.4)
+    minitest (2.0.2)
+    phocus (1.1)
+    rake (0.8.7)
+    ruby2ruby (1.2.5)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    ruby_parser (2.0.5)
+      sexp_processor (~> 3.0)
+    sexp_processor (3.0.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  callsite (~> 0.0.4)
+  minitest
+  parameters_extra!
+  phocus
+  rake
+  ruby2ruby (~> 1.2.4)
+  ruby_parser (~> 2.0)
+  sexp_processor (~> 3.0.4)

data/README.markdown

@@ -0,0 +1,45 @@
+# ParametersExtra
+
+## Purpose
+
+You've got a method, but want to know more about the arguments? `#arity` and `#parameters` (if available) are useful,
+but not nearly enough. You need something better. Like, the default arguments. *ParametersExtra* makes this simple. It operates
+on a source file to supply the more details argument information by parsing the code itself.
+
+## Usage
+
+Pretend you have a file `your_ruby_file.rb`:
+
+    class MyClass
+      def initialize
+        @default_value = 'hello'
+      end
+
+      def something(one, two = 'two', three = @default_value, *more, &block)
+      end
+    end
+
+To look at the arguments to something and you're in Ruby 1.9 (please see https://twitter.com/igrigorik/status/19461463110320128), just require it normally:
+
+    require 'your_ruby_file'
+    MyClass.instance_method(:something).args
+
+Otherwise, do the following:
+    
+    ParametersExtra.load('your_ruby_file') # <-- this also requires the file
+    MyClass.instance_method(:something).args
+    
+This will return an `ArgList` object. You can then look at the names & types.
+
+    MyClass.instance_method(:something).args.names
+    # => [:one, :two, :three, :more, :block]
+
+    MyClass.instance_method(:something).args.types
+    # => [:required, :optional, :optional, :splat, :block]
+    
+If you want to get the value of a default argument, you'll need a context in which to evaluate it, namely,
+an instance of the class from which the method derives.
+
+    obj = MyClass.new
+    obj.method(:something).args.last.default_value
+    # => 'hello'

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'bundler'
+
+desc "Run tests"
+task :test do
+  $: << '.'
+  $: << 'lib'
+  require 'parameters_extra'
+  require 'test/helper'
+  Dir['test/**/test_*.rb'].each { |test| require test }
+end
+
+require 'rake/rdoctask'
+desc "Generate documentation"
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'rdoc'
+end
+
+Bundler::GemHelper.install_tasks

data/lib/parameters_extra.rb

@@ -0,0 +1,52 @@
+require 'set'
+require 'ruby2ruby'
+require 'ruby_parser'
+require 'sexp_processor'
+
+require 'parameters_extra/method_mixins'
+require 'parameters_extra/args'
+require 'parameters_extra/processor'
+require 'parameters_extra/version'
+require 'parameters_extra/method_registry'
+
+module ParametersExtra
+  ClassMethodRegistry = Hash.new{|h, k| h[k] = MethodRegistry.new}
+  FileRegistry = Set.new
+
+  def self.load(file, require_file = true)
+    require file if require_file
+    register file
+  end
+
+  def self.parameters_for_method(method)
+    k = class_key(method.owner)
+    ClassMethodRegistry[k][method.name.to_sym] if ClassMethodRegistry.key?(k)
+  end
+
+  def self.register(file)
+    file = expand_path(file)
+    unless FileRegistry.include?(file)
+      FileRegistry << file
+      parse(file).each { |cls, methods| ClassMethodRegistry[cls].add_methods!(methods) }
+    end
+  end
+
+  def self.parse(file, require_file = true)
+    parser = RubyParser.new
+    sexp = parser.process(File.read(expand_path(file)))
+    parameters_extra = Processor.new
+    parameters_extra.process(sexp)
+    parameters_extra.methods
+  end
+
+  def self.class_key(cls)
+    nesting = cls.class_eval("Module.nesting")
+    nesting.pop
+    nesting.join('::')
+  end
+
+  def self.expand_path(file)
+    file = File.expand_path(file)
+    File.exist?(file) ? file : "#{file}.rb"
+  end
+end

data/lib/parameters_extra/args.rb

@@ -0,0 +1,66 @@
+module ParametersExtra
+  class Args < Array
+    class Arg
+    
+      attr_accessor :arg_list
+      attr_reader :name, :type
+    
+      def initialize(name, type, default = nil)
+        @name, @type, @default = name, type, default
+      end
+
+      def required?
+        @type == :required
+      end
+
+      def optional?
+        @type == :optional
+      end
+
+      def splat?
+        @type == :splat
+      end
+
+      def default?
+        !@default.nil?
+      end
+
+      def default_value(*args)
+        return nil if @default.nil?
+        receiver ||= arg_list.owning_method.receiver
+        raise "You must specify a receiver for the defaul value" if receiver.nil?
+        raise "You must evaluate defaults in the context of a matching class. #{receiver.class.name} is not a #{arg_list.cls.name}." unless receiver.is_a?(arg_list.cls)
+        receiver.instance_eval(@default)
+      end
+    end
+
+    attr_accessor :owning_method
+
+    def initialize(cls)
+      @cls = cls
+    end
+
+    def cls
+      @cls.inject(Module) {|c, m| c.const_get(m)}
+    end
+
+    def clone
+      o = super
+      o.each {|arg| arg.arg_list = o}
+      o
+    end
+
+    def required_size
+      inject(0) {|count, arg| count += arg.required? ? 1 : 0}
+    end
+    alias_method :required_count, :required_size
+
+    def names
+      map(&:name)
+    end
+
+    def types
+      map(&:type)
+    end
+  end
+end

data/lib/parameters_extra/method_mixins.rb

@@ -0,0 +1,11 @@
+module MethodMixin
+  def parameters_extra
+    ParametersExtra.register(source_location[0]) if respond_to?(:source_location)
+    args = ParametersExtra.parameters_for_method(self).clone
+    args.owning_method = self
+    args
+  end
+end
+
+Method.send(:include, MethodMixin)
+UnboundMethod.send(:include, MethodMixin)

data/lib/parameters_extra/method_registry.rb

@@ -0,0 +1,19 @@
+module ParametersExtra
+  class MethodRegistry < Hash
+    attr_reader :method_names
+
+    def initialize
+      super
+      @method_names = []
+    end
+
+    def add_methods!(methods)
+      methods.each do |(method_name, args)|
+        unless key?(method_name)
+          self[method_name] = args
+          method_names << method_name
+        end
+      end
+    end
+  end
+end

data/lib/parameters_extra/processor.rb

@@ -0,0 +1,88 @@
+module ParametersExtra
+  class Processor < SexpProcessor
+
+    attr_reader :methods
+
+    def initialize
+      @methods = Hash.new{|h,k| h[k] = []}
+      @current_class = []
+      super()
+    end
+
+    def process_module(exp)
+      exp.shift
+      @current_class << exp.first.to_sym
+      process(exp)
+      @current_class.pop
+      exp.clear
+      exp
+    end
+
+    def process_class(exp)
+      exp.shift
+      current_class_size = @current_class.size
+      case exp.first
+      when Symbol
+        @current_class << exp.first.to_sym
+        process(exp)
+      else
+        if exp.first.first == :colon2
+          exp.first.shift
+          class_exp = exp.shift
+          class_exp[0, class_exp.size - 1].each do |const|
+            @current_class << const.last
+          end
+          @current_class << class_exp.last
+        else
+          raise
+        end
+        exp.shift
+        process(exp.first)
+      end
+      @current_class.slice!(current_class_size, @current_class.size)
+      exp.clear
+      exp
+    end
+
+    def process_defn(exp)
+      exp.shift
+      @current_method = exp.shift
+      @ruby2ruby = Ruby2Ruby.new
+      process_args(exp.shift)
+      exp.shift
+      exp
+    end
+
+    def process_args(exp)
+      exp.shift
+      arg_list = Args.new(@current_class.clone)
+      while !exp.empty?
+        t = exp.shift
+        case t
+        when Symbol
+          arg_list << case t.to_s[0]
+          when ?* then Args::Arg.new(t.to_s[1, t.to_s.size].to_sym, :splat)
+          when ?& then Args::Arg.new(t.to_s[1, t.to_s.size].to_sym, :block)
+          else         Args::Arg.new(t, :required)
+          end
+        when Sexp
+          case t.shift
+          when :block
+            while lasgn = t.shift
+              lasgn.shift
+              name = lasgn.shift
+              new_arg = Args::Arg.new(name, :optional, @ruby2ruby.process(lasgn.last))
+              arg_list.each_with_index{|arg, idx| arg_list[idx] = new_arg if arg.name == name}
+            end
+          end
+        end
+      end
+      @methods[current_classname] << [@current_method, arg_list]
+      exp
+    end
+
+    def current_classname
+      @current_class.map{|c| c.to_s}.join('::')
+    end
+  end
+end

data/lib/parameters_extra/version.rb

@@ -0,0 +1,3 @@
+module ParametersExtra
+  VERSION = '0.2.0'
+end

data/parameters_extra.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "parameters_extra/version"
+
+Gem::Specification.new do |s|
+  s.name        = "parameters_extra"
+  s.version     = ParametersExtra::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Joshua Hull"]
+  s.email       = ["joshbuddy@gmail.com"]
+  s.homepage    = "https://github.com/joshbuddy/parameters_extra"
+  s.summary     = "Get back more detailed information about the parameters for a method"
+  s.description = "Get back more detailed information about the parameters for a method."
+
+  s.rubyforge_project = "parameters_extra"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "ruby_parser", "~> 2.0"
+  s.add_dependency "ruby2ruby", "~> 1.2.4"
+  s.add_dependency "sexp_processor", "~> 3.0.4"
+  s.add_development_dependency "callsite", "~> 0.0.4"
+  s.add_development_dependency "bundler", "~> 1.0.0"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "phocus"
+  s.add_development_dependency "minitest"
+end

data/test/fixtures/1.rb

@@ -0,0 +1,21 @@
+class One
+  attr_accessor :two_method
+
+  def no_args
+  end
+
+  def one_args(one)
+  end
+  
+  def two_args(one, two)
+  end
+
+  def splat_args(one, two, *three)
+  end
+
+  def default_args(one, two = 'two')
+  end
+
+  def default_args_with_dependant_value(one, two = two_method)
+  end
+end

data/test/fixtures/2.rb

@@ -0,0 +1,18 @@
+class Two
+  def one(hi, there)
+  end
+end
+
+module TwoModule
+  def mod(from, mod)
+  end
+end
+
+class TwoSubclass < Two
+  include TwoModule
+  def two(one, more)
+  end
+
+  def one(hi, there, more)
+  end
+end

data/test/fixtures/3.rb

@@ -0,0 +1,4 @@
+class MyClass
+  def block(arg, arg2 = 1, *splat, &blk)
+  end
+end

data/test/fixtures/4.rb

@@ -0,0 +1,4 @@
+class Autoloaded
+  def some_method
+  end
+end

data/test/fixtures/5.rb

@@ -0,0 +1,17 @@
+class Top
+  def one
+  end
+  
+  class Middle
+    def two
+    end
+
+    def one(two)
+    end
+    
+    class End
+      def two(three)
+      end
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,4 @@
+require 'minitest/autorun'
+require 'phocus'
+require 'callsite'
+Callsite.activate_string_methods

data/test/test_autoload.rb

@@ -0,0 +1,11 @@
+if Method.instance_method(:source_location)
+  class TestAutoload < MiniTest::Unit::TestCase
+    def setup
+      require ~'fixtures/4'
+    end
+
+    def test_arg_counts
+      assert_equal 0, Autoloaded.instance_method(:some_method).parameters_extra.count
+    end
+  end
+end rescue nil

data/test/test_block.rb

@@ -0,0 +1,9 @@
+class TestBlock < MiniTest::Unit::TestCase
+  def setup
+    ParametersExtra.load(~'fixtures/3')
+  end
+
+  def test_block
+    assert_equal [:required, :optional, :splat, :block], MyClass.instance_method(:block).parameters_extra.types
+  end
+end

data/test/test_bound_method.rb

@@ -0,0 +1,22 @@
+class TestBoundMethod < MiniTest::Unit::TestCase
+  def setup
+    ParametersExtra.load(~'fixtures/1')
+  end
+
+  def test_default_args
+    one = One.new
+    one.two_method = 'happy times'
+    two = One.new
+    two.two_method = 'more happy times'
+    assert_equal 'happy times',      one.method(:default_args_with_dependant_value).parameters_extra.last.default_value
+    assert_equal 'more happy times', two.method(:default_args_with_dependant_value).parameters_extra.last.default_value
+  end
+
+  def test_binding_method
+    method = One.instance_method(:default_args_with_dependant_value)
+    one = One.new
+    one.two_method = 'happy times'
+    assert_equal 'happy times',      method.bind(one).parameters_extra.last.default_value
+  end
+
+end

data/test/test_nested.rb

@@ -0,0 +1,12 @@
+class TestNested < MiniTest::Unit::TestCase
+  def setup
+    ParametersExtra.load(~'fixtures/5')
+  end
+
+  def test_nested
+    assert_equal 0, Top.instance_method(:one).parameters_extra.count
+    assert_equal 1, Top::Middle.instance_method(:one).parameters_extra.count
+    assert_equal 0, Top::Middle.instance_method(:two).parameters_extra.count
+    assert_equal 1, Top::Middle::End.instance_method(:two).parameters_extra.count
+  end
+end

data/test/test_simple.rb

@@ -0,0 +1,33 @@
+class TestSimple < MiniTest::Unit::TestCase
+  def setup
+    ParametersExtra.load(~'fixtures/1')
+  end
+
+  def test_arg_counts
+    assert_equal 0, One.instance_method(:no_args).parameters_extra.count
+    assert_equal 1, One.instance_method(:one_args).parameters_extra.count
+    assert_equal 2, One.instance_method(:two_args).parameters_extra.count
+    assert_equal 3, One.instance_method(:splat_args).parameters_extra.count
+    assert_equal 2, One.instance_method(:splat_args).parameters_extra.required_count
+    assert_equal 2, One.instance_method(:default_args).parameters_extra.count
+    assert_equal 1, One.instance_method(:default_args).parameters_extra.required_count
+    assert_equal 2, One.instance_method(:default_args_with_dependant_value).parameters_extra.count
+    assert_equal 1, One.instance_method(:default_args_with_dependant_value).parameters_extra.required_count
+  end
+
+  def test_arg_types
+    assert_equal [],                                One.instance_method(:no_args).parameters_extra.types
+    assert_equal [:required],                       One.instance_method(:one_args).parameters_extra.types
+    assert_equal [:required, :required],            One.instance_method(:two_args).parameters_extra.types
+    assert_equal [:required, :required, :splat],    One.instance_method(:splat_args).parameters_extra.types
+    assert_equal [:required, :optional],            One.instance_method(:default_args).parameters_extra.types
+    assert_equal [:required, :optional],            One.instance_method(:default_args_with_dependant_value).parameters_extra.types
+  end
+
+  def test_default_args
+    one = One.new
+    one.two_method = 'happy times'
+    assert_equal 'happy times', One.instance_method(:default_args_with_dependant_value).bind(one).parameters_extra.last.default_value
+  end
+
+end

data/test/test_subclass.rb

@@ -0,0 +1,21 @@
+class TestSubclass < MiniTest::Unit::TestCase
+  def setup
+    ParametersExtra.load(~'fixtures/2')
+  end
+
+  def test_normal_visibility
+    assert_equal [:one, :more], TwoSubclass.instance_method(:two).parameters_extra.names
+  end
+
+  def test_subclass_overridding
+    assert_equal [:hi, :there, :more], TwoSubclass.instance_method(:one).parameters_extra.names
+  end
+
+  def test_superclass_visibility
+    assert_equal [:hi, :there], Two.instance_method(:one).parameters_extra.names
+  end
+
+  def test_module_visibility
+    assert_equal [:from, :mod], TwoSubclass.instance_method(:mod).parameters_extra.names
+  end
+end

metadata

@@ -0,0 +1,222 @@
+--- !ruby/object:Gem::Specification 
+name: parameters_extra
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Joshua Hull
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-24 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ruby_parser
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 0
+        version: "2.0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: ruby2ruby
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 2
+        - 4
+        version: 1.2.4
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: sexp_processor
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 3
+        - 0
+        - 4
+        version: 3.0.4
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: callsite
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 0
+        - 0
+        - 4
+        version: 0.0.4
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: phocus
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id008
+description: Get back more detailed information about the parameters for a method.
+email: 
+- joshbuddy@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.markdown
+- Rakefile
+- lib/parameters_extra.rb
+- lib/parameters_extra/args.rb
+- lib/parameters_extra/method_mixins.rb
+- lib/parameters_extra/method_registry.rb
+- lib/parameters_extra/processor.rb
+- lib/parameters_extra/version.rb
+- parameters_extra.gemspec
+- test/fixtures/1.rb
+- test/fixtures/2.rb
+- test/fixtures/3.rb
+- test/fixtures/4.rb
+- test/fixtures/5.rb
+- test/helper.rb
+- test/test_autoload.rb
+- test/test_block.rb
+- test/test_bound_method.rb
+- test/test_nested.rb
+- test/test_simple.rb
+- test/test_subclass.rb
+has_rdoc: true
+homepage: https://github.com/joshbuddy/parameters_extra
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: parameters_extra
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Get back more detailed information about the parameters for a method
+test_files: 
+- test/fixtures/1.rb
+- test/fixtures/2.rb
+- test/fixtures/3.rb
+- test/fixtures/4.rb
+- test/fixtures/5.rb
+- test/helper.rb
+- test/test_autoload.rb
+- test/test_block.rb
+- test/test_bound_method.rb
+- test/test_nested.rb
+- test/test_simple.rb
+- test/test_subclass.rb