markdown_helper 1.9.0 → 1.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8845145b2e85dd7e7420a4fd9c9c96d5795f01e
-  data.tar.gz: 088ef4f4cdb02275f43f2c99441f27f34e67e24d
+  metadata.gz: f37bc35a877f0cbad86a8441204b6c1d8a6af34c
+  data.tar.gz: d56f7ef795b3e7d382ba2a2cd32e5d1461252999
 SHA512:
-  metadata.gz: aa95f50a350189ee1caf1987dabc3b6ebd28f65ee6e5e1d53db52ab57102dfa0543212c8d81d6e5dce78c641cc6b50dc34193ab84cdc1b54468af411906fa0db
-  data.tar.gz: 72ccd0a952302199225dd553c1cd071f70790bd574a0ecfec5e887f771536225e418c93630483b6df92a98cb03db54a289ee1c1ad315c8511fad2346ecf12bac
+  metadata.gz: bcbbe35a306f7689ae6dbc65884f9f4b43e3085fbe1c4181e4ccac405ab43f84a962e8290baf961be1fa633403eadf66e8c07eb5c1eb90d13d9cce2d221cb022
+  data.tar.gz: dd5a5f2b96c308f817999412ef138e205d3418032f4162fb1b318828c8b3fa02e18f44e10a6b2f02b5cd33e55d06839ead8fafa60d40361fc5eec44db9ad9927

data/Gemfile.lock

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

data/README.md

@@ -10,25 +10,18 @@
 
 ## What's New?
 
