Merge pull request #19 from KEINOS/feat-user-custom-toc-tag

Feat #17 user custom toc tag. Close #17

Author: KEINOS

Extension.php

@@ -47,7 +47,7 @@ class ParsedownToC extends DynamicParent
      *  Constants.
      * ------------------------------------------------------------------------
      */
-    const version = '1.1.1'; // Version is available since v1.1.0
+    const version = '1.1.2'; // Version is available since v1.1.0
     const VERSION_PARSEDOWN_REQUIRED = '1.7';
     const TAG_TOC_DEFAULT = '[toc]';
     const ID_ATTRIBUTE_DEFAULT = 'toc';
@@ -124,15 +124,19 @@ protected function blockHeader($Line)
     }
 
     /**
-     * Parses the given markdown string to an HTML string.
-     * It's an alias of the parent method: \Parsedown::text()
+     * Parses the given markdown string to an HTML string but it leaves the ToC
+     * tag as is. It's an alias of the parent method "\DynamicParent::text()".
      *
      * @param  string $text  Markdown string to be parsed.
      * @return string        Parsed HTML string.
      */
     public function body($text)
     {
-        return DynamicParent::text($text);
+        $text = $this->encodeTagToHash($text);   // Escapes ToC tag temporary
+        $html = DynamicParent::text($text);      // Parses the markdown text
+        $html = $this->decodeTagFromHash($html); // Unescape the ToC tag
+
+        return $html;
     }
 
     /**
@@ -167,7 +171,8 @@ public function contentsList($type_return = 'string')
     }
 
     /**
-     * Generates link-able anchor from the text.
+     * Generates an anchor text that are link-able even the heading is not in
+     * ASCII.
      *
      * @param  string $text
      * @return string
@@ -177,6 +182,53 @@ protected function createAnchorID($text)
         return  urlencode($this->fetchText($text));
     }
 
+    /**
+     * Decodes the hashed ToC tag to an original tag and replaces.
+     *
+     * This is used to avoid parsing user defined ToC tag which includes "_" in
+     * their tag such as "[[_toc_]]". Unless it will be parsed as:
+     *   "<p>[[<em>TOC</em>]]</p>"
+     *
+     * @param  string $text
+     * @return string
+     */
+    protected function decodeTagFromHash($text)
+    {
+        $salt = $this->getSalt();
+        $tag_origin = $this->getTagToC();
+        $tag_hashed = hash('sha256', $salt . $tag_origin);
+
+        if (strpos($text, $tag_hashed) === false) {
+            return $text;
+        }
+
+        return str_replace($tag_hashed, $tag_origin, $text);
+    }
+
+    /**
+     * Encodes the ToC tag to a hashed tag and replace.
+     *
+     * This is used to avoid parsing user defined ToC tag which includes "_" in
+     * their tag such as "[[_toc_]]". Unless it will be parsed as:
+     *   "<p>[[<em>TOC</em>]]</p>"
+     *
+     * @param  string $text
+     * @return string
+     */
+    protected function encodeTagToHash($text)
+    {
+        $salt = $this->getSalt();
+        $tag_origin = $this->getTagToC();
+
+        if (strpos($text, $tag_origin) === false) {
+            return $text;
+        }
+
+        $tag_hashed = hash('sha256', $salt . $tag_origin);
+
+        return str_replace($tag_origin, $tag_hashed, $text);
+    }
+
     /**
      * Get only the text from a markdown string.
      * It parses to HTML once then trims the tags to get the text.
@@ -204,35 +256,33 @@ protected function getIdAttributeToC()
     }
 
     /**
-     * Gets the markdown tag for ToC.
+     * Unique string to use as a salt value.
      *
      * @return string
      */
