ruby_traverser 0.1.0

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 Kristian Mandrup
+
+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.markdown

@@ -0,0 +1,195 @@
+# Ruby traverser ##
+
+A DSL for traversing ruby code as an object model (graph), which lets you find parts of the ruby code of interest.
+The traverser leverages `ripper2ruby`, which leverages `ripper`, which comes with ruby 1.9. Ruby 1.9 is thus required.
+
+See the unit tests in the test directory for examples of use.
+
+## Finders ##
+
+* find_module(name)
+* find_class(name, options = {})
+* find_call(name, options = {})
+* find_block(name, options = {})
+* find_def(name, options = {})
+* find_variable(name, options = {})
+* find_assignment(name, options = {})
+
+## Find module ##
+
+<pre>
+  src = %q{      
+    module Xyz::Xxx::Blip
+      2
+    end    
+  }
+  
+  code = Ripper::RubyBuilder.build(src)          
+  module_node = code.find_module('Xyz::Xxx::Blip') 
+  assert_equal Ruby::Module, module_node.class 
+</pre>
+
+## Find class ##
+
+<pre>
+# class Monty::Python ... end
+clazz_node = code.find_class('Monty::Python')   
+</pre>
+
+Find class inheriting from a certain superclass
+<pre>
+# class Monty < Abc::Blip ... end
+clazz_node = code.find_class('Monty', :superclass => 'Abc::Blip')   
+</pre>
+
+## Find call ##
+                                                               
+<pre>
+# gem 'ripper', :src => 'github' 
+gem_call = code.find_call('gem', :args => ['ripper', {:src => 'github'}])   
+</pre>
+
+
+## Find block ##        
+
+<pre>
+# my_block do ... end
+block_node = code.find_block('my_block')   
+</pre>
+
+<pre>
+# my_block do |v| ... end
+block_node = code.find_block('my_block', :block_params => ['v'])   
+</pre>
+
+<pre>
+# my_block 7, 'a' do ... end
+block_node = code.find_block('my_block', :args => [7, 'a'])   
+</pre>
+                                                 
+<pre>
+# my_block 7, 'a', :k => 32 do |v| ... end
+block_node = code.find_block('my_block', :args => [7, 'a', {:k => 32}], :block_params => ['v'])   
+</pre>
+
+<pre>
+# my_block :a => 7, b => 3 do |v| ... end
+block_node = code.find_block('my_block', :args => [{:a => 7, 'b' => 3}])   
+</pre>     
+
+<pre>                                                                      
+# my_block ['a', 'b'] do |v| ... end  
+block_node = code.find_block('my_block', :args => [{:array =>['a', 'b']}])   
+</pre>
+
+
+## Find variable ##
+
+Source code: 
+<pre>
+  def hello_world(a)
+    my_var
+  end  
+</pre>
+
+Ruby code find DSL:
+<pre>
+code = Ripper::RubyBuilder.build(src)               
+code.inside_def('hello_world', :params => ['a']) do |b|
+  call_node = b.find_variable('my_var')
+  assert_equal Ruby::Variable, call_node.class
+  puts call_node.to_ruby
+end
+</pre>
+
+
+## Find assignment ##
+
+Source code: 
+<pre>
+  def hello_world(a)
+    my_var = 2
+  end    
+</pre>
+
+Ruby code find DSL:
+<pre>
+  code = Ripper::RubyBuilder.build(src)               
+  code.inside_def('hello_world', :params => ['a']) do |b|
+    call_node = b.find_assignment('my_var')
+  end  
+</pre>
+
+## Inside ##
+
+The following finder methods have corresponding `inside_` functions, which support block DSL constructs as shown below.
+
+* inside_module
+* inside_class
+* inside_def
+* inside_block
+
+<pre>
+  # source code
+  src = %q{      
+    gem 'ripper', :src => 'github', :blip => 'blap'       
+    group :test do
+      gem 'ripper', :src => 'github' 
+    end  
+  }
+</pre>
+
+<pre>
+  code = Ripper::RubyBuilder.build(src)              
+  # chaining finders using 'inside__' DSL block constructs  
+  code.inside_block('group', :args => [:test]) do |b|
+    call_node = b.find_call('gem', :args => ['ripper', {:src => 'github'}])
+    assert_equal Ruby::Call, call_node.class
+    puts call_node.to_ruby # output ruby code as string for found node 
+  end    
+</pre>
+
+<pre>  
+  src = %q{    
+    def hello_world(b)
+      3
+    end
+
+    def hello_world(a)
+      gem 'ripper', :src => 'github' 
+    end
+
+  }  
+</pre>    
+
+<pre>     
+  # chaining finders using 'inside__' DSL block constructs
+  code = Ripper::RubyBuilder.build(src)            
+  code.inside_def('hello_world', :params => ['a']) do |b|
+    call_node = b.find_call('gem', :args => ['ripper', {:src => 'github'}])
+    assert_equal Ruby::Call, call_node.class
+    puts call_node.to_ruby # output ruby code as string for found node 
+  end  
+</pre>
+
+## Code Mutation API ##
+
+The API now also supports a wide variety of code mutations using a DSL.
+More information will soon be available here or on the github wiki.
+Check the test/mutate folder for test demonstrating what is currently possible.
+
+Note: The mutation API code was developed in a test-driven fashion, but is in need of a major refactoring overhaul sometime soon...
+
+## 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.
+
+## Copyright ##
+
+Copyright (c) 2010 Kristian Mandrup. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,48 @@
+# require 'rubygems'
+# require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ruby_traverser"
+    gem.summary = %Q{traverse and mutate ruby code using a nice DSL}
+    gem.description = %Q{traverse a ruby code model and optionally mutate it along the way using a nice rubyish DSL}
+    gem.email = "kmandrup@gmail.com"
+    gem.homepage = "http://github.com/kristianmandrup/ruby_trav"
+    gem.authors = ["Kristian Mandrup"]
+    gem.add_development_dependency "rspec", ">= 2.0.0"
+    gem.add_dependency "ripper2ruby", "> 0.0.2"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+    
+    # add more gem options here    
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+# require 'rspec/rake_task'
+# Rspec::Core::RakeTask.new(:spec) do |spec|
+# #  spec.libs << 'lib' << 'spec'
+# #  spec.spec_files = FileList['spec/**/*_spec.rb']
+# end
+# 
+# require 'rspec/rake_task'
+# Rspec::Core::RakeTask.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 = "ruby_trav #{version}"
+#   rdoc.rdoc_files.include('README*')
+#   rdoc.rdoc_files.include('lib/**/*.rb')
+# end

