mdtoc 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae0f7d7fa8f96a2d68073f0fbc5a0b92f8ac8182b82fbd2a7bcabb074449d525
-  data.tar.gz: a0af9901b92c93dc3eea21ddae16fa349f7be653945f51e9867d2f69efc1073a
+  metadata.gz: 4b54718ab7b2f7bbc8e90ae473318895665986e0a7408674670db03294f12d6e
+  data.tar.gz: f1b251a78ba55942f8c85d82b99f614d3b9368541b7dcb1f144d1094e293d01f
 SHA512:
-  metadata.gz: 350566fff5655c9ab17502f02992c23d04e23d844cd94a6c25788d9c745142135f3cc2a1d41e7b7cc6a691caf209edfb9f689816d2b3a1379a75f061a756fddc
-  data.tar.gz: 33af4aeb021e9b61bb111ab2c20904f1af90afb4bf5c62361fea8e08d3bb21fcde68a9dc45b1863035f321db4a23a367898b9648f270931394c76e3437562140
+  metadata.gz: 247816469ed9798906c93e6ca0c58bd4b863d379795d9f776b71fc6c7d3835d7eb4ee890372a408ee04981658336a5f924156d85456e66d90793e0d58b7bd9e2
+  data.tar.gz: 2c10991bfa7f4b95896d468f803bae94b44899fc695c1113bd6fa6d7d90c784f4303939a7c2637ed70cd6335bf51f66688d6c932b03a6c0d284f5060cc009646

data/lib/mdtoc.rb

@@ -4,7 +4,6 @@
 require 'optparse'
 require 'tempfile'
 require_relative 'mdtoc/cli'
-require_relative 'mdtoc/markdown'
 require_relative 'mdtoc/node'
 require_relative 'mdtoc/writer'
 
@@ -14,8 +13,8 @@ module Mdtoc
 
     sig { params(args: T::Array[String]).void }
     def main(args)
-      options = Mdtoc::CLI::Options.for_args(args)
-      toc = render_toc(options.paths)
+      options = Mdtoc::CLI.parse(args)
+      toc = Mdtoc::Node.render(options.paths)
       unless options.output
         puts toc
         return
@@ -23,17 +22,6 @@ module Mdtoc
 
       Mdtoc::Writer.write(toc, T.must(options.output), options.append, options.create)
     end
-
-    private
-
-    sig { params(paths: T::Array[String]).returns(String) }
-    def render_toc(paths)
-      paths
-        .map { |path| Mdtoc::Node.for_path(path).headers }
-        .flatten(1)
-        .map(&:to_s)
-        .join("\n")
-    end
   end
 end
 

data/lib/mdtoc/cli.rb

@@ -4,26 +4,14 @@
 require 'optparse'
 require 'sorbet-runtime'
 require 'tempfile'
-require_relative 'markdown'
-require_relative 'node'
-require_relative 'writer'
 
 module Mdtoc
   module CLI
-    class Options < T::Struct
+    class << self
       extend T::Sig
 
-      prop :append, T::Boolean, default: false
-      prop :create, T::Boolean, default: false
-      prop :output, T.nilable(String)
-      prop :paths, T::Array[String], default: []
-
-      def []=(key, val)
-        send("#{key}=", val)
-      end
-
       sig { params(args: T::Array[String]).returns(Options) }
-      def self.for_args(args)
+      def parse(args)
         parser = OptionParser.new do |parser_|
           parser_.banner = "Usage: #{parser_.program_name} [options] files or directories..."
           parser_.on('-h', '--help', 'Show this message') do
@@ -44,5 +32,19 @@ module Mdtoc
         options
       end
     end
+
+    class Options < T::Struct
+      extend T::Sig
+
+      prop :append, T::Boolean, default: false
+      prop :create, T::Boolean, default: false
+      prop :output, T.nilable(String)
+      prop :paths, T::Array[String], default: []
+
+      sig { params(key: Symbol, val: T.untyped).returns(T.untyped) }
+      def []=(key, val)
+        send("#{key}=", val)
+      end
+    end
   end
 end

data/lib/mdtoc/markdown/header.rb