-    protected function getTagToC()
+    protected function getSalt()
     {
-        if (isset($this->tag_toc) && ! empty($this->tag_toc)) {
-            return $this->tag_toc;
+        static $salt;
+        if (isset($salt)) {
+            return $salt;
         }
 
-        return self::TAG_TOC_DEFAULT;
+        $salt = hash('md5', time());
+        return $salt;
     }
 
     /**
-     * Replaces the "[toc]" tag (by default) to the parsed ToC list.
+     * Gets the markdown tag for ToC.
      *
-     * @param  string $html Parsed HTML string
-     * @return string       Parsed HTML string with parsed ToC.
+     * @return string
      */
-    protected function replaceTagToC($html)
+    protected function getTagToC()
     {
-        $toc     = $this->contentsList();
-        $tag_toc = $this->getTagToC();
-        $id_toc  = $this->getIdAttributeToC();
-
-        $needle  = '<p>' . $tag_toc . '</p>';
-        $replace = "<div id=\"${id_toc}\">${toc}</div>";
+        if (isset($this->tag_toc) && ! empty($this->tag_toc)) {
+            return $this->tag_toc;
+        }
 
-        return str_replace($needle, $replace, $html);
+        return self::TAG_TOC_DEFAULT;
     }
 
     /**
@@ -297,6 +347,29 @@ protected function setContentsListAsString(array $Content)
     protected $contentsListString = '';
     protected $firstHeadLevel = 0;
 
+    /**
+     * Sets the user defined ToC markdown tag.
+     *
+     * @param  string $tag
+     * @return void
+     */
+    public function setTagToc($tag)
+    {
+        $tag = trim($tag);
+        if (self::escape($tag) === $tag) {
+            // Set ToC tag if it's safe
+            $this->tag_toc = $tag;
+        } else {
+            // Do nothing but log
+            error_log(
+                'Malformed ToC user tag given.'
+                . ' At: ' . __FUNCTION__ . '() '
+                . ' in Line:' . __LINE__ . ' (Using default ToC tag)'
+            );
+        }
+    }
+    protected $tag_toc='';
+
     /**
      * Parses markdown string to HTML and also the "[toc]" tag as well.
      * It overrides the parent method: \Parsedown::text().
@@ -306,13 +379,22 @@ protected function setContentsListAsString(array $Content)
      */
     public function text($text)
     {
-        $body = $this->body($text);
-        $tag  = $this->getTagToC();
+        // Parses the markdown text except the ToC tag. This also searches
+        // the list of contents and available to get from "contentsList()"
+        // method.
+        $html = $this->body($text);
 
-        if (strpos($text, $tag) === false) {
-            return $body;
+        $tag_origin  = $this->getTagToC();
+
+        if (strpos($text, $tag_origin) === false) {
+            return $html;
         }
 
-        return $this->replaceTagToC($body);
+        $toc_data = $this->contentsList();
+        $toc_id   = $this->getIdAttributeToC();
+        $needle  = '<p>' . $tag_origin . '</p>';
+        $replace = "<div id=\"${toc_id}\">${toc_data}</div>";
+
+        return str_replace($needle, $replace, $html);
     }
 }

README.md

@@ -85,13 +85,23 @@ echo $body . PHP_EOL; // Main body
 - Main Class: `ParsedownToC()`
   - Arguments: none
   - Methods:
-    - `text(string $text)`: Returns the parsed content and `[toc]` tag(s) parsed as well.
+    - `text(string $text)`:
+      - Returns the parsed content and `[toc]` tag(s) parsed as well.
       - Required argument `$text`: Markdown string to be parsed.
-    - `body(string $text)`: Returns the parsed content without parsing `[toc]` tag.
+    - `body(string $text)`:
+      - Returns the parsed content WITHOUT parsing `[toc]` tag.
       - Required argument `$text`: Markdown string to be parsed.
-    - `toc([string $type_return='string'])`: Returns the ToC, the table of contents, in HTML or JSON.
-      - Option argument `$type_return`: `string` or `json` can be specified. (`string`=HTML(default), `json`=JSON)
+    - `toc([string $type_return='string'])`:
+      - Returns the ToC, the table of contents, in HTML or JSON.
+      - Option argument:
+        - `$type_return`:
+          - `string` or `json` can be specified. `string`=HTML, `json`=JSON.
+          - Default `string`
       - Alias method: `contentsList(string $type_return)`
+    - `setTagToc(string $tag='[tag]')`:
+      - Sets user defined ToC markdown tag. Use this method before `text()` or `body()` method if you want to use the ToC tag rather than the "`[toc]`".
+      - Empty value sets the default ToC tag.
+      - Available since v1.1.2
   - Other Methods:
     - All the public methods of `Parsedown` and/or `Parsedown Extend` are available to use.
   - Note: As of v1.1.0 the old alias class: `Extension()` is deprecated.
@@ -145,7 +155,7 @@ php -r "copy('https://KEINOS.github.io/parsedown-extension_table-of-contents/Ext
 
 As of Parsedown ToC Extension v1.1.1, you can use the [anchor identifiers](https://michelf.ca/projects/php-markdown/extra/#header-id) for [Parsedown Extra](https://github.com/erusev/parsedown-extra).
 
-With this feature, you can specify the anchor name you like. Useful if the headings are in UTF-8 (not in ASCII) and/or placing "go back" links in page.
+With this feature, you can specify the anchor name you like. Useful if the headings are in UTF-8 (not in ASCII) and to make it readable. Such as placing the "go back" links in a page.
 
 ```markdown
 # SampleHead1 {#self-defined-head1}

composer.json

@@ -33,6 +33,7 @@
         "test": "./tests/run-tests.sh",
         "test-docker": "docker run --rm --user root -v $(pwd):/app php:cli /app/tests/run-tests.sh",
         "test-docker-php5": "docker run --rm --user root -v $(pwd):/app php:5-cli-alpine /app/tests/run-tests.sh",
+        "test-docker-php5.3": "docker run --rm --user root -v $(pwd):/app php:5.3.29-cli /app/tests/run-tests.sh",
         "test-docker-php8": "docker run --rm --user root -v $(pwd):/app keinos/php8-jit /app/tests/run-tests.sh"
     }
 }

tests/README.md

@@ -18,7 +18,13 @@ In order to run the tests in PHP5 as well, we decided NOT to use PHPUnit and do
   ```
 
   ```bash
-  $ # For those who want to run the tests in PHP ^5.6 (Alpine)
+  $ # For those who want to run the tests in PHP 5.3.26 (Debian)
+  $ composer test-docker-php5.3
+  ...
+  ```
+
+  ```bash
+  $ # For those who want to run the tests in PHP 5.6.40 (Alpine)
   $ composer test-docker-php5
   ...
   ```