data/VERSION

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

data/lib/mutate/api.rb

@@ -0,0 +1,124 @@
+require 'mutate/replacer'
+
+class String
+  # Returns an indented string, all lines of string will be indented with count of chars
+  def indent(char, count)
+    (char * count) + gsub(/(\n+)/) { $1 + (char * count) }
+  end
+end
+
+
+module RubyAPI
+  module Mutator
+    include Replacer
+    
+    def append_code(code)
+      return append_code_simple(code) if !elemental?
+      obj = object
+      indentation = obj.last_indent  
+      code =  "\n#{code}\n".indent(' ', indentation)
+      ruby_code = Ripper::RubyBuilder.build(code)
+      inject_code = ruby_code.elements[0]
+      obj.get_elements << inject_code
+      inject_code
+    end
+
+    def append_code_simple(code)
+      indentation = position.col
+      code =  "\n#{code}\n".indent(' ', indentation)
+      ruby_code = Ripper::RubyBuilder.build(code)
+      inject_code = ruby_code.elements[0]
+      index = parent.find_index(self)
+      parent.get_elements.insert(index+1, inject_code)
+      inject_code
+    end
+
+    def find_index(obj)
+      get_elements.each_with_index do |elem, i|
+        if elem == obj
+          return i
+        end
+      end        
+    end
+
+    def prepend_code(code)
+      obj = object
+      indentation = obj.first_indent  
+      code =  "\n#{code}\n".indent(' ', indentation)
+      ruby_code = Ripper::RubyBuilder.build(code)
+      inject_code = ruby_code.elements[0]
+      obj.get_elements.insert(0, inject_code)
+      obj
+    end
+
+
+    def append_comment(text)
+      append_code("# #{text}")
+    end      
+
+    def elemental?
+      respond_to?(:body) || respond_to?(:elements)
+    end
+
+    def get_elements
+      case self
+      when Ruby::Class
+        body.elements
+      else
+        elements
+      end
+    end
+
+
+    protected
+
+    def last_indent
+      case self
+      when Ruby::Block, Ruby::Class
+        last_position(get_elements)                           
+      else
+        puts "unknown: #{obj.class}"
+      end
+    end
+
+    def last_position(elements) 
+      last_element = elements.last
+      return position.col 
+      return position.col if simple_pos?
+      return last_element.identifier.position.col if elements && elements.size > 0
+      inside_indent
+    end
+
+    def simple_pos?       
+      [Ruby::Token, Ruby::Variable].include?(last_element.class)
+    end
+
+    def first_indent
+      case self
+      when Ruby::Block, Ruby::Class
+        first_position(get_elements)                           
+      else
+        puts "unknown: #{obj.class}"
+      end
+    end
+
+    def first_position(elements) 
+      first_element = elements.first
+      return position.col if simple_pos?
+      return first_element.identifier.position.col if elements && elements.size > 0
+      inside_indent
+    end
+
+    def object
+      self.respond_to?(:block) ? self.block : self
+    end
+    
+  end
+end
+
+module Ruby
+  class Node
+    include RubyAPI::Mutator
+  end
+end
+                

