Refactor by adding AnnotateRoutes::Helpers (#770)

For further refactoring toward better architecture, I moved methods `.strip_annotations`, `.extract_magic_comments_from_array` and `.real_content_and_header_position` from `AnnotateRoutes` to `AnnotateRoutes::Helpers`.

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2020-02-13 20:05:34 +0900 using RuboCop version 0.68.1.
+# on 2020-03-01 03:15:48 +0900 using RuboCop version 0.68.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -266,14 +266,16 @@ Style/Dir:
   Exclude:
     - 'bin/annotate'
 
-# Offense count: 7
+# Offense count: 9
 Style/Documentation:
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
     - 'lib/annotate.rb'
     - 'lib/annotate/active_record_patch.rb'
     - 'lib/annotate/annotate_models.rb'
+    - 'lib/annotate/annotate_routes.rb'
+    - 'lib/annotate/annotate_routes/helpers.rb'
     - 'lib/annotate/version.rb'
     - 'lib/generators/annotate/install_generator.rb'
     - 'lib/tasks/annotate_models_migrate.rake'
@@ -307,7 +309,7 @@ Style/FormatStringToken:
   Exclude:
     - 'lib/annotate/annotate_models.rb'
 
-# Offense count: 26
+# Offense count: 27
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: when_needed, always, never
@@ -422,7 +424,7 @@ Style/RedundantParentheses:
 # Configuration parameters: AllowMultipleReturnValues.
 Style/RedundantReturn:
   Exclude:
-    - 'lib/annotate/annotate_routes.rb'
+    - 'lib/annotate/annotate_routes/helpers.rb'
 
 # Offense count: 2
 # Cop supports --auto-correct.

lib/annotate/annotate_routes.rb

@@ -19,18 +19,19 @@
 #
 # Released under the same license as Ruby. No Support. No Warranty.
 #
+
+require_relative './annotate_routes/helpers'
+
 module AnnotateRoutes
   PREFIX = '== Route Map'.freeze
   PREFIX_MD = '## Route Map'.freeze
   HEADER_ROW = ['Prefix', 'Verb', 'URI Pattern', 'Controller#Action'].freeze
 
-  MAGIC_COMMENT_MATCHER = Regexp.new(/(^#\s*encoding:.*)|(^# coding:.*)|(^# -\*- coding:.*)|(^# -\*- encoding\s?:.*)|(^#\s*frozen_string_literal:.+)|(^# -\*- frozen_string_literal\s*:.+-\*-)/).freeze
-
   class << self
     def do_annotations(options = {})
       if routes_file_exist?
         existing_text = File.read(routes_file)
-        content, header_position = strip_annotations(existing_text)
+        content, header_position = Helpers.strip_annotations(existing_text)
         new_content = annotate_routes(header(options), content, header_position, options)
         new_text = new_content.join("\n")
 
@@ -47,7 +48,7 @@ def do_annotations(options = {})
     def remove_annotations(_options={})
       if routes_file_exist?
         existing_text = File.read(routes_file)
-        content, header_position = strip_annotations(existing_text)
+        content, header_position = Helpers.strip_annotations(existing_text)
         new_content = strip_on_removal(content, header_position)
         new_text = new_content.join("\n")
         if rewrite_contents(existing_text, new_text)
@@ -73,7 +74,7 @@ def routes_file
     def header(options = {})
       routes_map = app_routes_map(options)
 
-      magic_comments_map, routes_map = extract_magic_comments_from_array(routes_map)
+      magic_comments_map, routes_map = Helpers.extract_magic_comments_from_array(routes_map)
 
       out = []
 
@@ -113,35 +114,6 @@ def comment(row = '')
       end
     end
 
-    # TODO: write the method doc using ruby rdoc formats
-    # This method returns an array of 'real_content' and 'header_position'.
-    # 'header_position' will either be :before, :after, or
-    # a number.  If the number is > 0, the
-    # annotation was found somewhere in the
-    # middle of the file.  If the number is
-    # zero, no annotation was found.
-    def strip_annotations(content)
-      real_content = []
-      mode = :content
-      header_position = 0
-
-      content.split(/\n/, -1).each_with_index do |line, line_number|
-        if mode == :header && line !~ /\s*#/
-          mode = :content
-          real_content << line unless line.blank?
-        elsif mode == :content
-          if line =~ /^\s*#\s*== Route.*$/
-            header_position = line_number + 1 # index start's at 0
-            mode = :header
-          else
-            real_content << line
-          end
-        end
-      end
-
-      real_content_and_header_position(real_content, header_position)
-    end
-
     def strip_on_removal(content, header_position)
       if header_position == :before
         content.shift while content.first == ''
@@ -168,7 +140,7 @@ def rewrite_contents(existing_text, new_text)
     end
 
     def annotate_routes(header, content, header_position, options = {})
-      magic_comments_map, content = extract_magic_comments_from_array(content)
+      magic_comments_map, content = Helpers.extract_magic_comments_from_array(content)
       if %w(before top).include?(options[:position_in_routes])
         header = header << '' if content.first != ''
         magic_comments_map << '' if magic_comments_map.any?
@@ -208,24 +180,6 @@ def app_routes_map(options)
       routes_map
     end
 
-    # @param [Array<String>] content
-    # @return [Array<String>] all found magic comments
-    # @return [Array<String>] content without magic comments
-    def extract_magic_comments_from_array(content_array)
-      magic_comments = []
-      new_content = []
-
-      content_array.each do |row|
-        if row =~ MAGIC_COMMENT_MATCHER
-          magic_comments << row.strip
-        else
-          new_content << row
-        end
-      end
-
-      [magic_comments, new_content]
-    end
-
     def content(line, maxs, options = {})
       return line.rstrip unless options[:format_markdown]
 
@@ -235,18 +189,5 @@ def content(line, maxs, options = {})
         sprintf("%-#{min_length}.#{min_length}s", elem.tr('|', '-'))
       end.join(' | ')
     end
-
-    def real_content_and_header_position(real_content, header_position)
-      # By default assume the annotation was found in the middle of the file
-
-      # ... unless we have evidence it was at the beginning ...
-      return real_content, :before if header_position == 1
-
-      # ... or that it was at the end.
-      return real_content, :after if header_position >= real_content.count
-
-      # and the default
-      return real_content, header_position
-    end
   end
 end

lib/annotate/annotate_routes/helpers.rb

@@ -0,0 +1,69 @@
+module AnnotateRoutes
+  module Helpers
+    MAGIC_COMMENT_MATCHER = Regexp.new(/(^#\s*encoding:.*)|(^# coding:.*)|(^# -\*- coding:.*)|(^# -\*- encoding\s?:.*)|(^#\s*frozen_string_literal:.+)|(^# -\*- frozen_string_literal\s*:.+-\*-)/).freeze
+
+    class << self
+      # TODO: write the method doc using ruby rdoc formats
+      # This method returns an array of 'real_content' and 'header_position'.
+      # 'header_position' will either be :before, :after, or
+      # a number.  If the number is > 0, the
+      # annotation was found somewhere in the
+      # middle of the file.  If the number is
+      # zero, no annotation was found.
+      def strip_annotations(content)
+        real_content = []
+        mode = :content
+        header_position = 0
+
+        content.split(/\n/, -1).each_with_index do |line, line_number|
+          if mode == :header && line !~ /\s*#/
+            mode = :content
+            real_content << line unless line.blank?
+          elsif mode == :content
+            if line =~ /^\s*#\s*== Route.*$/
+              header_position = line_number + 1 # index start's at 0
+              mode = :header
+            else
+              real_content << line
+            end
+          end
+        end
+
+        real_content_and_header_position(real_content, header_position)
+      end
+
+      # @param [Array<String>] content
+      # @return [Array<String>] all found magic comments
+      # @return [Array<String>] content without magic comments
+      def extract_magic_comments_from_array(content_array)
+        magic_comments = []
+        new_content = []
+
+        content_array.each do |row|
+          if row =~ MAGIC_COMMENT_MATCHER
+            magic_comments << row.strip
+          else
+            new_content << row
+          end
+        end
+
+        [magic_comments, new_content]
+      end
+
+      private
+
+      def real_content_and_header_position(real_content, header_position)
+        # By default assume the annotation was found in the middle of the file
+
+        # ... unless we have evidence it was at the beginning ...
+        return real_content, :before if header_position == 1
+
+        # ... or that it was at the end.
+        return real_content, :after if header_position >= real_content.count
+
+        # and the default
+        return real_content, header_position
+      end
+    end
+  end
+end