-* The helper now checks whether the working directory is in a ```git``` project, and raises an exception if not.
-
-* There is now a backtrace of inclusions when:
-  * An includee file cannot be read.
-  * A circular inclusion (direct or indirect) is found.
-* The backtrace shows:
-  * Each includer file path.
-  * Its include description.
-  * The includee file path.
-* File paths are relative to the git directory.
-* Use cases are added:
-  * [Diagnose Missing Includee](markdown/use_cases/include/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
-  * [Diagnose Circular Includes](markdown/use_cases/include/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
+Page TOC:
+
+- Support is added for creating the table of contents for a markdown page.
+- The TOC is a tree of links to the headers on the page, suitable for inclusion with the page itself.
+- See the [use case](markdown/use_cases/tables_of_contents/create_and_include_page_toc/use_case.md#create-and-include-page-toc).
 
 ## 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 the table of contents for a markdown page.
 * [Image path resolution](#image-path-resolution): to resolve relative image paths to absolute URL paths (so they work even in gem documentation).
 * [Image attributes](#image-attributes): image attributes are passed through to an HTML <code>img</code> tag.
 
@@ -66,6 +59,8 @@ This markdown helper enables file inclusion in GitHub markdown.
 
 Use the markdown helper to merge external files into a markdown (</code>.md</code>) file.
 
+See the [use cases](markdown/use_cases/use_cases.md#use-cases).
+
 ### Merged Text Formats
 
 #### Highlighted Code Block
@@ -177,6 +172,14 @@ where:
 ```
 <!-- <<<<<< END INCLUDED FILE (code_block): SOURCE markdown/readme/include.md -->
 
+## Page TOC
+
+The markdown helper can create the table of contents for a markdown page.
+- The TOC is a tree of links to the headers on the page, suitable for inclusion with the page itself.
+- See the [use case](markdown/use_cases/tables_of_contents/create_and_include_page_toc/use_case.md#create-and-include-page-toc).
+
+
+
 ## Image Path Resolution 
 
 <!-- >>>>>> BEGIN RESOLVED IMAGES: INPUT-LINE '![image_icon](../../images/image.png | width=50)
@@ -349,7 +352,6 @@ where:
 
 I have opened some enhancement Issues in the GitHub [markdown_helper](https://github.com/BurdetteLamar/markdown_helper) project:
 
-* [File TOC](https://github.com/BurdetteLamar/markdown_helper/issues/36):  table of contents of all headers in a markdown page.
 * [Project TOC](https://github.com/BurdetteLamar/markdown_helper/issues/37):  table of contents of all markdown pages in project.
 * [Partial file inclusion](https://github.com/BurdetteLamar/markdown_helper/issues/38):  including only specified lines from a file (instead of the whole file).
 * [Ruby-entity inclusion](https://github.com/BurdetteLamar/markdown_helper/issues/39):  like file inclusion, but including a Ruby class, module, or method.

data/Rakefile

@@ -33,6 +33,7 @@ namespace :build do
   desc 'Build usage for executables'
   task :usages do
     %w/
+        create_page_toc
         include
         resolve
     /.each do |executable_name|

data/bin/_create_page_toc

@@ -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 create_page_toc [options] markdown_file_path toc_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
+
+    * markdown_file_path is the path to an existing markdown file.
+    * toc_file_path is the path to the table-of-contents file to be created.
+
+  Typically:
+
+    * Both file types are .md.
+    * The markdown file contains various headings.
+EOT
+  exit
+end
+
+parser.parse!
+
+_, markdown_file_path, toc_file_path = ARGV
+
+usage(opts) unless ARGV.size == 3
+
+MarkdownHelper.new(options).create_page_toc(markdown_file_path, toc_file_path)

data/bin/usage/create_page_toc.txt

@@ -0,0 +1,14 @@
+
+Usage: markdown_helper create_page_toc [options] markdown_file_path toc_file_path
+        --pristine                   No comments added
+        --help                       Display help
+    
+  where
+
+    * markdown_file_path is the path to an existing markdown file.
+    * toc_file_path is the path to the table-of-contents file to be created.
+
+  Typically:
+
+    * Both file types are .md.
+    * The markdown file contains various headings.

data/lib/markdown_helper.rb

@@ -9,7 +9,8 @@ class MarkdownHelper
 
   class MarkdownHelperError < RuntimeError; end
   class CircularIncludeError < MarkdownHelperError; end
-  class MissingIncludeeError < MarkdownHelperError; end
+  class UnreadableInputError < MarkdownHelperError; end
+  class TocHeadingsError < MarkdownHelperError; end
   class OptionError < MarkdownHelperError; end
   class EnvironmentError < MarkdownHelperError; end
 
@@ -54,6 +55,12 @@ class MarkdownHelper
     end
   end
 
+  def create_page_toc(markdown_file_path, toc_file_path)
+    send(:generate_file, markdown_file_path, toc_file_path, __method__) do |input_lines, output_lines|
+      send(:_create_page_toc, input_lines, output_lines)
+    end
+  end
+
   # Resolves relative image paths to absolute urls in markdown text.
   # @param template_file_path [String] the path to the input template markdown file, usually containing image pragmas.
   # @param markdown_file_path [String] the path to the output resolved markdown file.
@@ -85,6 +92,35 @@ class MarkdownHelper
 
   private
 
+  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
+      anchor = title.gsub(/\W+/, '-').downcase
+      "[#{title}](##{anchor})"
+    end
+
+  end
+
   def self.comment(text)
     "<!--#{text}-->\n"
   end
@@ -100,39 +136,41 @@ class MarkdownHelper
   end
 
   def generate_file(template_file_path, markdown_file_path, method)
+    unless File.readable?(template_file_path)
+      message = [
+          Inclusions::UNREADABLE_INPUT_EXCEPTION_LABEL,
+          template_file_path.inspect,
+      ].join("\n")
+      raise UnreadableInputError.new(message)
+    end
     output_lines = []
-    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
+    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
-    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)
+    output = output_lines.join('')
+    File.write(markdown_file_path, output)
+    output
+  end
+
+  def _create_page_toc(input_lines, output_lines)
+    level_one_seen = false
+    input_lines.each do |input_line|
+      input_line.chomp!
+      heading = Heading.parse(input_line)
+      next unless heading
+      unless level_one_seen || heading.level == 1
+        message = "First heading must be level 1, not '#{input_line}'"
+        raise TocHeadingsError.new(message)
       end
-      raise e
+      level_one_seen = true
+      indentation = '  ' * heading.level
+      output_line = "#{indentation}- #{heading.link}"
+      output_lines.push("#{output_line}\n")
     end
-    output
   end
 
   def include_files(includer_file_path, input_lines, output_lines, inclusions)
@@ -284,11 +322,12 @@ EOT
             MISSING_INCLUDEE_EXCEPTION_LABEL,
             backtrace_inclusions,
         ].join("\n")
-        e = MissingIncludeeError.new(message)
+        e = UnreadableInputError.new(message)
         e.set_backtrace([])
         raise e
       end
-      unless include_lines.last.match("\n")
+      last_line = include_lines.last
+      unless last_line && last_line.match("\n")
         message = "Warning:  Included file has no trailing newline: #{cited_includee_file_path}"
         warn(message)
       end
@@ -318,8 +357,8 @@ EOT
     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.'
+    UNREADABLE_INPUT_EXCEPTION_LABEL = 'Could not read input file.'
+    UNWRITABLE_OUTPUT_EXCEPTION_LABEL = 'Could not write output file.'
     MISSING_INCLUDEE_EXCEPTION_LABEL = 'Could not read include file,'
     LEVEL_LABEL = '    Level'
     BACKTRACE_LABEL = '  Backtrace (innermost include first):'
@@ -349,12 +388,13 @@ EOT
       lines.join("\n")
     end
 
-    def self.assert_io_exception(test, expected_exception_class, exception_label, e)
+    def self.assert_io_exception(test, expected_exception_class, expected_label, expected_file_path, 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)
+      actual_label = lines.shift
+      test.assert_equal(expected_label, actual_label)
+      actual_file_path = lines.shift
+      test.assert_equal(expected_file_path.inspect, actual_file_path)
     end
 
     def self.assert_inclusion_exception(test, expected_exception_class, exception_label, expected_inclusions, e)
@@ -397,20 +437,12 @@ EOT
       )
     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)
+    def self.assert_template_exception(test, expected_file_path, e)
       self.assert_io_exception(
           test,
           Exception,
-          UNWRITABLE_OUTPUT_EXCEPTION_LABEL,
+          UNREADABLE_INPUT_EXCEPTION_LABEL,
+          expected_file_path,
           e
       )
     end

data/lib/markdown_helper/version.rb

@@ -1,3 +1,3 @@
 class MarkdownHelper
-  VERSION = '1.9.0'
+  VERSION = '1.9.5'
 end

data/lib/string_helper.rb

@@ -0,0 +1,14 @@
+class StringHelper
+
+  def self.to_title(s)
+    small_words = %w{a an and the or for of nor}
+    title_words = []
+    s.split('_').each_with_index do |word, i|
+      word.capitalize! unless small_words.include?(word)
+      word.capitalize! if i == 0
+      title_words.push(word)
+    end
+    title_words.join(' ')
+  end
+
+end

data/markdown/readme/README.template.md

@@ -4,25 +4,18 @@
 
 ## What's New?
 
-* The helper now checks whether the working directory is in a ```git``` project, and raises an exception if not.
-
-* There is now a backtrace of inclusions when:
-  * An includee file cannot be read.
-  * A circular inclusion (direct or indirect) is found.
-* The backtrace shows:
-  * Each includer file path.
-  * Its include description.
-  * The includee file path.
-* File paths are relative to the git directory.
-* Use cases are added:
-  * [Diagnose Missing Includee](markdown/use_cases/include/diagnose_missing_includee/use_case.md#diagnose-missing-includee).
-  * [Diagnose Circular Includes](markdown/use_cases/include/diagnose_circular_includes/use_case.md#diagnose-circular-includes).
+Page TOC:
+
+- Support is added for creating the table of contents for a markdown page.
+- The TOC is a tree of links to the headers on the page, suitable for inclusion with the page itself.
+- See the [use case](markdown/use_cases/tables_of_contents/create_and_include_page_toc/use_case.md#create-and-include-page-toc).
 
 ## 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 the table of contents for a markdown page.
 * [Image path resolution](#image-path-resolution): to resolve relative image paths to absolute URL paths (so they work even in gem documentation).
 * [Image attributes](#image-attributes): image attributes are passed through to an HTML <code>img</code> tag.
 
@@ -56,6 +49,8 @@ This markdown helper enables file inclusion in GitHub markdown.
 
 Use the markdown helper to merge external files into a markdown (</code>.md</code>) file.
 
+See the [use cases](markdown/use_cases/use_cases.md#use-cases).
+
 ### Merged Text Formats
 
 #### Highlighted Code Block
@@ -106,6 +101,14 @@ where:
 
 @[code_block](include.md)
 
+## Page TOC
+
+The markdown helper can create the table of contents for a markdown page.
+- The TOC is a tree of links to the headers on the page, suitable for inclusion with the page itself.
+- See the [use case](markdown/use_cases/tables_of_contents/create_and_include_page_toc/use_case.md#create-and-include-page-toc).
+
+
+
 ## Image Path Resolution 
 
 ![image_icon](../../images/image.png | width=50)
@@ -184,7 +187,6 @@ where:
 
 I have opened some enhancement Issues in the GitHub [markdown_helper](https://github.com/BurdetteLamar/markdown_helper) project:
 
-* [File TOC](https://github.com/BurdetteLamar/markdown_helper/issues/36):  table of contents of all headers in a markdown page.
 * [Project TOC](https://github.com/BurdetteLamar/markdown_helper/issues/37):  table of contents of all markdown pages in project.
 * [Partial file inclusion](https://github.com/BurdetteLamar/markdown_helper/issues/38):  including only specified lines from a file (instead of the whole file).
 * [Ruby-entity inclusion](https://github.com/BurdetteLamar/markdown_helper/issues/39):  like file inclusion, but including a Ruby class, module, or method.

data/markdown/use_cases/Rakefile

@@ -1,4 +1,5 @@
-require_relative 'include/include_use_case'
+require_relative 'include_files/include_use_case'
+require_relative '../../lib/string_helper'
 
 namespace :build do
 
@@ -19,7 +20,7 @@ EOT
       Dir.chdir(dir_path) do
         IncludeUseCase.write_interface_file
         use_case_dirs = {
-            :include => %w/
+            :include_files => %w/
                 reuse_text
                 include_with_added_comments
                 nest_inclusions
@@ -30,17 +31,21 @@ EOT
                 diagnose_missing_includee
                 diagnose_circular_includes
             /,
+            :tables_of_contents => %w/
+                create_and_include_page_toc
+            /,
             # :resolve => %w/
                 # resize_images
                 # resolve_with_added_comments
                 # gemify_images
-            # /
+            # /,
         }
         use_case_dirs.each_pair do |section, dir_names|
 
           # Header for section, if any dirs therein.
+          title = StringHelper.to_title(section.to_s).sub(/ toc$/i, ' TOC')
           use_case_file.puts(<<EOT
-## #{section.to_s.capitalize}
+## #{title}
 
 EOT
 ) unless dir_names.empty?
@@ -65,6 +70,7 @@ EOT
                   ensure
                   end
                 else
+                  p command
                   system(command)
                 end
               end