data/lib/mutate/replacer.rb

@@ -0,0 +1,129 @@
+module PositionReplacer
+  def replace_position_arg(options)
+    pos = position_arg?(options[:arg])
+    self.arguments.elements[pos.to_i].replace_pos_argument(options)      
+  end
+
+  def replace_pos_argument(options)                                    
+    case self.arg
+    when Ruby::String                                    
+      replace_arg_token(options[:replace_arg])
+    end
+  end
+
+  def position_arg?(arg)       
+    return arg[1] if arg && arg[0]  == '#'
+    nil
+  end
+end
+
+module TokenReplacer
+  def replace_arg_token(replacement)
+    self.arg.elements[0].token = replacement         
+  end
+
+  def matching_string_arg?(txt)
+    self.arg.elements[0].token == txt
+  end                    
+end
+
+module HashReplacer
+  def hash_arg?(arg) 
+    case arg
+    when Hash 
+      matching_hash_arg?(arg)
+    when Symbol
+      matching_symbol_arg?(arg)      
+    end
+  end                    
+
+  def replace_hash_arg(options) 
+    src = options[:replace_code]        
+    code = Ripper::RubyBuilder.build(src)
+    code.set_ldelim(self.arg) 
+    self.arg = code
+  end
+
+  def set_ldelim(arg)
+    if arg.respond_to? :elements
+      self.ldelim = arg.elements[0].key.ldelim
+      self.ldelim.token = ''
+    else                  
+      self.ldelim = arg.ldelim
+    end
+  end
+  
+  def matching_hash_arg?(arg)
+    if self.arg.respond_to? :elements
+      if self.arg.elements[0].class == Ruby::Assoc
+        key = self.arg.elements[0].key
+        value = self.arg.elements[0].value
+        arg_key = arg.first[0]
+        arg_value = arg.first[1]
+        return key.identifier.token.to_sym == arg_key && value.elements[0].token == arg_value
+      end
+    end
+    false
+  end
+  
+  def matching_symbol_arg?(arg)
+    if self.arg.respond_to? :elements
+      if self.arg.elements[0].class == Ruby::Assoc
+        return self.arg.elements[0].key.identifier.token.to_sym == arg
+      end
+    else
+      # remove ':' token from symbol      
+      self.arg.ldelim.token = ''
+      return self.arg.identifier.token.to_sym == arg       
+    end
+    false
+  end
+end
+
+module ValueReplacer
+  def replace_value(options)
+    if self.class == Ruby::Assignment 
+      self.right.token = options[:value]
+    end
+  end 
+end
+
+module RubyAPI
+  module Mutator
+    module Replacer
+      include PositionReplacer
+      include TokenReplacer  
+      include HashReplacer
+      include ValueReplacer              
+      
+      # :arg => 'ripper', :replace_arg => 'rapper'
+      def replace(options)                       
+        if options[:value]
+          return replace_value(options) 
+        end
+        
+        if position_arg?(options[:arg])
+          return replace_position_arg(options) 
+        end
+        
+        self.arguments.elements.each_with_index do |elem, i|
+          case elem
+          when Ruby::Arg
+            if elem.hash_arg?(options[:arg])
+              return elem.replace_hash_arg(options) 
+            end
+            elem.replace_argument(options)
+          end
+        end
+      end
+
+      def replace_argument(options)                                    
+        case self.arg
+        when Ruby::String                                    
+          replace_arg_token(options[:replace_arg]) if matching_string_arg?(options[:arg])  
+        end
+      end
+
+    end
+  end
+end

