fix toc levels parsing as per documentation

vsch · May 13, 2020 · a3778aa · a3778aa
1 parent e19204a
commit a3778aa
Show file tree

Hide file tree

Showing 7 changed files with 383 additions and 89 deletions.
diff --git a/VERSION-TODO.md b/VERSION-TODO.md
@@ -7,6 +7,7 @@
 - [Release 0.60.0](#release-0600)
   - [API Refactoring](#api-refactoring)
 - [Next 0.61.xx](#next-061xx)
+- [0.61.28](#06128)
 - [0.61.26](#06126)
 - [0.61.24](#06124)
 - [0.61.22](#06122)
@@ -225,6 +226,30 @@ Please give feedback on the upcoming changes if you have concerns about breaking
 * [ ] Fix: Html converter to not add spaces between end of inline marker and next punctuation:
       `.,:;`
 
+## 0.61.28
+
+* Fix: Toc and SimToc `levels` parsing to properly handle levels as per documentation.
+  * single numeric >2 is 2-level, ie. `levels=4` should be interpreted as `levels=2-4` but was
+    `levels=4,4`.
+  * `levels=x-` to be same as `levels=x-6`, was handled as `levels=x,x`
+
+  `levels=levelList` where level list is a comma separated list of levels or ranges. Default is
+  to include heading levels 2 and 3. If a range is specified using `-` as separator between
+  numeric values then the included range is from first numeric to last numeric inclusive. If
+  first numeric is missing then 1 will be used in its place. If last numeric is missing then 6
+  will be used in its place.
+
+  Examples:
+  * `levels=1` include level 1 only, same as `levels=1,1`
+  * `levels=2` include level 2 only, same as `levels=2,2`
+  * `levels=3` include levels 2 and 3
+  * `levels=4` include levels 2,3 and 4
+  * `levels=2-4` include levels 2,3 and 4. same as `levels=4`
+  * `levels=2-4,5` include levels 2,3,4 and 5
+  * `levels=1,3` include levels 1 and 3
+  * `levels=-3` include levels 1 to 3
+  * `levels=3-` include levels 3 to 6
+
 ## 0.61.26
 
 * Fix: `SequenceBuilder.toString()` not to add space between sequence parts.

diff --git a/...rk-ext-toc/src/main/java/com/vladsch/flexmark/ext/toc/internal/TocLevelsOptionParser.java b/...rk-ext-toc/src/main/java/com/vladsch/flexmark/ext/toc/internal/TocLevelsOptionParser.java
@@ -37,6 +37,7 @@ public class TocLevelsOptionParser implements OptionParser<TocOptions> {
         TOC_LEVELS_MAP.put(1 << 5, "5,5");
         TOC_LEVELS_MAP.put(1 << 6, "6,6");
     }
+
     public TocLevelsOptionParser(String optionName) {
         this.myOptionName = optionName;
     }
@@ -46,7 +47,6 @@ public String getOptionName() {
         return myOptionName;
     }
 
-    @SuppressWarnings("unchecked")
     @Override
     public Pair<TocOptions, List<ParsedOption<TocOptions>>> parseOption(BasedSequence optionText, TocOptions options, MessageProvider provider) {
         // may have levels
@@ -71,20 +71,27 @@ public Pair<TocOptions, List<ParsedOption<TocOptions>>> parseOption(BasedSequenc
         };
 
         for (BasedSequence option : levelsOptionValue) {
-            BasedSequence[] optionRange = option.split("-", 2, BasedSequence.SPLIT_TRIM_PARTS);
+            BasedSequence[] optionRange = option.split("-", 2, BasedSequence.SPLIT_TRIM_PARTS | BasedSequence.SPLIT_INCLUDE_DELIM_PARTS);
 
             Integer rangeStart;
             Integer rangeEnd;
             parserParams.skip = false;
 
-            if (optionRange.length == 2) {
+            if (optionRange.length >= 2) {
                 rangeStart = convertWithMessage.apply(optionRange[0]);
-                rangeEnd = convertWithMessage.apply(optionRange[1]);
+                rangeEnd = optionRange.length >= 3 ? convertWithMessage.apply(optionRange[2]) : null;
                 if (rangeStart == null) rangeStart = 1;
                 if (rangeEnd == null) rangeEnd = 6;
             } else {
-                rangeStart = convertWithMessage.apply(optionRange[0]);
-                rangeEnd = rangeStart;
+                // NOTE: 1 means heading level 1 only, 2 means 2 only, rest mean 2-x
+                Integer optionValue = convertWithMessage.apply(optionRange[0]);
+                if (optionValue != null && optionValue <= 2) {
+                    rangeStart = optionValue;
+                    rangeEnd = rangeStart;
+                } else {
+                    rangeStart = optionValue == null ? null : 2;
+                    rangeEnd = optionValue;
+                }
             }
 
             if (!parserParams.skip) {

diff --git a/flexmark-ext-toc/src/main/javadoc/overview.html b/flexmark-ext-toc/src/main/javadoc/overview.html
@@ -4,7 +4,64 @@
 </head>
 <body>
 <p><strong>flexmark-java table of contents extension</strong></p>
-<p>flexmark-java extension for converting <code>[TOC level=</code> <em><strong>#</strong></em> <code>]</code> to an HTML rendered table of contents</p>
-<p>where # is a digit specifying the highest level heading to use in the table of contents</p>
+<p>Converts <code>[TOC style]</code> text to TocBlock nodes and</p>
+<p>Or Sim TOC tag, which has the following format: <code>[TOC style]: # &quot;Title&quot;</code> and includes all
+following lines until a blank line. <!--SimTocContent--></p>
+<p>Lines after the TOC tag are added to the <code>SimTocContent</code> child node of the SimToc block.</p>
+<p>The intention for this tag is to have the <code>SimTocContent</code> updated to reflect the content of the
+document.</p>
+<ol>
+  <li>
+    <p><code>style</code> consists of space separated list of options:</p>
+    <ul>
+      <li>
+        <p><code>levels=levelList</code> where level list is a comma separated list of levels or ranges. Default
+        is to include heading levels 2 and 3. Examples:</p>
+        <ul>
+          <li><code>levels=4</code> include levels 2,3 and 4</li>
+          <li><code>levels=2-4</code> include levels 2,3 and 4. same as <code>levels=4</code></li>
+          <li><code>levels=2-4,5</code> include levels 2,3,4 and 5</li>
+          <li><code>levels=1,3</code> include levels 1 and 3</li>
+          <li><code>levels=-3</code> include levels 1 to 3</li>
+          <li><code>levels=3-</code> include levels 3 to 6</li>
+        </ul>
+      </li>
+      <li>
+        <p><code>html</code> generate HTML version of the TOC</p>
+      </li>
+      <li>
+        <p><code>markdown</code> generate Markdown version of the TOC</p>
+      </li>
+      <li>
+        <p><code>text</code> to only include the text of the heading</p>
+      </li>
+      <li>
+        <p><code>formatted</code> to include text and inline formatting</p>
+      </li>
+      <li>
+        <p><code>hierarchy</code> to render as hierarchical list in order of appearance in the document</p>
+      </li>
+      <li>
+        <p><code>flat</code> to render as a flat list in order of appearance in the document</p>
+      </li>
+      <li>
+        <p><code>reversed</code> to render as a flat list in order of appearance in the document</p>
+      </li>
+      <li>
+        <p><code>sort-up</code> to render as a flat list sorted alphabetically by heading text only, no inlines</p>
+      </li>
+      <li>
+        <p><code>sort-down</code> to render as a flat list sorted reversed alphabetically by heading text only,
+        no inlines</p>
+      </li>
+      <li>
+        <p><code>bullet</code> to use a bullet list for the TOC items</p>
+      </li>
+      <li>
+        <p><code>numbered</code> to use a numbered list for TOC items</p>
+      </li>
+    </ul>
+  </li>
+</ol>
 </body>
 </html>
diff --git a/flexmark-ext-toc/src/main/javadoc/overview.md b/flexmark-ext-toc/src/main/javadoc/overview.md
@@ -1,5 +1,49 @@
 **flexmark-java table of contents extension**
 
-flexmark-java extension for converting `[TOC level=` ***#*** `]` to an HTML rendered table of contents
+Converts `[TOC style]` text to TocBlock nodes and 
+
+Or Sim TOC tag, which has the following format: `[TOC style]: # "Title"` and includes all
+following lines until a blank line. <!--SimTocContent-->
+
+
+Lines after the TOC tag are added to the `SimTocContent` child node of the SimToc block.
+
+The intention for this tag is to have the `SimTocContent` updated to reflect the content of the
+document.
+
+
+
+1. `style` consists of space separated list of options:
+
+   * `levels=levelList` where level list is a comma separated list of levels or ranges. Default
+     is to include heading levels 2 and 3. Examples:
+     * `levels=4` include levels 2,3 and 4
+     * `levels=2-4` include levels 2,3 and 4. same as `levels=4`
+     * `levels=2-4,5` include levels 2,3,4 and 5
+     * `levels=1,3` include levels 1 and 3
+     * `levels=-3` include levels 1 to 3
+     * `levels=3-` include levels 3 to 6
+
+   * `html` generate HTML version of the TOC
+
+   * `markdown` generate Markdown version of the TOC
+
+   * `text` to only include the text of the heading
+
+   * `formatted` to include text and inline formatting
+
+   * `hierarchy` to render as hierarchical list in order of appearance in the document
+
+   * `flat` to render as a flat list in order of appearance in the document
+
+   * `reversed` to render as a flat list in order of appearance in the document
+
+   * `sort-up` to render as a flat list sorted alphabetically by heading text only, no inlines
+
+   * `sort-down` to render as a flat list sorted reversed alphabetically by heading text only,
+     no inlines
+
+   * `bullet` to use a bullet list for the TOC items
+
+   * `numbered` to use a numbered list for TOC items
 
-where # is a digit specifying the highest level heading to use in the table of contents
diff --git a/flexmark-ext-toc/src/test/resources/ext_simtoc_ast_spec.md b/flexmark-ext-toc/src/test/resources/ext_simtoc_ast_spec.md
@@ -21,11 +21,21 @@ document.
 1. `style` consists of space separated list of options:
 
    * `levels=levelList` where level list is a comma separated list of levels or ranges. Default
-     is to include heading levels 2 and 3. Examples:
+     is to include heading levels 2 and 3. If a range is specified using `-` as separator
+     between numeric values then the included range is from first numeric to last numeric
+     inclusive. If first numeric is missing then 1 will be used in its place. If last numeric is
+     missing then 6 will be used in its place.
+
+     Examples:
+     * `levels=1` include level 1 only, same as `levels=1,1`
+     * `levels=2` include level 2 only, same as `levels=2,2`
+     * `levels=3` include levels 2 and 3
      * `levels=4` include levels 2,3 and 4
      * `levels=2-4` include levels 2,3 and 4. same as `levels=4`
      * `levels=2-4,5` include levels 2,3,4 and 5
      * `levels=1,3` include levels 1 and 3
+     * `levels=-3` include levels 1 to 3
+     * `levels=3-` include levels 3 to 6
 
    * `html` generate HTML version of the TOC
 
@@ -1198,13 +1208,21 @@ options, title with escaped chars
 <div>
   <h1>title&quot;s</h1>
   <ul>
-    <li><a href="#header-3">Header 3</a></li>
+    <li><a href="#header-2">Header 2</a>
+      <ul>
+        <li><a href="#header-3">Header 3</a></li>
+      </ul>
+    </li>
   </ul>
 </div>
 <div>
   <h1>title's</h1>
   <ul>
-    <li><a href="#header-3">Header 3</a></li>
+    <li><a href="#header-2">Header 2</a>
+      <ul>
+        <li><a href="#header-3">Header 3</a></li>
+      </ul>
+    </li>
   </ul>
 </div>
 .
@@ -2009,7 +2027,11 @@ Document[0, 58]
 <div md-pos="26-51">
   <h1>titles</h1>
   <ul>
-    <li><a href="#header-3">Header 3</a></li>
+    <li><a href="#header-2">Header 2</a>
+      <ul>
+        <li><a href="#header-3">Header 3</a></li>
+      </ul>
+    </li>
   </ul>
 </div>
 .

diff --git a/flexmark-ext-toc/src/test/resources/ext_toc_ast_spec.md b/flexmark-ext-toc/src/test/resources/ext_toc_ast_spec.md
@@ -15,11 +15,21 @@ Converts `[TOC style]` text to TocBlock nodes.
 1. `style` consists of space separated list of options:
 
    * `levels=levelList` where level list is a comma separated list of levels or ranges. Default
-     is to include heading levels 2 and 3. Examples:
+     is to include heading levels 2 and 3. If a range is specified using `-` as separator
+     between numeric values then the included range is from first numeric to last numeric
+     inclusive. If first numeric is missing then 1 will be used in its place. If last numeric is
+     missing then 6 will be used in its place.
+
+     Examples:
+     * `levels=1` include level 1 only, same as `levels=1,1`
+     * `levels=2` include level 2 only, same as `levels=2,2`
+     * `levels=3` include levels 2 and 3
      * `levels=4` include levels 2,3 and 4
      * `levels=2-4` include levels 2,3 and 4. same as `levels=4`
      * `levels=2-4,5` include levels 2,3,4 and 5
      * `levels=1,3` include levels 1 and 3
+     * `levels=-3` include levels 1 to 3
+     * `levels=3-` include levels 3 to 6
 
    * `html` generate HTML version of the TOC
 
@@ -1250,7 +1260,11 @@ Document[0, 129]
 <h3 id="header-3" md-pos="16-24">Header 3</h3>
 <div md-pos="26-40">
   <ul>
-    <li><a href="#header-3">Header 3</a></li>
+    <li><a href="#header-2">Header 2</a>
+      <ul>
+        <li><a href="#header-3">Header 3</a></li>
+      </ul>
+    </li>
   </ul>
 </div>
 .
@@ -1303,16 +1317,26 @@ Document[0, 40]
 <h4 id="test-1211">test 1.2.1.1</h4>
 <h4 id="test-1212">test 1.2.1.2</h4>
 <ul>
+  <li><a href="#test-001">test 0.0.1</a></li>
+  <li><a href="#test-002">test 0.0.2</a></li>
   <li><a href="#test-11">test 1.1</a>
     <ul>
-      <li><a href="#test-1111">test 1.1.1.1</a></li>
-      <li><a href="#test-1112">test 1.1.1.2</a></li>
+      <li><a href="#test-111">test 1.1.1</a>
+        <ul>
+          <li><a href="#test-1111">test 1.1.1.1</a></li>
+          <li><a href="#test-1112">test 1.1.1.2</a></li>
+        </ul>
+      </li>
     </ul>
   </li>
   <li><a href="#test-12">test 1.2</a>
     <ul>
-      <li><a href="#test-1211">test 1.2.1.1</a></li>
-      <li><a href="#test-1212">test 1.2.1.2</a></li>
+      <li><a href="#test-121">test 1.2.1</a>
+        <ul>
+          <li><a href="#test-1211">test 1.2.1.1</a></li>
+          <li><a href="#test-1212">test 1.2.1.2</a></li>
+        </ul>
+      </li>
     </ul>
   </li>
 </ul>