@@ -0,0 +1,41 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+
+module Mdtoc
+  module Markdown
+    class Header
+      extend T::Sig
+
+      sig { params(depth: Integer, label: String, url: String).void }
+      def initialize(depth, label, url)
+        if depth < 0
+          raise ArgumentError, "Header depth must be >= 0, but was #{depth}"
+        end
+        @depth = depth
+        @label = label.strip.gsub(/\s+/, ' ')
+        @url = url
+      end
+
+      sig { returns(String) }
+      def to_s
+        prefix = ' ' * 2 * @depth
+        "#{prefix}* [#{@label}](#{@url})"
+      end
+
+      sig { params(relative_to_depth: Integer).returns(T::Boolean) }
+      def top_level?(relative_to_depth)
+        @depth == relative_to_depth
+      end
+    end
+
+    class HeaderWithFragment < Header
+      sig { params(depth: Integer, label: String, url: String).void }
+      def initialize(depth, label, url)
+        url = "#{url}##{label.strip.downcase.tr(' ', '-').gsub(/[^\w\-]/, '')}"
+        super
+      end
+    end
+  end
+end

data/lib/mdtoc/{markdown.rb → markdown/parser.rb}

@@ -2,42 +2,10 @@
 # frozen_string_literal: true
 
 require 'sorbet-runtime'
+require_relative 'header'
 
 module Mdtoc
   module Markdown
-    class Header
-      extend T::Sig
-
-      sig { params(depth: Integer, label: String, url: String).void }
-      def initialize(depth, label, url)
-        if depth < 0
-          raise ArgumentError, "Header depth must be >= 0, but was #{depth}"
-        end
-        @depth = depth
-        @label = label.strip.gsub(/\s+/, ' ')
-        @url = url
-      end
-
-      sig { params(relative_to_depth: Integer).returns(T::Boolean) }
-      def top_level?(relative_to_depth)
-        @depth == relative_to_depth
-      end
-
-      sig { returns(String) }
-      def to_s
-        prefix = ' ' * 2 * @depth
-        "#{prefix}* [#{@label}](#{@url})"
-      end
-    end
-
-    class HeaderWithFragment < Header
-      sig { params(depth: Integer, label: String, url: String).void }
-      def initialize(depth, label, url)
-        url = "#{url}##{label.downcase.strip.gsub(/ /, '-').gsub(/[^\w\-_ ]/, '')}"
-        super
-      end
-    end
-
     class Parser
       extend T::Sig
 
@@ -65,7 +33,7 @@ module Mdtoc
 
       private
 