data/lib/rails/api_wrapper.rb

@@ -0,0 +1,23 @@
+module RubyAPI
+  module Rails
+    module Gemfile
+      def inside_group(name, &block)
+        inside_block('group', :args => [:"#{name}"], :extend => RubyAPI::Rails::Gemfile, &block)
+      end
+
+      def add_gem(name) 
+        append_code("gem '#{name}'")
+      end
+
+      def replace_gem(name, replace_name)
+        found = find_gem(name)
+        puts "gem:#{found}"
+        found.replace(:arg => name, :replace_arg => replace_name) if found       
+      end
+
+      def find_gem(name, options = nil)
+        find_call('gem', :args => ["#{name}", options])
+      end
+    end
+  end
+end

data/lib/ruby_traverser.rb

@@ -0,0 +1,4 @@
+require 'ripper2ruby'
+require 'traversal/mixin'
+require 'traversal/api/traversal'
+require 'mutate/api'

data/lib/traversal/api/finders.rb

@@ -0,0 +1,41 @@
+require 'yaml'
+
+module RubyAPI
+  module Finders
+    def find_module(name)
+      get_obj.select(Ruby::Module, :identifier => name).first
+    end
+
+    def find_class(name, options = {})
+      options.merge!(:identifier => name)
+      get_obj.select(Ruby::Class, options).first    
+    end
+
+    def find_variable(name, options = {})
+      options.merge!(:token => name)      
+      get_obj.select(Ruby::Variable, options).first      
+    end
+
+    def find_assignment(name, options = {})
+      options.merge!(:left_token => name)      
+      get_obj.select(Ruby::Assignment, options).first      
+    end    
+
+    def find_call(name, options = {})
+      options.merge!(:identifier => name)      
+      get_obj.select(Ruby::Call, options).first
+    end 
+
+    def find_block(name, options = {})  
+      options.merge!(:identifier => name)
+      options.merge!(:block => true) if !options.has_key?(:block_params)    
+      get_obj.select(Ruby::Call, options).first    
+    end 
+
+
+    def find_def(name, options = {})
+      options.merge!(:identifier => name)
+      get_obj.select(Ruby::Method, options).first
+    end 
+  end
+end  

data/lib/traversal/api/inside.rb

@@ -0,0 +1,36 @@
+module RubyAPI
+  module Inside              
+    def inside_block(name, options = {}, &block) 
+      call_block(find_block(name, options), options, &block)
+    end 
+
+    def inside_module(name, &block)
+      call_block(find_module(name), options, &block)      
+    end
+
+    def inside_class(name, options = {}, &block) 
+      call_block(find_class(name, options), options, &block)
+    end
+
+    def inside_def(name, options = {}, &block)
+      call_block(find_def(name, options), options, &block)
+    end
+    
+    protected
+    
+    def call_block(s, options, &block)
+      # inc_inside_indent
+      s.extend(options[:extend]) if options[:extend] 
+      block.arity < 1 ? s.instance_eval(&block) : block.call(s)      
+    end
+
+    def inside_indent
+      if self.class == Ruby::Class
+        pos = ldelim.position.col
+        return pos
+      end
+      2
+    end
+    
+  end
+end

data/lib/traversal/api/traversal.rb

@@ -0,0 +1,20 @@
+require 'traversal/api/finders'
+require 'traversal/api/inside'
+
+module RubyAPI 
+  include Finders
+  include Inside   
+  
+  protected
+  
+  def get_obj(options = {})
+    return self.block if self.class == Ruby::Method     
+    self
+  end  
+end
+
+module Ruby
+  class Node
+    include RubyAPI
+  end
+end