markdown_helper 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f87e472a6df990e637dacc06c4e6bc7daffd512634c69c4202e3d9d6f96bc43
-  data.tar.gz: 414fe00be28329fef09722912fffe9bb9a5bb1ba998c69432d68908219a639e3
+  metadata.gz: f530c806dbcaa0885c405efa0f663800b9afb5cd758c9b9ab182aa129a588b77
+  data.tar.gz: e53416b6a71deebd8c0dc6e11721eeeac8ee8bf18494c6fe66f8afb10a4f7bcc
 SHA512:
-  metadata.gz: b8a99c9e3a3b2ffa39abbf36fcf44a21650b19498849ed2d60e78e418792464c8efffe680c758c6f23b65bc95c4fdef67a97e894339a96d6196bc7c7d362851d
-  data.tar.gz: 861b07f382444226d6fcacf224e16da75e94a3822305592fbf9dba7b1d38f0686a0f890fc1914f33c8640c04f2bf3a3d39ecfd52014c39ae95b47d40ddc008b5
+  metadata.gz: d052b01dcb0903bfacfb0b5b87b6eb5fc95540796786bf9cc2afbe047413139b9556fe1b5bfd1c1f1548c657f532dcd6a6a609b45d506f0778719266d30591d9
+  data.tar.gz: 453e13f39dcd61fab4ac4217695518b972c6aeb7d00fecc826f1200aafad7d55c3f941873c49b45ce8674c23c44fa0e7f622f6a0e84ed069faba0afc33593c35

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_helper (2.3.0)
+    markdown_helper (2.4.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -3,11 +3,8 @@
 
 [![Gem](https://img.shields.io/gem/v/markdown_helper.svg?style=flat)](http://rubygems.org/gems/markdown_helper "View this project in Rubygems")
 
-## What's New?
-
-Inclusion of text as details is added.  See the [use case](markdown/use_cases/include_files/include_text_as_details/use_case.md#include-text-as-details).
-
 ## Contents
+- [Installation](#installation)
 - [What's a Markdown Helper?](#whats-a-markdown-helper)
 - [How It Works](#how-it-works)
   - [Restriction: ```git``` Only](#restriction-git-only)
@@ -33,14 +30,20 @@ Inclusion of text as details is added.  See the [use case](markdown/use_cases/in
       - ["Noisy" (Not Pristine)](#noisy-not-pristine)
       - [Missing Includee File](#missing-includee-file)
       - [Circular Inclusion](#circular-inclusion)
+- [Run ```irb```](#run-irb)
 - [What Should Be Next?](#what-should-be-next)
 
+## Installation
+
+```gem install markdown_helper```
+
 ## What's a Markdown Helper?
 
 Class <code>MarkdownHelper</code> supports:
 
 * [File inclusion](#file-inclusion): to include text from other files, as code-block or markdown.
 * [Page TOC](#page-toc): to create and insert the table of contents for a markdown page.
+* [Run irb](#run-irb): to execute Ruby snippets in the Ruby interactive shell (```irb```) and include the output in markdown.
 
 ## How It Works
 
@@ -73,41 +76,41 @@ See all [use cases](markdown/use_cases/use_cases.md#use-cases).
 
 ### Re-use Text
 
-Keep your markdown DRY (Don't Repeat Yourself) by re-using text.  See the [use case](markdown/use_cases/include_files/reuse_text/use_case.md#reuse-text).
+Keep your markdown DRY (Don't Repeat Yourself) by re-using text.  See the [use case](markdown/use_cases/include/reuse_text/use_case.md#reuse-text).
 
 ### Include Generated Text
 
-In particular, you can include text that's built during your "readme build."  See the [use case](markdown/use_cases/include_files/include_generated_text/use_case.md#include-generated-text).
+In particular, you can include text that's built during your "readme build."  See the [use case](markdown/use_cases/include/include_generated_text/use_case.md#include-generated-text).
 
 ### Nest Inclusions
 
-You can nest inclusions.  See the [use case](markdown/use_cases/include_files/nest_inclusions/use_case.md#nest-inclusions).
+You can nest inclusions.  See the [use case](markdown/use_cases/include/nest_inclusions/use_case.md#nest-inclusions).
 
 ### Merged Text Formats
 
 #### Markdown
 
-You can include text that is to be treated simply as markdown.  See the [use case](markdown/use_cases/include_files/include_markdown/use_case.md#include-markdown).
+You can include text that is to be treated simply as markdown.  See the [use case](markdown/use_cases/include/include_markdown/use_case.md#include-markdown).
 
 #### Highlighted Code Block
 
-You can include a code block that's to be highlighted.  See the [use case](markdown/use_cases/include_files/include_highlighted_code/use_case.md#include-highlighted-code).
+You can include a code block that's to be highlighted.  See the [use case](markdown/use_cases/include/include_highlighted_code/use_case.md#include-highlighted-code).
 
 #### Plain Code Block
 
-You can also include a code block without highlighting.  See the [use case](markdown/use_cases/include_files/include_code_block/use_case.md#include-code-block).
+You can also include a code block without highlighting.  See the [use case](markdown/use_cases/include/include_code_block/use_case.md#include-code-block).
 
 #### Comment
 
-You can include text that's to become a comment in the markdown.  See the [use case](markdown/use_cases/include_files/include_text_as_comment/use_case.md#include-text-as-comment).
+You can include text that's to become a comment in the markdown.  See the [use case](markdown/use_cases/include/include_text_as_comment/use_case.md#include-text-as-comment).
 
 #### Details
 
-You can include text that's to become details in the markdown.  See the [use case](markdown/use_cases/include_files/include_text_as_details/use_case.md#include-text-as-details).
+You can include text that's to become details in the markdown.  See the [use case](markdown/use_cases/include/include_text_as_details/use_case.md#include-text-as-details).
 
 ### Pre-Formatted Text
 
-You can include text that's pre-formatted.  See the [use case](markdown/use_cases/include_files/include_text_as_pre/use_case.md#include-text-as-pre).
+You can include text that's pre-formatted.  See the [use case](markdown/use_cases/include/include_text_as_pre/use_case.md#include-text-as-pre).
 
 ### Usage
 
@@ -188,21 +191,25 @@ where:
 
 #### Page TOC
 
-You can specify the location for an automatically-generated page TOC (table of cotents).  See the [use case](markdown/use_cases/include_files/include_page_toc/use_case.md#include-page-toc).
+You can specify the location for an automatically-generated page TOC (table of cotents).  See the [use case](markdown/use_cases/include/include_page_toc/use_case.md#include-page-toc).
 
 #### Diagnostics
 
 ##### "Noisy" (Not Pristine)
 
-By default, the markdown helper inserts comments indicating inclusions.  See the [use case](markdown/use_cases/include_files/include_with_added_comments/use_case.md#include-with-added-comments).
+By default, the markdown helper inserts comments indicating inclusions.  See the [use case](markdown/use_cases/include/include_with_added_comments/use_case.md#include-with-added-comments).
 
 ##### Missing Includee File
 
-A missing includee file causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include_files/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
+A missing includee file causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
 
 ##### Circular Inclusion
 
-A circular inclusion causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include_files/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
+A circular inclusion causes an exception that shows an inclusion backtrace.  See the [use case](markdown/use_cases/include/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
+
+## Run ```irb```
+
+* Execute Ruby snippets in the Ruby interactive shell (```irb```) and include the output in markdown.  See the [use case](markdown/use_cases/run_irb/run_irb/use_case.md#run-irb).
 
 ## What Should Be Next?
 

data/bin/_run_irb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+
+require 'markdown_helper'
+
+options = {:pristine => false}
+
+# Save opts for use below.
+opts = nil
+parser = OptionParser.new do |_opts|
+  opts = _opts
+  _opts.banner = "Usage: markdown_helper run_irb [options] template_file_path markdown_file_path"
+  _opts.on('--pristine', 'No comments added') do |_|
+    options[:pristine] = true
+  end
+  _opts.on('--help', 'Display help') do
+    usage(_opts)
+  end
+end
+
+def usage(opts)
+  puts ''
+  puts opts
+  puts <<-EOT
+    
+  where
+
+    * template_file_path is the path to an existing file.
+    * markdown_file_path is the path to a file to be created.
+
+  Typically:
+
+    * Both file types are .md.
+    * The template file contains code blocks to be run in irb.
+EOT
+  exit
+end
+
+parser.parse!
+
+_, template_file_path, markdown_file_path = ARGV
+
+usage(opts) unless ARGV.size == 3
+
+MarkdownHelper.new(options).run_irb(template_file_path, markdown_file_path)

data/lib/markdown_helper.rb

@@ -1,384 +1,3 @@
-require 'pathname'
-
-require 'markdown_helper/version'
-
-class MarkdownHelper
-
-  class MarkdownHelperError < RuntimeError; end
-  class OptionError < MarkdownHelperError; end
-  class MultiplePageTocError < MarkdownHelperError; end
-  class InvalidTocTitleError < MarkdownHelperError; end
-  class UnreadableTemplateError < MarkdownHelperError; end
-  class UnwritableMarkdownError < MarkdownHelperError; end
-  class CircularIncludeError < MarkdownHelperError; end
-  class UnreadableIncludeeError < MarkdownHelperError; end
-
-  INCLUDE_REGEXP = /^@\[([^\[]+)\]\(([^)]+)\)$/
-  INCLUDE_MARKDOWN_REGEXP = /^@\[:markdown\]\(([^)]+)\)$/
-
-  attr_accessor :pristine
-
-  def initialize(options = {})
-    # Confirm that we're in a git project.
-    # This is necessary so that we can prune file paths in the tests,
-    # which otherwise would fail because of differing installation directories.
-    # It also allows pruned paths to be used in the inserted comments (when not pristine).
-    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 OptionError.new("Unknown option: #{method}")
-      end
-      setter_method = "#{method}="
-      send(setter_method, value)
-      merged_options.delete(method)
-    end
-    @inclusions = []
-  end
-
-  def include(template_file_path, markdown_file_path)
-    send(:generate_file, template_file_path, markdown_file_path) do |output_lines|
-      Dir.chdir(File.dirname(template_file_path)) do
-        markdown_lines = include_markdown(template_file_path)
-        markdown_lines = include_page_toc(markdown_lines)
-        include_all(template_file_path, markdown_lines, output_lines)
-      end
-    end
-  end
-
-  private
-
-  def generate_file(template_file_path, markdown_file_path)
-    template_path_in_project = MarkdownHelper.path_in_project(template_file_path)
-    output_lines = []
-    yield output_lines
-    unless pristine
-      output_lines.unshift(MarkdownHelper.comment(" >>>>>> BEGIN GENERATED FILE (include): SOURCE #{template_path_in_project} "))
-      output_lines.push(MarkdownHelper.comment(" <<<<<< END GENERATED FILE (include): SOURCE #{template_path_in_project} "))
-    end
-    output_lines.push('')
-    output = output_lines.join("\n")
-    File.write(markdown_file_path, output)
-  end
-
-  def include_markdown(template_file_path)
-    Dir.chdir(File.dirname(template_file_path)) do
-      markdown_lines = []
-      unless File.readable?(template_file_path)
-        path_in_project = MarkdownHelper.path_in_project(template_file_path )
-        message = [
-            "Could not read template file: #{path_in_project}",
-            MarkdownHelper.backtrace_inclusions(@inclusions),
-        ].join("\n")
-        e = UnreadableTemplateError.new(message)
-        e.set_backtrace([])
-        raise e
-      end
-      template_lines = File.readlines(template_file_path)
-      template_lines.each_with_index do |template_line, i|
-        template_line.chomp!
-        treatment, includee_file_path = *parse_include(template_line)
-        if treatment.nil?
-          markdown_lines.push(template_line)
-          next
-        end
-        if treatment == ':page_toc'
-          markdown_lines.push(template_line)
-          next
-        end
-        inclusion = Inclusion.new(
-            template_file_path,
-            template_line,
-            i,
-            treatment,
-            includee_file_path,
-            @inclusions
-            )
-        case treatment
-        when ':markdown'
-          check_includee(inclusion)
-          check_circularity(inclusion)
-          @inclusions.push(inclusion)
-          includee_lines = include_markdown(File.absolute_path(includee_file_path))
-          markdown_lines.concat(includee_lines)
-        when ':comment'
-          text = File.read(includee_file_path)
-          markdown_lines.push(MarkdownHelper.comment(text))
-          @inclusions.push(inclusion)
-        when ':pre'
-          text = File.read(includee_file_path)
-          markdown_lines.push(MarkdownHelper.pre(text))
-          @inclusions.push(inclusion)
-        when ':details'
-          text = File.read(includee_file_path)
-          markdown_lines.push(MarkdownHelper.details(text))
-          @inclusions.push(inclusion)
-        else
-          markdown_lines.push(template_line)
-          next
-        end
-        @inclusions.pop
-        treatment.sub!(/^:/, '')
-        add_inclusion_comments(treatment, includee_file_path, markdown_lines)
-      end
-      markdown_lines
-    end
-  end
-
-  def include_page_toc(template_lines)
-    toc_line_index = nil
-    toc_title = nil
-    template_lines.each_with_index do |template_line, i|
-      match_data = template_line.match(INCLUDE_REGEXP)
-      next unless match_data
-      treatment = match_data[1]
-      next unless treatment == ':page_toc'
-      unless toc_line_index.nil?
-        message = 'Multiple page TOC not allowed'
-        raise MultiplePageTocError.new(message)
-      end
-      toc_line_index = i
-      toc_title = match_data[2]
-      title_regexp = /^\#{1,6}\s/
-      unless toc_title.match(title_regexp)
-        message = "TOC title must be a valid markdown header, not #{toc_title}"
-        raise InvalidTocTitleError.new(message)
-      end
-    end
-    return template_lines unless toc_line_index
-    toc_lines = [toc_title]
-    first_heading_level = nil
-    template_lines.each_with_index do |input_line, i|
-      next if i < toc_line_index
-      line = input_line.chomp
-      heading = Heading.parse(line)
-      next unless heading
-      first_heading_level ||= heading.level
-      indentation = '  ' * (heading.level - first_heading_level)
-      toc_line = "#{indentation}- #{heading.link}"
-      toc_lines.push(toc_line)
-    end
-    template_lines.delete_at(toc_line_index)
-    template_lines.insert(toc_line_index, *toc_lines)
-    template_lines
-  end
-
-  def include_all(template_file_path, template_lines, output_lines)
-    template_lines.each_with_index do |template_line, i|
-      treatment, includee_file_path = *parse_include(template_line)
-      if treatment.nil?
-        output_lines.push(template_line)
-        next
-      end
-      inclusion = Inclusion.new(
-          template_file_path,
-          template_line,
-          i,
-          treatment,
-          includee_file_path,
-          @inclusions
-      )
-      check_includee(inclusion)
-      @inclusions.push(inclusion)
-      file_marker = format('```%s```:', File.basename(includee_file_path))
-      begin_backticks = '```'
-      end_backticks = '```'
-      begin_backticks += treatment unless treatment.start_with?(':')
-      includee_lines = File.read(includee_file_path).split("\n")
-      includee_lines.unshift(begin_backticks)
-      includee_lines.unshift(file_marker)
-      includee_lines.push(end_backticks)
-      add_inclusion_comments(treatment.sub(':', ''), includee_file_path, includee_lines)
-      output_lines.concat(includee_lines)
-    end
-  end
-
-  def add_inclusion_comments(treatment, includee_file_path, lines)
-    path_in_project = MarkdownHelper.path_in_project(includee_file_path)
-    unless pristine
-      comment = format(' >>>>>> BEGIN INCLUDED FILE (%s): SOURCE %s ', treatment, path_in_project)
-      lines.unshift(MarkdownHelper.comment(comment))
-      comment = format(' <<<<<< END INCLUDED FILE (%s): SOURCE %s ', treatment, path_in_project)
-      lines.push(MarkdownHelper.comment(comment))
-    end
-  end
-
-  def parse_include(line)
-    match_data = line.match(INCLUDE_REGEXP)
-    return [nil, nil] unless match_data
-    treatment = match_data[1]
-    includee_file_path = match_data[2]
-    [treatment, includee_file_path]
-  end
-
-  def self.path_in_project(file_path)
-    abs_path = File.absolute_path(file_path)
-    abs_path.sub(self.git_clone_dir_path + '/', '')
-  end
-
-  def self.comment(text)
-    "<!--#{text}-->"
-  end
-
-  def self.pre(text)
-    "<pre>\n#{text}</pre>"
-  end
-
-  def self.details(text)
-    "<details>\n#{text}</details>"
-  end
-
-  def self.git_clone_dir_path
-    git_dir = `git rev-parse --show-toplevel`.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
-    git_dir
-  end
-
-  class Heading
-
-    attr_accessor :level, :title
-
-    def initialize(level, title)
-      self.level = level
-      self.title = title
-    end
-
-    def self.parse(line)
-      # Four leading spaces not allowed (but three are allowed).
-      return nil if line.start_with?(' ' * 4)
-      stripped_line = line.sub(/^ */, '')
-      # Now must begin with hash marks and space.
-      return nil unless stripped_line.match(/^#+ /)
-      hash_marks, title = stripped_line.split(' ', 2)
-      level = hash_marks.size
-      # Seventh level heading not allowed.
-      return nil if level > 6
-      self.new(level, title)
-    end
-
-
-    def link
-      remove_regexp = /[\#\(\)\[\]\{\}\.\?\+\*\`\"\']+/
-      to_hyphen_regexp = /\W+/
-      anchor = title.
-          gsub(remove_regexp, '').
-          gsub(to_hyphen_regexp, '-').
-          downcase
-      "[#{title}](##{anchor})"
-    end
-
-  end
-
-  def check_circularity(inclusion)
-    included_file_paths = @inclusions.collect { |x| x.includee_real_file_path}
-    previously_included = included_file_paths.include?(inclusion.includee_real_file_path)
-    if previously_included
-      @inclusions.push(inclusion)
-      message = [
-          'Includes are circular:',
-          MarkdownHelper.backtrace_inclusions(@inclusions),
-      ].join("\n")
-      e = MarkdownHelper::CircularIncludeError.new(message)
-      e.set_backtrace([])
-      raise e
-    end
-  end
-
-  def check_includee(inclusion)
-    unless File.readable?(inclusion.includee_absolute_file_path)
-      @inclusions.push(inclusion)
-      message = [
-          'Could not read includee file:',
-          MarkdownHelper.backtrace_inclusions(@inclusions),
-      ].join("\n")
-      e = MarkdownHelper::UnreadableIncludeeError.new(message)
-      e.set_backtrace([])
-      raise e
-    end
-
-  end
-
-  def self.backtrace_inclusions(inclusions)
-    lines = ['  Backtrace (innermost include first):']
-    inclusions.reverse.each_with_index do |inclusion, i|
-      lines.push("#{'    Level'} #{i}:")
-      level_lines = inclusion.to_lines(indentation_level = 3)
-      lines.push(*level_lines)
-    end
-    lines.join("\n")
-  end
-
-  class Inclusion
-
-    attr_accessor \
-      :includer_file_path,
-      :includer_absolute_file_path,
-      :include_pragma,
-      :treatment,
-      :includer_line_number,
-      :cited_includee_file_path,
-      :includee_absolute_file_path
-
-    def initialize(
-        includer_file_path,
-        include_pragma,
-        includer_line_number,
-        treatment,
-        cited_includee_file_path,
-        inclusions
-        )
-      self.includer_file_path = includer_file_path
-      self.include_pragma = include_pragma
-      self.includer_line_number = includer_line_number
-      self.treatment = treatment
-      self.cited_includee_file_path = cited_includee_file_path
-
-      self.includer_absolute_file_path = File.absolute_path(includer_file_path)
-      unless File.exist?(self.includer_absolute_file_path)
-        fail self.includer_absolute_file_path
-      end
-
-      self.includee_absolute_file_path = File.absolute_path(File.join(
-          File.dirname(includer_file_path),
-          cited_includee_file_path,
-          ))
-    end
-
-    def includer_real_file_path
-      Pathname.new(includer_absolute_file_path).realpath.to_s
-    end
-
-    def includee_real_file_path
-      Pathname.new(includee_absolute_file_path).realpath.to_s
-    end
-
-    def indentation(level)
-      '  ' * level
-    end
-
-    def to_lines(indentation_level)
-      relative_inluder_file_path = MarkdownHelper.path_in_project(includer_file_path)
-      relative_inludee_file_path = MarkdownHelper.path_in_project(includee_absolute_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 pragma: #{include_pragma}
-#{indentation(indentation_level)}Includee:
-#{indentation(indentation_level+1)}File path: #{relative_inludee_file_path}
-EOT
-      text.split("\n")
-    end
-
-  end
-
-end
+require 'markdown_helper/markdown_helper'
+require 'markdown_helper/markdown_includer'
+require 'markdown_helper/markdown_irb_runner'