markdown_helper 1.8.0 → 1.9.0

data/Rakefile

@@ -1,6 +1,8 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
+require_relative 'lib/markdown_helper'
+
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
@@ -12,19 +14,20 @@ namespace :build do
   desc 'Build README.md file from README.template.md'
   task :readme do
     Rake::Task['build:usages'].invoke
-    require_relative 'lib/markdown_helper'
-    markdown_helper = MarkdownHelper.new
-    template_file_path = 'markdown/highlight_ruby_template.md'
-    markdown_file_path = 'markdown/highlighted_ruby.md'
-    markdown_helper.include(template_file_path, markdown_file_path)
-    # Do the resolve before the include, so that the included text is not also resolved.
-    # This protects example code from being also resolved, thus damaging the example code.
-    # Temp file must be in the same directory as its source (it becomes the source).
-    temp_file_path = 'markdown/temp_resolved.md'
-    markdown_helper.resolve('markdown/README.template.md', temp_file_path)
-    readme_file_path = 'README.md'
-    markdown_helper.include(temp_file_path, readme_file_path)
-    File.delete(temp_file_path)
+    Dir.chdir('markdown/readme') do
+      markdown_helper = MarkdownHelper.new
+      template_file_path = 'highlight_ruby_template.md'
+      markdown_file_path = 'highlighted_ruby.md'
+      markdown_helper.include(template_file_path, markdown_file_path)
+      # Do the resolve before the include, so that the included text is not also resolved.
+      # This protects example code from being also resolved, thus damaging the example code.
+      # Temp file must be in the same directory as its source (it becomes the source).
+      temp_file_path = 'temp_resolved.md'
+      markdown_helper.resolve('README.template.md', temp_file_path)
+      readme_file_path = '../../README.md'
+      markdown_helper.include(temp_file_path, readme_file_path)
+      File.delete(temp_file_path)
+    end
   end
 
   desc 'Build usage for executables'

data/bin/_include

@@ -42,6 +42,5 @@ parser.parse!
 _, template_file_path, markdown_file_path = ARGV
 
 usage(opts) unless ARGV.size == 3
-usage(opts) unless File.readable?(template_file_path)
 
 MarkdownHelper.new(options).include(template_file_path, markdown_file_path)

data/bin/_resolve

@@ -42,6 +42,5 @@ parser.parse!
 _, template_file_path, markdown_file_path = ARGV
 
 usage(opts) unless ARGV.size == 3
-usage(opts) unless File.readable?(template_file_path)
 
 MarkdownHelper.new(options).resolve(template_file_path, markdown_file_path)

data/bin/markdown_helper

@@ -2,6 +2,9 @@
 
 require 'markdown_helper'
 
+# Confirm that we're in a git project.
+MarkdownHelper.git_clone_dir_path
+
 # Each command foo has a corresponding Ruby executable _foo.
 def command_keywords
   dir_path = File.dirname(__FILE__)

data/bin/setup

@@ -1,8 +1,8 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/markdown_helper.rb

@@ -7,19 +7,27 @@ require 'markdown_helper/version'
 # @author Burdette Lamar
 class MarkdownHelper
 
+  class MarkdownHelperError < RuntimeError; end
+  class CircularIncludeError < MarkdownHelperError; end
+  class MissingIncludeeError < MarkdownHelperError; end
+  class OptionError < MarkdownHelperError; end
+  class EnvironmentError < MarkdownHelperError; end
+
   IMAGE_REGEXP = /!\[([^\[]+)\]\(([^)]+)\)/
   INCLUDE_REGEXP = /^@\[([^\[]+)\]\(([^)]+)\)$/
 
   attr_accessor :pristine
 
   def initialize(options = {})
+    # Confirm that we're in a git project.
+    MarkdownHelper.git_clone_dir_path
     default_options = {
         :pristine => false,
     }
     merged_options = default_options.merge(options)
     merged_options.each_pair do |method, value|
       unless self.respond_to?(method)
