synvert 0.0.13 → 0.0.14

data/lib/synvert/rewriter/action.rb

@@ -1,17 +1,28 @@
 # encoding: utf-8
 
 module Synvert
+  # Action defines rewriter action, add, replace or remove code.
   class Rewriter::Action
+    # Initialize an action.
+    #
+    # @param instance [Synvert::Rewriter::Instance]
+    # @param code {String] new code to add, replace or remove.
     def initialize(instance, code)
       @instance = instance
       @code = code
       @node = @instance.current_node
     end
 
+    # Line number of the node.
+    #
+    # @return [Integer] line number.
     def line
       @node.loc.expression.line
     end
 
+    # The rewritten source code with proper indent.
+    #
+    # @return [String] rewritten code.
     def rewritten_code
       if rewritten_source.split("\n").length > 1
         "\n\n" + rewritten_source.split("\n").map { |line|
@@ -22,24 +33,41 @@ module Synvert
       end
     end
 
+    # The rewritten source code.
+    #
+    # @return [String] rewritten source code.
     def rewritten_source
       @rewritten_source ||= @node.rewritten_source(@code)
     end
 
+    # Compare actions by begin position.
+    #
+    # @param action [Synvert::Rewriter::Action]
+    # @return [Integer] -1, 0 or 1
     def <=>(action)
       self.begin_pos <=> action.begin_pos
     end
   end
 
+  # ReplaceWithAction to replace code.
   class Rewriter::ReplaceWithAction < Rewriter::Action
+    # Begin position of code to replace.
+    #
+    # @return [Integer] begin position.
     def begin_pos
       @node.loc.expression.begin_pos
     end
 
+    # End position of code to replace.
+    #
+    # @return [Integer] end position.
     def end_pos
       @node.loc.expression.end_pos
     end
 
+    # The rewritten source code with proper indent.
+    #
+    # @return [String] rewritten code.
     def rewritten_code
       if rewritten_source.split("\n").length > 1
         "\n\n" + rewritten_source.split("\n").map { |line|
@@ -52,12 +80,20 @@ module Synvert
 
   private
 
+    # Indent of the node
+    #
+    # @param node [Parser::AST::Node]
+    # @return [String] n times whitesphace
     def indent(node)
       ' ' * node.indent
     end
   end
 
+  # AppendWithAction to append code to the bottom of node body.
   class Rewriter::AppendAction < Rewriter::Action
+    # Begin position to append code.
+    #
+    # @return [Integer] begin position.
     def begin_pos
       if :begin == @node.type
         @node.loc.expression.end_pos
@@ -66,12 +102,19 @@ module Synvert
       end
     end
 
+    # End position, always same to begin position.
+    #
+    # @return [Integer] end position.
     def end_pos
       begin_pos
     end
 
   private
 
+    # Indent of the node.
+    #
+    # @param node [Parser::AST::Node]
+    # @return [String] n times whitesphace
     def indent(node)
       if [:block, :class].include? node.type
         ' ' * (node.indent + 2)
@@ -81,17 +124,27 @@ module Synvert
     end
   end
 
+  # InsertAction to insert code to the top of node body.
   class Rewriter::InsertAction < Rewriter::Action
+    # Begin position to insert code.
+    #
+    # @return [Integer] begin position.
     def begin_pos
       insert_position(@node)
     end
 
+    # End position, always same to begin position.
+    #
+    # @return [Integer] end position.
     def end_pos
       begin_pos
     end
 
   private
 
+    # Insert position.
+    #
+    # @return [Integer] insert position.
     def insert_position(node)
       case node.type
       when :block
@@ -103,6 +156,10 @@ module Synvert
       end
     end
 
+    # Indent of the node.
+    #
+    # @param node [Parser::AST::Node]
+    # @return [String] n times whitesphace
     def indent(node)
       if [:block, :class].include? node.type
         ' ' * (node.indent + 2)
@@ -112,35 +169,54 @@ module Synvert
     end
   end
 
+  # InsertAfterAction to insert code next to the node.
   class Rewriter::InsertAfterAction < Rewriter::Action
+    # Begin position to insert code.
+    #
+    # @return [Integer] begin position.
     def begin_pos
       @node.loc.expression.end_pos
     end
 
+    # End position, always same to begin position.
+    #
+    # @return [Integer] end position.
     def end_pos
       begin_pos
     end
 
   private
 
+    # Indent of the node.
+    #
+    # @param node [Parser::AST::Node]
+    # @return [String] n times whitesphace
     def indent(node)
       ' ' * node.indent
     end
   end
 
+  # RemoveAction to remove code.
   class Rewriter::RemoveAction < Rewriter::Action
     def initialize(instance, code=nil)
       super
     end
 
+    # Begin position of code to replace.
+    #
+    # @return [Integer] begin position.
     def begin_pos
       @node.loc.expression.begin_pos
     end
 
+    # End position of code to replace.
+    #
+    # @return [Integer] end position.
     def end_pos
       @node.loc.expression.end_pos
     end
 
+    # The rewritten code, always empty string.
     def rewritten_code
       ''
     end

data/lib/synvert/rewriter/condition.rb

@@ -1,19 +1,29 @@
 # encoding: utf-8
 
 module Synvert
+  # Condition checks if rules matches.
   class Rewriter::Condition
+    # Initialize a condition.
+    #
+    # @param instance [Synvert::Rewriter::Instance]
+    # @param rules [Hash]
+    # @param block [Block]
+    # @return [Synvert::Rewriter::Condition]
     def initialize(instance, rules, &block)
       @instance = instance
       @rules = rules
       @block = block
     end
 
+    # If condition matches, run the block code.
     def process
       @instance.instance_eval &@block if match?
     end
   end
 
+  # IfExistCondition checks if matching node exists in the node children.
   class Rewriter::IfExistCondition < Rewriter::Condition
+    # check if any child node matches the rules.
     def match?
       match = false
       @instance.current_node.recursive_children do |child_node|
@@ -23,7 +33,9 @@ module Synvert
     end
   end
 
+  # UnlessExistCondition checks if matching node doesn't exist in the node children.
   class Rewriter::UnlessExistCondition < Rewriter::Condition
+    # check if none of child node matches the rules.
     def match?
       match = false
       @instance.current_node.recursive_children do |child_node|
@@ -33,7 +45,9 @@ module Synvert
     end
   end
 
+  # IfExistCondition checks if node has only one child node and the child node matches rules.
   class Rewriter::IfOnlyExistCondition < Rewriter::Condition
+    # check if only have one child node and the child node matches rules.
     def match?
       @instance.current_node.body.size == 1 &&
         @instance.current_node.body.first.match?(@instance, @rules)

data/lib/synvert/rewriter/gem_spec.rb

@@ -1,8 +1,15 @@
 # encoding: utf-8
 
 module Synvert
+  # GemSpec checks and compares gem version.
   class Rewriter::GemSpec
     OPERATORS = {eq: '==', lt: '<', gt: '>', lte: '<=', gte: '>=', ne: '!='}
+
+    # Initialize a gem_spec.
+    #
+    # @param name [String] gem name
+    # @param comparator [Hash] comparator to gem version, e.g. {eg: '2.0.0'},
+    #   comparator key can be eq, lt, gt, lte, gte or ne.
     def initialize(name, comparator)
       @name = name
       if Hash === comparator
@@ -14,6 +21,10 @@ module Synvert
       end
     end
 
+    # Check if the specified gem version in Gemfile.lock matches gem_spec comparator.
+    #
+    # @return [Boolean] true if matches, otherwise false.
+    # @raise [Synvert::GemfileLockNotFound] raise if Gemfile.lock does not exist.
     def match?
       gemfile_lock_path = File.join(Configuration.instance.get(:path), 'Gemfile.lock')
       if File.exists? gemfile_lock_path
@@ -24,7 +35,7 @@ module Synvert
           false
         end
       else
-        raise LoadError.new 'Gemfile.lock does not exist'
+        raise GemfileLockNotFound.new 'Gemfile.lock does not exist'
       end
     end
   end

data/lib/synvert/rewriter/instance.rb

@@ -1,15 +1,33 @@
 # encoding: utf-8
 
 module Synvert
+  # Instance is an execution unit, it finds specified ast nodes,
+  # checks if the nodes match some conditions, then add, replace or remove code.
+  #
+  # One instance can contains one or many [Synvert::Rewriter::Scope] and [Synvert::Rewriter::Condition].
   class Rewriter::Instance
+    # @!attribute [rw] current_node
+    #   @return current parsing node
+    # @!attribute [rw] current_source
+    #   @return current source code of file
+    # @!attribute [rw] current_file
+    #   @return current filename
     attr_accessor :current_node, :current_source, :current_file
 
+    # Initialize an instance.
+    #
+    # @param file_pattern [String] pattern to find files, e.g. spec/**/*_spec.rb
+    # @param block [Block] block code to find nodes, match conditions and rewrite code.
+    # @return [Synvert::Rewriter::Instance]
     def initialize(file_pattern, &block)
       @actions = []
       @file_pattern = file_pattern
       @block = block
     end
 
+    # Process the instance.
+    # It finds all files, for each file, it executes the block code, gets all rewrite actions,
+    # and rewrite source code back to original file.
     def process
       parser = Parser::CurrentRuby.new
       file_pattern = File.join(Configuration.instance.get(:path), @file_pattern)
@@ -41,50 +59,97 @@ module Synvert
       end
     end
 
+    # Gets current node, it allows to get current node in block code.
+    #
+    # @return [Parser::AST::Node]
     def node
       @current_node
     end
 
+    #######
+    # DSL #
+    #######
+
+    # Parse within_node dsl, it creates a [Synvert::Rewriter::Scope] to find matching ast nodes,
+    # then continue operating on each matching ast node.
+    #
+    # @param rules [Hash] rules to find mathing ast nodes.
+    # @param block [Block] block code to continue operating on the matching nodes.
     def within_node(rules, &block)
       Rewriter::Scope.new(self, rules, &block).process
     end
 
     alias with_node within_node
 
+    # Parse if_exist_node dsl, it creates a [Synvert::Rewriter::IfExistCondition] to check
+    # if matching nodes exist in the child nodes, if so, then continue operating on each matching ast node.
+    #
+    # @param rules [Hash] rules to check mathing ast nodes.
+    # @param block [Block] block code to continue operating on the matching nodes.
     def if_exist_node(rules, &block)
       Rewriter::IfExistCondition.new(self, rules, &block).process
     end
 
+    # Parse unless_exist_node dsl, it creates a [Synvert::Rewriter::UnlessExistCondition] to check
+    # if matching nodes doesn't exist in the child nodes, if so, then continue operating on each matching ast node.
+    #
+    # @param rules [Hash] rules to check mathing ast nodes.
+    # @param block [Block] block code to continue operating on the matching nodes.
     def unless_exist_node(rules, &block)
       Rewriter::UnlessExistCondition.new(self, rules, &block).process
     end
 
+    # Parse if_only_exist_node dsl, it creates a [Synvert::Rewriter::IfOnlyExistCondition] to check
+    # if current node has only one child node and the child node matches rules,
+    # if so, then continue operating on each matching ast node.
+    #
+    # @param rules [Hash] rules to check mathing ast nodes.
+    # @param block [Block] block code to continue operating on the matching nodes.
     def if_only_exist_node(rules, &block)
       Rewriter::IfOnlyExistCondition.new(self, rules, &block).process
     end
 
+    # Parse append dsl, it creates a [Synvert::Rewriter::AppendAction] to
+    # append the code to the bottom of current node body.
+    #
+    # @param code [String] code need to be appended.
     def append(code)
       @actions << Rewriter::AppendAction.new(self, code)
     end
 
+    # Parse insert dsl, it creates a [Synvert::Rewriter::InsertAction] to
+    # insert the code to the top of current node body.
+    #
+    # @param code [String] code need to be inserted.
     def insert(code)
       @actions << Rewriter::InsertAction.new(self, code)
     end
 
+    # Parse insert_after dsl, it creates a [Synvert::Rewriter::InsertAfterAction] to
+    # insert the code next to the current node.
+    #
+    # @param code [String] code need to be inserted.
     def insert_after(node)
       @actions << Rewriter::InsertAfterAction.new(self, node)
     end
 
+    # Parse replace_with dsl, it creates a [Synvert::Rewriter::ReplaceWithAction] to
+    # replace current node with code.
+    #
+    # @param code [String] code need to be replaced with.
     def replace_with(code)
       @actions << Rewriter::ReplaceWithAction.new(self, code)
     end
 
+    # Parse remove dsl, it creates a [Synvert::Rewriter::RemoveAction] to current node.
     def remove
       @actions << Rewriter::RemoveAction.new(self)
     end
 
   private
 
+    # It changes source code from bottom to top, and it can change source code twice at the same time.
+    # So if there is an overlap between two actions, it removes the conflict actions and operate them in the next loop.
     def check_conflict_actions
       i = @actions.length - 1
       @conflict_actions = []
@@ -97,6 +162,10 @@ module Synvert
       @conflict_actions
     end
 
+    # It checks if code is removed and that line is empty.
+    #
+    # @param source [String] source code of file
+    # @param line [String] the line number
     def remove_code_or_whole_line(source, line)
       newline_at_end_of_line = source[-1] == "\n"
       source_arr = source.split("\n")

data/lib/synvert/rewriter/scope.rb

@@ -1,13 +1,21 @@
 # encoding: utf-8
 
 module Synvert
+  # Scope finds the child nodes which match rules.
   class Rewriter::Scope
+    # Initialize a scope
+    #
+    # @param instance [Synvert::Rewriter::Instance]
+    # @param rules [Hash]
+    # @param block [Block]
     def initialize(instance, rules, &block)
       @instance = instance
       @rules = rules
       @block = block
     end
 
+    # Find the matching nodes. It checks the current node and iterates all child nodes,
+    # then run the block code for each matching node.
     def process
       current_node = @instance.current_node
       return unless current_node
@@ -27,6 +35,8 @@ module Synvert
 
   private
 
+    # Set instance current node properly and process.
+    # @param node [Parser::AST::Node]
     def process_with_node(node)
       @instance.current_node = node
       yield

data/lib/synvert/rewriter.rb

@@ -1,4 +1,20 @@
+# encoding: utf-8
+
 module Synvert
+  # Rewriter is the top level namespace in a snippet.
+  #
+  # One Rewriter can contain one or many [Synvert::Rewriter::Instance],
+  # which define the behavior what files and what codes to detect and rewrite to what code.
+  #
+  #   Synvert::Rewriter.new 'factory_girl_short_syntax', 'use FactoryGirl short syntax' do
+  #     if_gem 'factory_girl', {gte: '2.0.0'}
+  #
+  #     within_files 'spec/**/*.rb' do
+  #       with_node type: 'send', receiver: 'FactoryGirl', message: 'create' do
+  #         replace_with "create({{arguments}})"
+  #       end
+  #     end
+  #   end
   class Rewriter
     autoload :Action, 'synvert/rewriter/action'
     autoload :AppendAction, 'synvert/rewriter/action'
@@ -19,11 +35,28 @@ module Synvert
     autoload :GemSpec, 'synvert/rewriter/gem_spec'
 
     class <<self
+      # Register a rewriter with its name.
+      #
+      # @param name [String] the unique rewriter name.
+      # @param rewriter [Synvert::Rewriter] the rewriter to register.
       def register(name, rewriter)
         @rewriters ||= {}
         @rewriters[name.to_s] = rewriter
       end
 
+      # Fetch a rewriter by name.
+      #
+      # @param name [String] rewrtier name.
+      # @return [Synvert::Rewriter] the matching rewriter.
+      def fetch(name)
+        @rewriters[name.to_s]
+      end
+
+      # Get a registered rewriter by name and process that rewriter.
+      #
+      # @param name [String] the rewriter name.
+      # @return [Synvert::Rewriter] the registered rewriter.
+      # @raise [Synvert::RewriterNotFound] if the registered rewriter is not found.
       def call(name)
         if (rewriter = @rewriters[name.to_s])
           rewriter.process
@@ -33,34 +66,87 @@ module Synvert
         end
       end
 
+      # Get all available rewriters
+      #
+      # @return [Array<Synvert::Rewriter>]
       def availables
         @rewriters.values
       end
 
+      # Clear all registered rewriters.
       def clear
         @rewriters.clear
       end
     end
 
-    attr_reader :name, :description, :todo_list
-
-    def initialize(name, description, &block)
+    # @!attribute [r] name
+    #   @return [String] the unique name of rewriter
+    # @!attribute [r] sub_snippets
+    #   @return [Array<Synvert::Rewriter>] all rewriters this rewiter calls.
+    attr_reader :name, :sub_snippets
+
+    # Initialize a rewriter.
+    # When a rewriter is initialized, it is also registered.
+    #
+    # @param name [String] name of the rewriter.
+    # @param block [Block] a block defines the behaviors of the rewriter, block code won't be called when initialization.
+    # @return [Synvert::Rewriter]
+    def initialize(name, &block)
       @name = name
-      @description = description
       @block = block
       @helpers = []
+      @sub_snippets = []
       self.class.register(name, self)
     end
 
+    # Process the rewriter.
+    # It will call the block.
     def process
       self.instance_eval &@block
     end
 
+    # Process rewriter with sandbox mode.
+    # It will call the block but doesn't change any file.
+    def process_with_sandbox
+      @sandbox = true
+      self.process
+      @sandbox = false
+    end
+
+    #######
+    # DSL #
+    #######
+
+    # Parse description dsl, it sets description of the rewrite.
+    # Or get description.
+    #
+    # @param description [String] rewriter description.
+    # @return rewriter description.
+    def description(description=nil)
+      if description
+        @description = description
+      else
+        @description
+      end
+    end
+
+    # Parse if_gem dsl, it compares version of the specified gem.
+    #
+    # @param name [String] gem name.
+    # @param comparator [Hash] equal, less than or greater than specified version, e.g. {gte: '2.0.0'},
+    #   key can be eq, lt, gt, lte, gte or ne.
     def if_gem(name, comparator)
       @gem_spec = Rewriter::GemSpec.new(name, comparator)
     end
 
-    def within_file(file_pattern, &block)
+    # Parse within_files dsl, it finds specified files.
+    # It creates a [Synvert::Rewriter::Instance] to rewrite code.
+    #
+    # @param file_pattern [String] pattern to find files, e.g. spec/**/*_spec.rb
+    # @param block [Block] the block to rewrite code in the matching files.
+    def within_files(file_pattern, &block)
+      return if @sandbox
+
       if !@gem_spec || @gem_spec.match?
         instance = Rewriter::Instance.new(file_pattern, &block)
         @helpers.each { |helper| instance.singleton_class.send(:define_method, helper[:name], &helper[:block]) }
@@ -68,24 +154,47 @@ module Synvert
       end
     end
 
-    alias within_files within_file
+    # Parse within_file dsl, it finds a specifiled file.
+    alias within_file within_files
+
+    # Parses add_file dsl, it adds a new file.
+    #
+    # @param filename [String] file name of newly created file.
+    # @param content [String] file body of newly created file.
+    def add_file(filename, content)
+      return if @sandbox
 
-    def add_file(file, content)
-      File.open file, 'w' do |file|
+      File.open filename, 'w' do |file|
         file.write content
       end
     end
 
+    # Parse add_snippet dsl, it calls anther rewriter.
+    #
+    # @param name [String] name of another rewriter.
     def add_snippet(name)
-      self.class.call(name)
+      @sub_snippets << self.class.call(name)
     end
 
+    # Parse helper_method dsl, it defines helper method for [Synvert::Rewriter::Instance].
+    #
+    # @param name [String] helper method name.
+    # @param block [Block] helper method block.
     def helper_method(name, &block)
       @helpers << {name: name, block: block}
     end
 
-    def todo(list)
-      @todo_list = list
+    # Parse todo dsl, it sets todo of the rewriter.
+    # Or get todo.
+    #
+    # @param todo_list [String] rewriter todo.
+    # @return [String] rewriter todo.
+    def todo(todo=nil)
+      if todo
+        @todo = todo
+      else
+        @todo
+      end
     end
   end
 end