annotate 2.6.3 → 3.2.0

data/lib/annotate/annotate_routes/header_generator.rb

@@ -0,0 +1,113 @@
+require_relative './helpers'
+
+module AnnotateRoutes
+  class HeaderGenerator
+    PREFIX = '== Route Map'.freeze
+    PREFIX_MD = '## Route Map'.freeze
+    HEADER_ROW = ['Prefix', 'Verb', 'URI Pattern', 'Controller#Action'].freeze
+
+    class << self
+      def generate(options = {})
+        new(options, routes_map(options)).generate
+      end
+
+      private :new
+
+      private
+
+      def routes_map(options)
+        result = `rake routes`.chomp("\n").split(/\n/, -1)
+
+        # In old versions of Rake, the first line of output was the cwd.  Not so
+        # much in newer ones.  We ditch that line if it exists, and if not, we
+        # keep the line around.
+        result.shift if result.first =~ %r{^\(in \/}
+
+        ignore_routes = options[:ignore_routes]
+        regexp_for_ignoring_routes = ignore_routes ? /#{ignore_routes}/ : nil
+
+        # Skip routes which match given regex
+        # Note: it matches the complete line (route_name, path, controller/action)
+        if regexp_for_ignoring_routes
+          result.reject { |line| line =~ regexp_for_ignoring_routes }
+        else
+          result
+        end
+      end
+    end
+
+    def initialize(options, routes_map)
+      @options = options
+      @routes_map = routes_map
+    end
+
+    def generate
+      magic_comments_map, contents_without_magic_comments = Helpers.extract_magic_comments_from_array(routes_map)
+
+      out = []
+
+      magic_comments_map.each do |magic_comment|
+        out << magic_comment
+      end
+      out << '' if magic_comments_map.any?
+
+      out << comment(options[:wrapper_open]) if options[:wrapper_open]
+
+      out << comment(markdown? ? PREFIX_MD : PREFIX) + timestamp_if_required
+      out << comment
+      return out if contents_without_magic_comments.size.zero?
+
+      maxs = [HEADER_ROW.map(&:size)] + contents_without_magic_comments[1..-1].map { |line| line.split.map(&:size) }
+
+      if markdown?
+        max = maxs.map(&:max).compact.max
+
+        out << comment(content(HEADER_ROW, maxs))
+        out << comment(content(['-' * max, '-' * max, '-' * max, '-' * max], maxs))
+      else
+        out << comment(content(contents_without_magic_comments[0], maxs))
+      end
+
+      out += contents_without_magic_comments[1..-1].map { |line| comment(content(markdown? ? line.split(' ') : line, maxs)) }
+      out << comment(options[:wrapper_close]) if options[:wrapper_close]
+
+      out
+    end
+
+    private
+
+    attr_reader :options, :routes_map
+
+    def comment(row = '')
+      if row == ''
+        '#'
+      else
+        "# #{row}"
+      end
+    end
+
+    def content(line, maxs)
+      return line.rstrip unless markdown?
+
+      line.each_with_index.map { |elem, index| format_line_element(elem, maxs, index) }.join(' | ')
+    end
+
+    def format_line_element(elem, maxs, index)
+      min_length = maxs.map { |arr| arr[index] }.max || 0
+      format("%-#{min_length}.#{min_length}s", elem.tr('|', '-'))
+    end
+
+    def markdown?
+      options[:format_markdown]
+    end
+
+    def timestamp_if_required(time = Time.now)
+      if options[:timestamp]
+        time_formatted = time.strftime('%Y-%m-%d %H:%M')
+        " (Updated #{time_formatted})"
+      else
+        ''
+      end
+    end
+  end
+end

data/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

data/lib/annotate/annotate_routes.rb

@@ -8,7 +8,7 @@
 # Yes, it's simple but I'm thick and often need a reminder of what my routes
 # mean.
 #
-# Running this task will replace any exising route comment generated by the
+# Running this task will replace any existing route comment generated by the
 # task. Best to back up your routes file before running:
 #
 # Author:
@@ -17,131 +17,102 @@
 #
 # Released under the same license as Ruby. No Support. No Warranty.
 #
-module AnnotateRoutes
-  PREFIX = "# == Route Map"
-
-  def self.do_annotations(options={})
-    return unless(routes_exists?)
-
-    position_after = options[:position_in_routes] != 'before'
-
-    routes_map = `rake routes`.split(/\n/, -1)
 
-    # In old versions of Rake, the first line of output was the cwd.  Not so
-    # much in newer ones.  We ditch that line if it exists, and if not, we
-    # keep the line around.
-    routes_map.shift if(routes_map.first =~ /^\(in \//)
+require_relative './annotate_routes/helpers'
+require_relative './annotate_routes/header_generator'
 
-    header = [
-      "#{PREFIX} (Updated #{Time.now.strftime("%Y-%m-%d %H:%M")})",
-      "#"
-    ] + routes_map.map { |line| "# #{line}".rstrip }
-
-    (content, where_header_found) = strip_annotations(File.read(routes_file))
-    changed = where_header_found != 0 # This 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.
-
-    if(position_after)
-      # Ensure we have adequate trailing newlines at the end of the file to
-      # ensure a blank line separating the content from the annotation.
-      content << '' if(content.last != '')
-
-      # We're moving something from the top of the file to the bottom, so ditch
-      # the spacer we put in the first time around.
-      if(changed && where_header_found == :before)
-        content.shift if(content.first == '')
+module AnnotateRoutes
+  class << self
+    def do_annotations(options = {})
+      if routes_file_exist?
+        existing_text = File.read(routes_file)
+        content, header_position = Helpers.strip_annotations(existing_text)
+        new_content = annotate_routes(HeaderGenerator.generate(options), content, header_position, options)
+        new_text = new_content.join("\n")
+
+        if rewrite_contents(existing_text, new_text)
+          puts "#{routes_file} was annotated."
+        else
+          puts "#{routes_file} was not changed."
+        end
+      else
+        puts "#{routes_file} could not be found."
       end
-    else
-      header = header << '' if(content.first != '' || changed)
     end
 
-    content = position_after ? (content + header) : header + content
-
-    write_contents(content)
-
-    puts "Route file annotated."
-  end
-
-  def self.remove_annotations(options={})
-    return unless(routes_exists?)
-
-    (content, where_header_found) = strip_annotations(File.read(routes_file))
-
-    content = strip_on_removal(content, where_header_found)
-
-    write_contents(content)
+    def remove_annotations(_options={})
+      if routes_file_exist?
+        existing_text = File.read(routes_file)
+        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)
+          puts "Annotations were removed from #{routes_file}."
+        else
+          puts "#{routes_file} was not changed (Annotation did not exist)."
+        end
+      else
+        puts "#{routes_file} could not be found."
+      end
+    end
 
-    puts "Removed annotations from routes file."
-  end
+    private
 
-protected
+    def routes_file_exist?
+      File.exist?(routes_file)
+    end
 
-  def self.routes_file
-    @routes_rb ||= File.join("config", "routes.rb")
-  end
+    def routes_file
+      @routes_rb ||= File.join('config', 'routes.rb')
+    end
 
-  def self.routes_exists?
-    routes_exists = File.exists?(routes_file)
-    puts "Can`t find routes.rb" if(!routes_exists)
-    return routes_exists
-  end
+    def strip_on_removal(content, header_position)
+      if header_position == :before
+        content.shift while content.first == ''
+      elsif header_position == :after
+        content.pop while content.last == ''
+      end
 
-  def self.write_contents(content)
-    content << '' unless(content.last == '') # Make sure we end on a trailing
-                                             # newline.
+      # Make sure we end on a trailing newline.
+      content << '' unless content.last == ''
 
-    File.open(routes_file, "wb") { |f| f.puts(content.join("\n")) }
-  end
+      # TODO: If the user buried it in the middle, we should probably see about
+      # TODO: preserving a single line of space between the content above and
+      # TODO: below...
+      content
+    end
 
-  def self.strip_annotations(content)
-    real_content = []
-    mode = :content
-    line_number = 0
-    header_found_at = 0
-    content.split(/\n/, -1).each do |line|
-      line_number += 1
-      begin
-        if(mode == :header)
-          if(line !~ /\s*#/)
-            mode = :content
-            raise unless (line == '')
-          end
-        elsif(mode == :content)
-          if(line =~ /^\s*#\s*== Route.*$/)
-            header_found_at = line_number
-            mode = :header
-          else
-            real_content << line
-          end
-        end
-      rescue
-        retry
+    def rewrite_contents(existing_text, new_text)
+      if existing_text == new_text
+        false
+      else
+        File.open(routes_file, 'wb') { |f| f.puts(new_text) }
+        true
       end
     end
-    content_lines = real_content.count
 
-    # By default assume the annotation was found in the middle of the file...
-    where_header_found = header_found_at
-    # ... unless we have evidence it was at the beginning ...
-    where_header_found = :before if(header_found_at == 1)
-    # ... or that it was at the end.
-    where_header_found = :after if(header_found_at >= content_lines)
+    def annotate_routes(header, content, header_position, options = {})
+      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?
+        new_content = magic_comments_map + header + content
+      else
+        # Ensure we have adequate trailing newlines at the end of the file to
+        # ensure a blank line separating the content from the annotation.
+        content << '' unless content.last == ''
+
+        # We're moving something from the top of the file to the bottom, so ditch
+        # the spacer we put in the first time around.
+        content.shift if header_position == :before && content.first == ''
+
+        new_content = magic_comments_map + content + header
+      end
 
-    return real_content, where_header_found
-  end
+      # Make sure we end on a trailing newline.
+      new_content << '' unless new_content.last == ''
 
-  def self.strip_on_removal(content, where_header_found)
-    if(where_header_found == :before)
-      content.shift while(content.first == '')
-    elsif(where_header_found == :after)
-      content.pop while(content.last == '')
+      new_content
     end
-    # TODO: If the user buried it in the middle, we should probably see about
-    # TODO: preserving a single line of space between the content above and
-    # TODO: below...
-    return content
   end
 end

data/lib/annotate/constants.rb

@@ -0,0 +1,38 @@
+module Annotate
+  module Constants
+    TRUE_RE = /^(true|t|yes|y|1)$/i.freeze
+
+    ##
+    # The set of available options to customize the behavior of Annotate.
+    #
+    POSITION_OPTIONS = [
+      :position_in_routes, :position_in_class, :position_in_test,
+      :position_in_fixture, :position_in_factory, :position,
+      :position_in_serializer
+    ].freeze
+
+    FLAG_OPTIONS = [
+      :show_indexes, :simple_indexes, :include_version, :exclude_tests,
+      :exclude_fixtures, :exclude_factories, :ignore_model_sub_dir,
+      :format_bare, :format_rdoc, :format_yard, :format_markdown, :sort, :force, :frozen,
+      :trace, :timestamp, :exclude_serializers, :classified_sort,
+      :show_foreign_keys, :show_complete_foreign_keys,
+      :exclude_scaffolds, :exclude_controllers, :exclude_helpers,
+      :exclude_sti_subclasses, :ignore_unknown_models, :with_comment
+    ].freeze
+
+    OTHER_OPTIONS = [
+      :additional_file_patterns, :ignore_columns, :skip_on_db_migrate, :wrapper_open, :wrapper_close,
+      :wrapper, :routes, :models, :hide_limit_column_types, :hide_default_column_types,
+      :ignore_routes, :active_admin
+    ].freeze
+
+    PATH_OPTIONS = [
+      :require, :model_dir, :root_dir
+    ].freeze
+
+    ALL_ANNOTATE_OPTIONS = [
+      POSITION_OPTIONS, FLAG_OPTIONS, OTHER_OPTIONS, PATH_OPTIONS
+    ].freeze
+  end
+end

data/lib/annotate/helpers.rb

@@ -0,0 +1,30 @@
+module Annotate
+  # Class for holding helper methods. Done to make lib/annotate.rb less bloated.
+  class Helpers
+    class << self
+      def skip_on_migration?
+        ENV['ANNOTATE_SKIP_ON_DB_MIGRATE'] =~ Constants::TRUE_RE || ENV['skip_on_db_migrate'] =~ Constants::TRUE_RE
+      end
+
+      def include_routes?
+        ENV['routes'] =~ Constants::TRUE_RE
+      end
+
+      def include_models?
+        ENV['models'] =~ Constants::TRUE_RE
+      end
+
+      def true?(val)
+        val.present? && Constants::TRUE_RE.match?(val)
+      end
+
+      def fallback(*args)
+        args.detect(&:present?)
+      end
+
+      def reset_options(options)
+        options.flatten.each { |key| ENV[key.to_s] = nil }
+      end
+    end
+  end
+end