-        raise ArgumentError.new("Unknown option: #{method}")
+        raise OptionError.new("Unknown option: #{method}")
       end
       setter_method = "#{method}="
       send(setter_method, value)
@@ -42,7 +50,7 @@ class MarkdownHelper
   #   @[:markdown](foo.md)
   def include(template_file_path, markdown_file_path)
     send(:generate_file, template_file_path, markdown_file_path, __method__) do |input_lines, output_lines|
-      send(:include_files, template_file_path, input_lines, output_lines, markdown_inclusions = {})
+      send(:include_files, template_file_path, input_lines, output_lines, Inclusions.new)
     end
   end
 
@@ -77,7 +85,7 @@ class MarkdownHelper
 
   private
 
-  def comment(text)
+  def self.comment(text)
     "<!--#{text}-->\n"
   end
 
@@ -86,27 +94,48 @@ class MarkdownHelper
     repo_name = ENV['REPO_NAME']
     unless repo_user and repo_name
       message = 'ENV values for both REPO_USER and REPO_NAME must be defined.'
-      raise RuntimeError.new(message)
+      raise EnvironmentError.new(message)
     end
     [repo_user, repo_name]
   end
 
   def generate_file(template_file_path, markdown_file_path, method)
     output_lines = []
-    File.open(template_file_path, 'r') do |template_file|
-      output_lines.push(comment(" >>>>>> BEGIN GENERATED FILE (#{method.to_s}): SOURCE #{template_file_path} ")) unless pristine
-      input_lines = template_file.readlines
-      yield input_lines, output_lines
-      output_lines.push(comment(" <<<<<< END GENERATED FILE (#{method.to_s}): SOURCE #{template_file_path} ")) unless pristine
+    begin
+      File.open(template_file_path, 'r') do |template_file|
+        template_path_in_project = MarkdownHelper.path_in_project(template_file_path)
+        output_lines.push(MarkdownHelper.comment(" >>>>>> BEGIN GENERATED FILE (#{method.to_s}): SOURCE #{template_path_in_project} ")) unless pristine
+        input_lines = template_file.readlines
+        yield input_lines, output_lines
+        output_lines.push(MarkdownHelper.comment(" <<<<<< END GENERATED FILE (#{method.to_s}): SOURCE #{template_path_in_project} ")) unless pristine
+      end
+      output = output_lines.join('')
+    rescue => e
+      unless e.kind_of?(MarkdownHelperError)
+        message = [
+            e.message,
+            Inclusions::UNREADABLE_TEMPLATE_EXCEPTION_LABEL,
+        ].join("\n")
+        e = e.exception(message)
+      end
+      raise e
     end
-    output = output_lines.join('')
-    File.open(markdown_file_path, 'w') do |md_file|
-      md_file.write(output)
+    begin
+      File.write(markdown_file_path, output)
+    rescue => e
+      unless e.kind_of?(MarkdownHelperError)
+        message = [
+            e.message,
+            Inclusions::UNWRITABLE_OUTPUT_EXCEPTION_LABEL,
+        ].join("\n")
+        e = e.exception(message)
+      end
+      raise e
     end
     output
   end
 
-  def include_files(includer_file_path, input_lines, output_lines, markdown_inclusions)
+  def include_files(includer_file_path, input_lines, output_lines, inclusions)
 
     input_lines.each_with_index do |input_line, line_index|
       match_data = input_line.match(INCLUDE_REGEXP)
@@ -115,73 +144,42 @@ class MarkdownHelper
         next
       end
       treatment = match_data[1]
