ruby_traverser 0.1.1 → 0.2.0

data/README.markdown

@@ -1,273 +1,47 @@
-# Ruby traverser ##
+# Ruby code Query and Manipulation language ##
 
-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`, a library for generating a model from ruby source code. `ripper2ruby` leverages `ripper` which comes with ruby 1.9. 
+This Ruby DSL enables querying, traversing and manipulating Ruby code using a nice Rubish DSL.
+
+1. First parsing the ruby code into an object graph using `ripper2ruby`
+2. Query the graph to find the code constructs of interest using the Query API
+3. Manipulate the code constructs using the Manipulation API
+
+This project is a DSL layer on top of `ripper2ruby` which again is on top of `ripper` which comes with ruby 1.9. 
+Ruby 1.9 is therefore a requirement! 
 
 See the unit tests in the test directory for examples of use.
 
+See the [Wiki](http://wiki.github.com/kristianmandrup/ruby_traverser_dsl "Wiki") for more details.
+
 ## Requirements ##
 * Ruby 1.9
 * ripper2ruby >= 0.0.2 
 
-## 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.
-
-## Example use of Mutation API ##
-
-Source BEFORE mutations:
-<pre>
-class Monty < Abc::Blip  
-end
-</pre>
-
-<pre>
-    src = %q{  class Monty < Abc::Blip 
-  end}
-    
-    def_src = %q{
-def my_fun
-end}
-
-    def_code = Ripper::RubyBuilder.build(def_src)    
-    code = Ripper::RubyBuilder.build(src)
-
-    # append code examples                  
-    code.inside_class('Monty', :superclass => 'Abc::Blip') do |b|
-      assert_equal Ruby::Class, b.class                                  
-      gem_abc = b.append_code("gem 'abc'")
-      blip = b.append_code("blip")
-      gem_123 = gem_abc.append_code("gem '123'")      
-      gem_123.append_comment("hello")      
-      my_def = b.append_code(def_src)      
-      
-      b.prepend_code("gem '789'")
-      puts b.to_ruby
-    end
-</pre>
+## Ruby code Query API ##
 
-Source AFTER mutations:
-<pre>
-class Monty < Abc::Blip  
-  gem '789'  
-  gem 'abc'  
-  gem '123'  
-  blip  
+See [Query API](http://wiki.github.com/kristianmandrup/ruby_traverser_dsl/finder-api "Query API")
 
-  def my_fun
-  end 
-end
-</pre>  
+* find(type, name, options, &block)
+* inside (alias for find which requires a block argument)
 
+The following symbols are supported `[:module, :class, :variable, :assignment, :call, :block, :def]`
 
-## Replace example ##
+## Manipulation API ##
 
-Source BEFORE mutations:
-<pre>
-group :test do
-  gem 'ripper', :src 
-  my_var = 2  
-end  
-</pre>
+See [Manipulation API](http://wiki.github.com/kristianmandrup/ruby_traverser_dsl/manipulation-api "Manipulation API")
 
-<pre>
-    src = %q{                 
-group :test do
-  gem 'ripper', :src 
-  my_var = 2  
-end  
-    }
+The insert and update API support blocks and always returns the updated or inserted node
 
-    code = Ripper::RubyBuilder.build(src) 
-    # replace examples                                      
-    code.inside_block('group', :args => [:test]) do |b|
-      call_node = b.find_call('gem', :args => ['ripper'])
-      assert_equal Ruby::Call, call_node.class
-      call_node.replace(:arg => :src , :replace_code => "{:src => 'unknown'}")
-      call_node.replace(:value => "3")            
-      puts b.to_ruby
-    end       
-  end  
-</pre>
+### Insert ##
+* insert(position, code, &block)
 
-Source AFTER mutations:
-<pre>
-group :test do
-  gem 'ripper', {:src => 'unknown'} 
-  my_var = 3
-end  
-</pre>  
+### Update ##
+* update(:select, :with, &block)
+* update(:select, :with_code, &block)
+* update(:value, &block)
 
-Note: The mutation API code was developed quickly in a test-driven fashion, but is in need of a major refactoring overhaul sometime soon...
+### Delete ##
+* delete
 
 ## Note on Patches/Pull Requests ##
  

data/TODO.txt

@@ -0,0 +1,12 @@
+find
+find :after
+find :before
+
+insert :after, ...
+insert :before, ...
+
+update :select => {...}, :with => {...}
+update :select => {...}, :with_code => 'code'
+
+delete
+delete :select => {...}

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/config/api.rb

@@ -0,0 +1,11 @@
+require 'query/api'
+require 'manipulation/api'
+require 'config/mixin'
+
+module Ruby
+  class Node
+    include RubyCodeAPI::Query
+    include RubyCodeAPI::Manipulation 
+    include RubyCodeAPI::Misc    
+  end
+end

data/lib/config/has_ext.rb

@@ -0,0 +1,44 @@
+module Ruby
+  class Node
+    module Extension
+      module Has      
+        def has_const?(value)
+          if respond_to?(:const)
+            if namespace?(value)
+              name = value.split('::').last
+              return self.const.identifier.token == name
+            end
+          end
+          false
+        end
+
+        def has_block?
+          respond_to? :block
+        end      
+
+        def has_namespace?(value)
+          if respond_to?(:namespace)
+            return self.namespace.identifier.token == value
+          end
+          false
+        end
+
+        def has_identifier?(value)
+          if respond_to?(:identifier)
+            id = self.identifier
+
+            if namespace?(value)
+              return id.token.to_s == value.to_s if id.respond_to?(:token)
+              if id.respond_to?(:identifier)
+                name = value.split('::').last
+                return id.identifier.token == name
+              end
+            end
+          else
+            has_const?(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/{traversal → config}/misc.rb

@@ -1,6 +1,6 @@
 module Ruby
   class Node
-    module Traversal
+    module Extension
       module Misc
         def args?(value, with_block = nil) 
           found = 0        
@@ -21,11 +21,11 @@ module Ruby
         def argument_count(args)
           args.reject{|arg| !valid_arg?(arg)}.size
         end
-        
+    
         def valid_arg?(arg)
           arg && arg != {} 
         end
-        
+    
         def has_a_block?(with_block)
           with_block && self.respond_to?(:block)
         end                                
@@ -148,5 +148,5 @@ module Ruby
         end
       end
     end
-  end        
+  end
 end

data/lib/config/mixin.rb

@@ -0,0 +1,15 @@
+require 'config/module'
+require 'config/misc'
+require 'config/has_ext'
+require 'config/patch'
+
+module Ruby
+  class Node               
+    include Extension::Patch    
+    include Extension::Module
+    include Extension::Misc
+    include Extension::Has
+  end    
+end   
+
+     

data/lib/{traversal → config}/module.rb

@@ -1,6 +1,6 @@
 module Ruby
   class Node
-    module Traversal
+    module Extension
       module Module
         def namespace?(full_name)
           if full_name.split('::').size > 1

data/lib/{traversal → config}/patch.rb

@@ -1,6 +1,6 @@
 module Ruby
   class Node
-    module Traversal
+    module Extension
       module Patch
         def select(*args, &block)
           result = []
@@ -35,7 +35,7 @@ module Ruby
           end
           res
         end
-        
+    
         def check_pair(type, value)
           res = case type
           when :is_a
@@ -76,8 +76,8 @@ module Ruby
           # puts "check pair type:#{type}, value:#{value} => #{res}, self: #{self.inspect}" if self.class == Ruby::Variable 
           res
         end 
-        
+    
       end # Patch
     end
   end
-end
+end