-      sig { params(line: String).returns(Header) }
+      sig { params(line: String).returns(HeaderWithFragment) }
       def header(line)
         m = T.must(line.strip.match(/^(#+)\s*(.*)$/))
         num_hashes = m[1]&.count('#') || 1

data/lib/mdtoc/node.rb

@@ -3,7 +3,8 @@
 
 require 'pathname'
 require 'sorbet-runtime'
-require_relative 'markdown'
+require_relative 'markdown/header'
+require_relative 'markdown/parser'
 
 module Mdtoc
   class Node
@@ -11,13 +12,24 @@ module Mdtoc
     extend T::Sig
     abstract!
 
-    sig { params(path: String, depth: Integer).returns(Node) }
-    def self.for_path(path, depth = 0)
-      # Ensure that `path` is a relative path, so that all links are relative and therefore portable.
-      path = Pathname.new(path)
-      path = path.relative_path_from(Dir.pwd) if path.absolute?
-      path = path.to_s
-      File.directory?(path) ? DirNode.new(path, depth) : FileNode.new(path, depth)
+    class << self
+      extend T::Sig
+
+      sig { params(path: String, depth: Integer).returns(Node) }
+      def for_path(path, depth = 0)
+        # Ensure that `path` is a relative path, so that all links are relative and therefore portable.
+        path = Pathname.new(path)
+        path = path.relative_path_from(Dir.pwd) if path.absolute?
+        path = path.to_s
+        File.directory?(path) ? DirNode.new(path, depth) : FileNode.new(path, depth)
+      end
+
+      sig { params(paths: T::Array[String]).returns(String) }
+      def render(paths)
+        paths
+          .flat_map { |path| for_path(path).headers }
+          .join("\n")
+      end
     end
 
     sig { params(path: String, depth: Integer).void }
@@ -26,13 +38,13 @@ module Mdtoc
       @depth = depth
     end
 
+    sig { abstract.returns(T::Array[Mdtoc::Markdown::Header]) }
+    def headers; end
+
     sig { returns(String) }
     def label
       File.basename(@path, File.extname(@path)).gsub(/_+/, ' ').gsub(/\s+/, ' ').capitalize
     end
-
-    sig { abstract.returns(T::Array[Mdtoc::Markdown::Header]) }
-    def headers; end
   end
 
   class DirNode < Node
@@ -41,11 +53,9 @@ module Mdtoc
       readme_path = T.let(nil, T.nilable(String))
       child_headers = Dir
         .each_child(@path)
-        .map { |path| File.join(@path, path) }
-        .reject { |path| readme_path = path if File.basename(path).downcase == 'readme.md' }
+        .reject { |path| readme_path = File.join(@path, path) if path.casecmp?('readme.md') }
         .sort!
-        .map { |path| Node.for_path(path, @depth + 1).headers }
-        .flatten(1)
+        .flat_map { |path| Node.for_path(File.join(@path, path), @depth + 1).headers }
       return child_headers unless readme_path
 
       # Include the headers from the README at the beginning.

data/lib/mdtoc/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Mdtoc
-  VERSION = '0.1.3'
+  VERSION = '0.1.4'
 end

data/lib/mdtoc/writer.rb

@@ -28,7 +28,7 @@ module Mdtoc
           f = File.open(path)
         rescue
           # If File.open failed because the file didn't exist, then we know that --create
-          # was specified due to the validation in self.validate_path.
+          # was specified due to the validation in validate_path.
           return "#{toc}\n"
         end
         begin
@@ -51,16 +51,14 @@ module Mdtoc
 
       sig { params(path: String, create: T::Boolean).void }
       def validate_path(path, create)
-        if path
-          if File.exist?(path)
-            unless File.file?(path)
-              warn("--output PATH \"#{path}\" is not a regular file")
-              exit
-            end
-          elsif !create
-            warn("--output PATH \"#{path}\" does not exist. Specify --create to create it.")
+        if File.exist?(path)
+          unless File.file?(path)
+            warn("--output PATH \"#{path}\" is not a regular file")
             exit
           end
+        elsif !create
+          warn("--output PATH \"#{path}\" does not exist. Specify --create to create it.")
+          exit
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mdtoc
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - andornaut
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-11-02 00:00:00.000000000 Z
+date: 2020-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -122,7 +122,101 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description:
+description: |
+  # mdtoc - Markdown Table of Contents
+
+  Read Markdown files and output a table of contents.
+
+  ## Installation
+
+  Requirements:
+
+  * [Ruby](https://www.ruby-lang.org/en/) (see [.ruby-version](./.ruby-version))
+
+  ```
+  $ gem install mdtoc
+  ```
+
+  ## Usage
+
+  ```
+  $ mdtoc --help
+  Usage: mdtoc [options] files or directories...
+      -h, --help                       Show this message
+      -o, --output PATH                Update a table of contents in the file at PATH
+      -a, --[no-]append                Append to the --output file if a <!-- mdtoc --> tag isn't found
+      -c, --[no-]create                Create the --output file if it does not exist
+  ```
+
+  1. Add a `<!-- mdtoc -->` tag to a Markdown file.
+    ```
+    $ echo '<!-- mdtoc -->` >> README.md
+    ```
+  2. Run `mdtoc` and specify input files or directories (eg. the "test/samples" directory) and an output file (eg. "README.md").
+    ```
+    $ mdtoc -aco README.md test/samples
+    ```
+
+  ## Example Rakefile
+
+  Run the [rake](https://github.com/ruby/rake) "mdtoc" task to update a table of contents.
+  See [andornaut/til](https://github.com/andornaut/til) for an example.
+
+  ```
+  task default: %w[mdtoc]
+
+  desc 'Update Markdown table of contents and push changes to the git repository'
+  task :mdtoc do |t|
+    command = <<~END
+      set -e
+      git pull
+      if [ -n "$(git diff --name-only --diff-filter=U)" ]; then
+        echo 'Error: conflicts exist' >&2
+        exit 1
+      fi
+      mdtoc --append --create --output README.md docs/
+      git add *.md **/*.md
+      git commit -m 'Update TOC'
+      git push
+    END
+    %x|#{command}|
+  end
+  ```
+
+  ## Development
+
+  ### Installation
+
+  Requirements:
+
+  * [Bundler](https://bundler.io/)
+
+  ```
+  # Install dependencies
+  $ bundle
+  ```
+
+  ### Usage
+
+  ```
+  # List rake tasks
+  $ rake -T
+  rake build                 # Build mdtoc-0.0.2.gem into the pkg directory
+  rake default               # Run the build, rubocop:auto_correct, sorbet and test tasks
+  rake install               # Build and install mdtoc-0.0.2.gem into system gems
+  rake install:local         # Build and install mdtoc-0.0.2.gem into system gems without...
+  rake release[remote]       # Create tag v0.0.2 and build and push mdtoc-0.0.2.gem to ru...
+  rake rubocop               # Run RuboCop
+  rake rubocop:auto_correct  # Auto-correct RuboCop offenses
+  rake sorbet                # Run the Sorbet type checker
+  rake test                  # Run tests
+
+  # Run mdtoc with test inputs
+  $ ruby -Ilib bin/mdtoc test/samples
+
+  # Run mdtoc with test inputs, and write to a newly created output file
+  $ f=$(mktemp) && ruby -Ilib bin/mdtoc -aco ${f} test/samples ; cat ${f}
+  ```
 email:
 executables:
 - mdtoc
@@ -132,19 +226,11 @@ files:
 - bin/mdtoc
 - lib/mdtoc.rb
 - lib/mdtoc/cli.rb
-- lib/mdtoc/markdown.rb
+- lib/mdtoc/markdown/header.rb
+- lib/mdtoc/markdown/parser.rb
 - lib/mdtoc/node.rb
 - lib/mdtoc/version.rb
 - lib/mdtoc/writer.rb
-- test/samples/README.md
-- test/samples/a/c.md
-- test/samples/a/d/f.md
-- test/samples/a/e.md
-- test/samples/a/g/README.md
-- test/samples/a/g/h.md
-- test/samples/a/readme.md
-- test/test_markdown.rb
-- test/test_node.rb
 homepage: https://github.com/andornaut/mdtoc
 licenses:
 - MIT

data/test/samples/README.md

@@ -1,18 +0,0 @@
-# Title
-intro text
- # Ignore this non-title
-    # ignore this non title
-```
-ignore this multi-line code block
-```
-```ignore this inline block```
-<!-- ignore this comment -->
-## 2
-### 3
-
-## 2
-text
-
-#### 4
-text
-## 2

data/test/samples/a/c.md

@@ -1,2 +0,0 @@
-# c 1
-## c 2

data/test/samples/a/d/f.md

@@ -1 +0,0 @@
-## f 2

data/test/samples/a/e.md

@@ -1 +0,0 @@
-# e 1

data/test/samples/a/g/README.md

@@ -1 +0,0 @@
-# README 1 for g

data/test/samples/a/g/h.md

@@ -1 +0,0 @@
-# h 1

data/test/samples/a/readme.md

@@ -1,4 +0,0 @@
-# readme 1
-## readme 2
-### readme 3
-#### readme 4

data/test/test_markdown.rb

@@ -1,127 +0,0 @@
-# typed: false
-# frozen_string_literal: true
-
-require "minitest/autorun"
-require "mdtoc/markdown"
-
-class TestHeader < Minitest::Test
-  def test_fragment_normalization
-    sample = [
-      'Spaces 1 space',
-      'Spaces  2 spaces',
-      "Spaces\t1 tab",
-      "Spaces\t\t2 tabs",
-      '    Spaces leading and trailing    ',
-      'Numbers 1234567890',
-      'Symbols -=~!@#$%^&',
-      'Symbols *()_+',
-      'Symbols <>?:"{}|[]\;\',./',
-    ]
-    expecteds = [
-      '/a#spaces-1-space',
-      '/a#spaces--2-spaces',
-      '/a#spaces1-tab',
-      '/a#spaces2-tabs',
-      '/a#spaces-leading-and-trailing',
-      '/a#numbers-1234567890',
-      '/a#symbols--',
-      '/a#symbols-_',
-      '/a#symbols-',
-    ]
-    actuals = sample.map do |label|
-      Mdtoc::Markdown::HeaderWithFragment.new(1, label, '/a').instance_variable_get(:@url)
-    end
-
-    expecteds.zip(actuals).each { |expected, actual| assert_equal(expected, actual) }
-  end
-
-  def test_invalid_depth
-    assert_raises(ArgumentError) do
-      Mdtoc::Markdown::Header.new(-1, 'a', '/a')
-    end
-  end
-
-  def test_label_normalization
-    sample = [
-      '  strip  ',
-      "squeeze    internal \t spaces",
-      'Don\'t change "#1?|!@#$%^&*()+ 2--',
-    ]
-    expecteds = [
-      'strip',
-      "squeeze internal spaces",
-      'Don\'t change "#1?|!@#$%^&*()+ 2--',
-    ]
-    actuals = sample.map { |label| Mdtoc::Markdown::Header.new(0, label, '/a').instance_variable_get(:@label) }
-
-    expecteds.zip(actuals).each { |expected, actual| assert_equal(expected, actual) }
-  end
-
-  def test_to_s_prefix
-    str = Mdtoc::Markdown::Header.new(3, 'a', '/a').to_s
-
-    assert_equal('      * [a](/a)', str)
-  end
-
-  def test_to_s_with_fragment
-    str = Mdtoc::Markdown::HeaderWithFragment.new(0, 'a', '/a').to_s
-
-    assert_equal('* [a](/a#a)', str)
-  end
-
-  def test_to_s_without_fragment
-    str = Mdtoc::Markdown::Header.new(0, 'a', '/a').to_s
-
-    assert_equal('* [a](/a)', str)
-  end
-end
-
-class TestParser < Minitest::Test
-  def test_skips_multiline_code_blocks
-    parser = Mdtoc::Markdown::Parser.new(0, '/')
-    sample = <<~END
-      # title
-      ```
-      code
-      # code
-      ```
-    END
-
-    headers = parser.headers(sample.each_line)
-
-    assert_equal(1, headers.size)
-    assert_equal('title', headers[0].instance_variable_get(:@label))
-  end
-
-  def test_skips_inline_code_blocks
-    parser = Mdtoc::Markdown::Parser.new(0, '/')
-    sample = <<~END
-      ```code #```
-      # Title
-      ```# code```
-      ```code```#
-    END
-
-    headers = parser.headers(sample.each_line)
-
-    assert_equal(1, headers.size)
-    assert_equal(headers[0].instance_variable_get(:@label), 'Title')
-  end
-
-  def test_depth
-    parser = Mdtoc::Markdown::Parser.new(10, '/')
-    sample = <<~END
-      # 1
-      ## 2
-      ### 3
-      #### 4
-    END
-
-    headers = parser.headers(sample.each_line)
-
-    assert_equal(4, headers.size)
-    (0..3).each do |i|
-      assert_equal(10 + i, headers[i].instance_variable_get(:@depth))
-    end
-  end
-end

data/test/test_node.rb

@@ -1,50 +0,0 @@
-# typed: false
-# frozen_string_literal: true
-
-require "minitest/autorun"
-require "mdtoc/node"
-
-class TestNode < Minitest::Test
-  SAMPLE_DIR = File.join(File.dirname(__FILE__), 'samples')
-
-  def test_dir
-    expected = <<~END
-      * [readme 1](test/samples/a/readme.md#readme-1)
-        * [readme 2](test/samples/a/readme.md#readme-2)
-          * [readme 3](test/samples/a/readme.md#readme-3)
-            * [readme 4](test/samples/a/readme.md#readme-4)
-        * [c 1](test/samples/a/c.md#c-1)
-          * [c 2](test/samples/a/c.md#c-2)
-          * [F](test/samples/a/d/f.md)
-            * [f 2](test/samples/a/d/f.md#f-2)
-        * [e 1](test/samples/a/e.md#e-1)
-        * [README 1 for g](test/samples/a/g/README.md#readme-1-for-g)
-          * [h 1](test/samples/a/g/h.md#h-1)
-    END
-    node = Mdtoc::Node.for_path(sample_path('a'))
-    actual = node.headers.join("\n") + "\n"
-
-    assert_equal(expected, actual)
-  end
-
-  def test_file
-    expected = <<~END
-      * [Title](test/samples/README.md#title)
-        * [2](test/samples/README.md#2)
-          * [3](test/samples/README.md#3)
-        * [2](test/samples/README.md#2)
-            * [4](test/samples/README.md#4)
-        * [2](test/samples/README.md#2)
-    END
-    node = Mdtoc::Node.for_path(sample_path('README.md'))
-    actual = node.headers.join("\n") + "\n"
-
-    assert_equal(expected, actual)
-  end
-
-  private
-
-  def sample_path(path)
-    File.join('test/samples', path)
-  end
-end