-      relative_included_file_path = match_data[2]
-      treatment = case treatment
-                    when ':code_block'
-                      :code_block
-                    when ':markdown'
-                      :markdown
-                    when ':verbatim'
-                      message = "Treatment ':verbatim' is deprecated; please use treatment ':markdown'."
-                      warn(message)
-                      :markdown
-                    when ':comment'
-                      :comment
-                    else
-                      treatment
-                  end
-      new_inclusion = Inclusion.new(
+      cited_includee_file_path = match_data[2]
+      inclusions.include(
+          input_line.chomp,
           includer_file_path,
-          includer_line_number = line_index + 1,
-          relative_included_file_path
+          line_index + 1,
+          cited_includee_file_path,
+          treatment,
+          output_lines,
+          self
       )
-      included_real_path = new_inclusion.included_real_path
-      if treatment == :markdown
-        previously_included = markdown_inclusions.include?(included_real_path)
-        if previously_included
-          markdown_inclusions.store(included_real_path, new_inclusion)
-          message_lines = ['Includes are circular:']
-           i = 0
-          markdown_inclusions.each_with_index do |path_and_inclusion, i|
-            _, inclusion = *path_and_inclusion
-            message_lines.push("  Level #{i}:")
-            message_lines.push("    Includer: #{inclusion.includer_file_path}:#{inclusion.includer_line_number}")
-            message_lines.push("    Relative file path: #{inclusion.relative_included_file_path}")
-            message_lines.push("    Included file path: #{inclusion.included_file_path}")
-            message_lines.push("    Real file_path: #{inclusion.included_real_path}")
-          end
-          message = message_lines.join("\n")
-          raise RuntimeError.new(message)
-        end
-      end
-      output_lines.push(comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{new_inclusion.included_file_path} ")) unless pristine
-      include_lines = File.readlines(new_inclusion.included_file_path)
-      unless include_lines.last.match("\n")
-        message = "Warning:  Included file has no trailing newline: #{relative_included_file_path}"
-        warn(message)
-      end
-      case treatment
-        when :markdown
-          # Pass through unadorned, but honor any nested includes.
-          markdown_inclusions.store(included_real_path, new_inclusion)
-          include_files(new_inclusion.included_file_path, include_lines, output_lines, markdown_inclusions)
-          markdown_inclusions.delete(included_real_path)
-        when :comment
-          output_lines.push(comment(include_lines.join('')))
-        else
-          # Use the file name as a label.
-          file_name_line = format("<code>%s</code>\n", File.basename(relative_included_file_path))
-          output_lines.push(file_name_line)
-          # Put into code block.
-          language = treatment == :code_block ? '' : treatment
-          output_lines.push("```#{language}\n")
-          output_lines.push(*include_lines)
-          output_lines.push("```\n")
-      end
-      output_lines.push(comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{new_inclusion.included_file_path} ")) unless pristine
     end
   end
 
+  def self.git_clone_dir_path
+    git_dir = `git rev-parse --git-dir`.chomp
+    unless $?.success?
+      message = <<EOT
+
+Markdown helper must run inside a .git project.
+That is, the working directory one of its parents must be a .git directory.
+EOT
+      raise RuntimeError.new(message)
+    end
+    if git_dir == '.git'
+      path = `pwd`.chomp
+    else
+      path = File.dirname(git_dir).chomp
+    end
+    realpath = Pathname.new(path.sub(%r|/c/|, 'C:/')).realpath
+    realpath.to_s
+  end
+
+  def self.path_in_project(path)
+    path.sub(MarkdownHelper.git_clone_dir_path + '/', '')
+  end
+
   def resolve_images(template_file_path, input_lines, output_lines)
     input_lines.each do |input_line|
       scan_data = input_line.scan(IMAGE_REGEXP)
@@ -189,7 +187,7 @@ class MarkdownHelper
         output_lines.push(input_line)
         next
       end
-      output_lines.push(comment(" >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
+      output_lines.push(MarkdownHelper.comment(" >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
       output_line = input_line
       scan_data.each do |alt_text, path_and_attributes|
         original_image_file_path, attributes_s = path_and_attributes.split(/\s?\|\s?/, 2)
@@ -206,14 +204,6 @@ class MarkdownHelper
         if original_image_file_path.start_with?('http')
           image_path = original_image_file_path
         else
-          git_dir = `git rev-parse --git-dir`.chomp
-          if git_dir == '.git'
-            git_clone_dir_path = `pwd`.chomp
-          else
-            git_clone_dir_path = git_dir.chomp
-          end
-          git_clone_dir_pathname = Pathname.new(git_clone_dir_path.sub(%r|/c/|, 'C:/')).realpath
-          git_clone_dir_path = git_clone_dir_pathname.to_s
           absolute_template_file_path = File.absolute_path(template_file_path)
           template_dir_path = File.dirname(absolute_template_file_path)
           absolute_file_path = File.join(
@@ -221,7 +211,7 @@ class MarkdownHelper
               original_image_file_path,
           )
           absolute_file_path = Pathname.new(absolute_file_path).cleanpath.to_s
-          relative_image_file_path = absolute_file_path.sub(git_clone_dir_path + '/', '')
+          relative_image_file_path = MarkdownHelper.path_in_project(absolute_file_path)
           repo_user, repo_name = repo_user_and_name
           image_path = File.join(
               "https://raw.githubusercontent.com/#{repo_user}/#{repo_name}/master",
@@ -237,34 +227,276 @@ class MarkdownHelper
         output_line = output_line.sub(IMAGE_REGEXP, img_element)
       end
       output_lines.push(output_line)
-      output_lines.push(comment(" <<<<<< END RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
+      output_lines.push(MarkdownHelper.comment(" <<<<<< END RESOLVED IMAGES: INPUT-LINE '#{input_line}' ")) unless pristine
+    end
+
+  end
+
+  class Inclusions
+
+    attr_accessor :inclusions
+
+    def initialize
+      self.inclusions = []
+    end
+
+    def include(
+        include_description,
+        includer_file_path,
+        includer_line_number,
+        cited_includee_file_path,
+        treatment,
+        output_lines,
+        markdown_helper
+    )
+      treatment = case treatment
+                    when ':code_block'
+                      :code_block
+                    when ':markdown'
+                      :markdown
+                    when ':verbatim'
+                      message = "Treatment ':verbatim' is deprecated; please use treatment ':markdown'."
+                      warn(message)
+                      :markdown
+                    when ':comment'
+                      :comment
+                    when ':pre'
+                      :pre
+                    else
+                      treatment
+                  end
+      new_inclusion = Inclusion.new(
+          include_description,
+          includer_file_path,
+          includer_line_number,
+          cited_includee_file_path
+      )
+      if treatment == :markdown
+        check_circularity(new_inclusion)
+      end
+      includee_path_in_project = MarkdownHelper.path_in_project(new_inclusion.absolute_includee_file_path)
+      output_lines.push(MarkdownHelper.comment(" >>>>>> BEGIN INCLUDED FILE (#{treatment}): SOURCE #{includee_path_in_project} ")) unless markdown_helper.pristine
+      begin
+        include_lines = File.readlines(new_inclusion.absolute_includee_file_path)
+      rescue => e
+        inclusions.push(new_inclusion)
+        message = [
+            MISSING_INCLUDEE_EXCEPTION_LABEL,
+            backtrace_inclusions,
+        ].join("\n")
+        e = MissingIncludeeError.new(message)
+        e.set_backtrace([])
+        raise e
+      end
+      unless include_lines.last.match("\n")
+        message = "Warning:  Included file has no trailing newline: #{cited_includee_file_path}"
+        warn(message)
+      end
+      case treatment
+        when :markdown
+          # Pass through unadorned, but honor any nested includes.
+          inclusions.push(new_inclusion)
+          markdown_helper.send(:include_files, new_inclusion.absolute_includee_file_path, include_lines, output_lines, self)
+          inclusions.pop
+        when :comment
+          output_lines.push(MarkdownHelper.comment(include_lines.join('')))
+        when :pre
+          output_lines.push("<pre>\n")
+          output_lines.push(include_lines.join(''))
+          output_lines.push("</pre>\n")
+        else
+          # Use the file name as a label.
+          file_name_line = format("```%s```:\n", File.basename(cited_includee_file_path))
+          output_lines.push(file_name_line)
+          # Put into code block.
+          language = treatment == :code_block ? '' : treatment
+          output_lines.push("```#{language}\n")
+          output_lines.push(*include_lines)
+          output_lines.push("```\n")
+      end
+      output_lines.push(MarkdownHelper.comment(" <<<<<< END INCLUDED FILE (#{treatment}): SOURCE #{includee_path_in_project} ")) unless markdown_helper.pristine
+    end
+
+    CIRCULAR_EXCEPTION_LABEL = 'Includes are circular:'
+    UNREADABLE_TEMPLATE_EXCEPTION_LABEL = 'Could not read template file.'
+    UNWRITABLE_OUTPUT_EXCEPTION_LABEL = 'Could not write markdown file.'
+    MISSING_INCLUDEE_EXCEPTION_LABEL = 'Could not read include file,'
+    LEVEL_LABEL = '    Level'
+    BACKTRACE_LABEL = '  Backtrace (innermost include first):'
+
+    def check_circularity(new_inclusion)
+      previous_inclusions = inclusions.collect {|x| x.real_includee_file_path}
+      previously_included = previous_inclusions.include?(new_inclusion.real_includee_file_path)
+      if previously_included
+        inclusions.push(new_inclusion)
+        message = [
+            CIRCULAR_EXCEPTION_LABEL,
+            backtrace_inclusions,
+            ].join("\n")
+        e = MarkdownHelper::CircularIncludeError.new(message)
+        e.set_backtrace([])
+        raise e
+      end
+    end
+
+    def backtrace_inclusions
+      lines = [BACKTRACE_LABEL]
+      inclusions.reverse.each_with_index do |inclusion, i|
+        lines.push("#{LEVEL_LABEL} #{i}:")
+        level_lines = inclusion.to_lines(indentation_level = 3)
+        lines.push(*level_lines)
+      end
+      lines.join("\n")
+    end
+
+    def self.assert_io_exception(test, expected_exception_class, exception_label, e)
+      test.assert_kind_of(expected_exception_class, e)
+      lines = e.message.split("\n")
+      _ = lines.shift # Message from original exception.
+      label_line = lines.shift
+      test.assert_equal(exception_label, label_line)
+    end
+
+    def self.assert_inclusion_exception(test, expected_exception_class, exception_label, expected_inclusions, e)
+      test.assert_kind_of(expected_exception_class, e)
+      lines = e.message.split("\n")
+      label_line = lines.shift
+      test.assert_equal(exception_label, label_line)
+      backtrace_line = lines.shift
+      test.assert_equal(BACKTRACE_LABEL, backtrace_line)
+      level_line_count = 1 + Inclusion::LINE_COUNT
+      level_count = lines.size / level_line_count
+      # Backtrace levels are innermost first, opposite of inclusions.
+      reversed_inclusions = expected_inclusions.inclusions.reverse
+      (0...level_count).each do |level_index|
+        level_line = lines.shift
+        inclusion_lines = lines.shift(Inclusion::LINE_COUNT)
+        test.assert_equal("#{LEVEL_LABEL} #{level_index}:", level_line)
+        expected_inclusion = reversed_inclusions[level_index]
+        expected_inclusion.assert_lines(test, level_index, inclusion_lines)
+      end
+    end
+
+    def self.assert_circular_exception(test, expected_inclusions, e)
+      self.assert_inclusion_exception(
+              test,
+              CircularIncludeError,
+              CIRCULAR_EXCEPTION_LABEL,
+              expected_inclusions,
+              e
+      )
+    end
+
+    def self.assert_includee_missing_exception(test, expected_inclusions, e)
+      self.assert_inclusion_exception(
+          test,
+          Exception,
+          MISSING_INCLUDEE_EXCEPTION_LABEL,
+          expected_inclusions,
+          e
+      )
+    end
+
+    def self.assert_template_exception(test, e)
+      self.assert_io_exception(
+          test,
+          Exception,
+          UNREADABLE_TEMPLATE_EXCEPTION_LABEL,
+          e
+      )
+    end
+
+    def self.assert_output_exception(test, e)
+      self.assert_io_exception(
+          test,
+          Exception,
+          UNWRITABLE_OUTPUT_EXCEPTION_LABEL,
+          e
+      )
     end
 
   end
 
   class Inclusion
 
+    LINE_COUNT = 5
+
     attr_accessor \
       :includer_file_path,
       :includer_line_number,
-      :relative_included_file_path,
-      :included_file_path,
-      :included_real_path
+      :include_description,
+      :absolute_includee_file_path,
+      :cited_includee_file_path,
+      :include_description
 
     def initialize(
+        include_description,
         includer_file_path,
         includer_line_number,
-        relative_included_file_path
+        cited_includee_file_path
     )
-      included_file_path = File.join(
-          File.dirname(includer_file_path),
-          relative_included_file_path,
-      )
+      self.include_description = include_description
       self.includer_file_path = includer_file_path
       self.includer_line_number = includer_line_number
-      self.relative_included_file_path = relative_included_file_path
-      self.included_file_path = included_file_path
-      self.included_real_path = Pathname.new(included_file_path).realpath.to_s
+      self.cited_includee_file_path = cited_includee_file_path
+      self.absolute_includee_file_path = absolute_includee_file_path
+      self.absolute_includee_file_path = File.absolute_path(File.join(
+          File.dirname(includer_file_path),
+          cited_includee_file_path,
+      ))
+    end
+
+    def real_includee_file_path
+      # Would raise exception unless exists.
+      return nil unless File.exist?(absolute_includee_file_path)
+      Pathname.new(absolute_includee_file_path).realpath.to_s
+    end
+
+    def to_lines(indentation_level)
+      def indentation(level)
+        '  ' * level
+      end
+      relative_inluder_file_path = MarkdownHelper.path_in_project(includer_file_path)
+      relative_inludee_file_path = MarkdownHelper.path_in_project(absolute_includee_file_path)
+       text = <<EOT
+#{indentation(indentation_level)}Includer:
+#{indentation(indentation_level+1)}Location: #{relative_inluder_file_path}:#{includer_line_number}
+#{indentation(indentation_level+1)}Include description: #{include_description}
+#{indentation(indentation_level)}Includee:
+#{indentation(indentation_level+1)}File path: #{relative_inludee_file_path}
+EOT
+      text.split("\n")
+    end
+
+    def assert_lines(test, level_index, actual_lines)
+      level_label = "Level #{level_index}:"
+      # Includer label.
+      includee_label = actual_lines.shift
+      test.assert_match(/^\s*Includer:$/, includee_label, level_label)
+      # Includer locatioin.
+      location = actual_lines.shift
+      message = "#{level_label} includer location"
+      test.assert_match(/^\s*Location:/, location, message)
+      includer_realpath =  Pathname.new(includer_file_path).realpath.to_s
+      relative_path = MarkdownHelper.path_in_project(includer_realpath)
+      r = Regexp.new(Regexp.escape("#{relative_path}:#{includer_line_number}") + '$')
+      test.assert_match(r, location, message)
+      # Include description.
+      description = actual_lines.shift
+      message = "#{level_label} include description"
+      test.assert_match(/^\s*Include description:/, description, message)
+      r = Regexp.new(Regexp.escape("#{include_description}") + '$')
+      test.assert_match(r, description, message)
+      # Includee label.
+      includee_label = actual_lines.shift
+      test.assert_match(/^\s*Includee:$/, includee_label, level_label)
+      # Includee file path.
+      includee_file_path = actual_lines.shift
+      message = "#{level_label} includee cited file path"
+      test.assert_match(/^\s*File path:/, includee_file_path, message)
+      relative_path = MarkdownHelper.path_in_project(absolute_includee_file_path)
+      r = Regexp.new(Regexp.escape("#{relative_path}") + '$')
+      test.assert_match(r, includee_file_path, message)
     end
 
   end