Merge pull request #18 from ogobrecht/development

Fix generated timestamp in docs

README.md

@@ -470,6 +470,13 @@ to escape the first hash character like so:
 
 ## Changelog
 
+### 0.9.1 - 2024-12-23
+
+- Fix generated timestamp in docs
+  - This timestamp slipped in with the last release
+  - Make it an option restores the previous behaviour
+  - It is a bad idea to have always changing docs without code changes
+
 ### 0.9.0 - 2024-12-22
 
 - Fix parsing issue for complex objects (thanks to github.com/gpaulissen for providing feedback and a test object)

package.json

@@ -1,16 +1,17 @@
 {
   "name": "ploc",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "PL/SQL code to doc converter",
   "main": "ploc.js",
   "bin": {
     "ploc": "ploc-cli.js"
   },
   "scripts": {
     "test_normal": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\"",
-    "test_autoHeaderIds": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\" --autoHeaderIds \"float: right;\"",
-    "test_tocStyles": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\" --tocStyles \"float: right;\"",
-    "test_autoHeaderIds_and_tocStyles": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\" --autoHeaderIds --tocStyles \"float: right;\"",
+    "test_timestamp": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\" --timestamp",
+    "test_autoHeaderIds": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\" --timestamp --autoHeaderIds \"float: right;\"",
+    "test_tocStyles": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\" --timestamp --tocStyles \"float: right;\"",
+    "test_autoHeaderIds_and_tocStyles": "echo \"Please check output tests/*.md!\" && npx ploc -d -i \"tests/*.*(pks|sql)\" --timestamp --autoHeaderIds --tocStyles \"float: right;\"",
     "build": "npx markdown-toc -i --maxdepth 2 README.md"
   },
   "repository": {

ploc-cli.js

@@ -7,9 +7,9 @@ const package = require('./package.json');
 
 // Util for parsing arguments: We reuse and extend ploc attributes here.
 ploc.utils.parseCliArgs = require('minimist');
-ploc.opts.cliArgs = {
+ploc.conf.cliArgs = {
     string: ["in", "out", "tocStyles"],
-    boolean: ["help", "autoHeaderIds", "version"],
+    boolean: ["help", "autoHeaderIds", "version", "timestamp"],
     alias: {
         i: "in",
         o: "out",
@@ -21,26 +21,26 @@ ploc.opts.cliArgs = {
     default: {
         in: "**/*.pks",
         out: "{folder}{file}.md",
-        toc: ploc.opts.minItemsForToc
+        toc: ploc.conf.minItemsForToc
     }
 };
 
 // cli help text.
-ploc.opts.cliHelp = [
+ploc.conf.cliHelp = [
     '',
     'Usage: ploc [options]',
     '',
     '-i, --in:         The glob pattern for the code files to read.',
-    '                  (default is "' + ploc.opts.cliArgs.default.in + '")',
+    '                  (default is "' + ploc.conf.cliArgs.default.in + '")',
     '',
     '-o, --out:        The pattern for the doc files to write.',
-    '                  (default is "' + ploc.opts.cliArgs.default.out + '")',
+    '                  (default is "' + ploc.conf.cliArgs.default.out + '")',
     '                  {folder} = in file path with trailing directory separator',
     '                  {file} = in file name without extension',
     '',
     '-t, --toc:        How many items (methods including object/package name) the',
     '                  code must have before a TOC is included.',
-    '                  (default is ' + ploc.opts.cliArgs.default.toc + ')',
+    '                  (default is ' + ploc.conf.cliArgs.default.toc + ')',
     '',
     '--tocStyles:      Inline styles to use for the TOC. If provided, the TOC',
     '                  is generated as a HTML unordered list instead of a',
@@ -49,6 +49,9 @@ ploc.opts.cliHelp = [
     '--autoHeaderIds:  Boolean - if present the headers are generated in HTML',
     '                  format instead of Markdown to be able to integrate the IDs.',
     '',
+    '--timestamp:      Boolean - if present a HTML comment with the generation',
+    '                  date and time is added.',
+    '',
     '-h, --help:       Command line help.',
     '',
     '-d, --debug:      Write CLI arguments to console.',
@@ -95,31 +98,32 @@ ploc.utils.files2docs = function (inFilePattern, outFilePattern) {
     }
     files.forEach(function (inFilePath) {
         const outFilePath = ploc.utils.getOutFilePath(inFilePath, outFilePattern);
+        const timestamp = (ploc.conf.timestamp ? `<!-- Generated ${new Date().toISOString()} -->\n` : '');
         console.log(inFilePath + ' => ' + outFilePath);
         fs.ensureFileSync(outFilePath);
         fs.writeFileSync(
             outFilePath,
             [
                 `<!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file ${inFilePath} -->`,
-                `<!-- Generated ${new Date().toISOString()} -->`,
-                `<!-- markdownlint-disable MD003 MD012 MD024 MD033 -->`,
+                `${timestamp}<!-- markdownlint-disable MD003 MD012 MD024 MD033 -->`,
                 ``,
                 ``
             ].join('\n') + ploc.getDoc(fs.readFileSync(inFilePath, 'utf8')));
     });
 };
 
 // Parse cli arguments.
-const args = ploc.utils.parseCliArgs(process.argv.slice(2), ploc.opts.cliArgs);
+const args = ploc.utils.parseCliArgs(process.argv.slice(2), ploc.conf.cliArgs);
 
-// Save args for TOC as these are used internally by ploc.getDoc.
-ploc.opts.autoHeaderIds = args.autoHeaderIds;
-ploc.opts.minItemsForToc = args.toc;
-ploc.opts.tocStyles = args.tocStyles;
+// Save args, they are used internally by ploc.getDoc.
+ploc.conf.autoHeaderIds = args.autoHeaderIds;
+ploc.conf.minItemsForToc = args.toc;
+ploc.conf.tocStyles = args.tocStyles;
+ploc.conf.timestamp = args.timestamp;
 
 // Print help, if options -h or --help were provided.
 if (args.help) {
-    console.log(ploc.opts.cliHelp);
+    console.log(ploc.conf.cliHelp);
 }
 else if (args.version) {
     // Print version, if options -v or --version were provided.

ploc.js

@@ -2,8 +2,8 @@
 
 const { regex } = require('regex');
 const ploc = {};
-ploc.opts = {};
-ploc.opts.minItemsForToc = 3;
+ploc.conf = {};
+ploc.conf.minItemsForToc = 3;
 ploc.utils = {};
 
 
@@ -83,7 +83,7 @@ ploc.getDocData = function (code) {
     let match;
 
     data.header = '';
-    data.toc = (ploc.opts.tocStyles ? '<ul style="' + ploc.opts.tocStyles + '">\n' : '');
+    data.toc = (ploc.conf.tocStyles ? '<ul style="' + ploc.conf.tocStyles + '">\n' : '');
     data.items = [];
 
     code = ploc.utils.reverseString(code);
@@ -129,14 +129,14 @@ ploc.getDocData = function (code) {
         }
         anchors.push(data.items[i].anchor);
         data.toc += (
-            ploc.opts.tocStyles ?
+            ploc.conf.tocStyles ?
                 `<li><a href="#${data.items[i].anchor}">${data.items[i].header}</a></li>\n` :
                 `- [${data.items[i].header}](#${data.items[i].anchor})\n`
         );
 
     });
 
-    data.toc += (ploc.opts.tocStyles ? '</ul>\n' : '');
+    data.toc += (ploc.conf.tocStyles ? '</ul>\n' : '');
 
     return data;
 };
@@ -145,7 +145,7 @@ ploc.getDocData = function (code) {
 // The main function to create the Markdown document.
 ploc.getDoc = function (code) {
     const docData = ploc.getDocData(code);
-    const provideToc = (docData.items.length >= ploc.opts.minItemsForToc);
+    const provideToc = (docData.items.length >= ploc.conf.minItemsForToc);
     let doc = '';
 
     doc += (docData.header ? docData.header + '\n\n' : '');
@@ -155,7 +155,7 @@ ploc.getDoc = function (code) {
         const level = (i === 0 && !docData.header ? 1 : 2);
         const comment = (level === 1 ? '=' : '-').repeat((15 + item.header.length + item.anchor.length));
         doc += [
-            (ploc.opts.autoHeaderIds ?
+            (ploc.conf.autoHeaderIds ?
                 `<h${level}><a id="${item.anchor}"></a>${item.header}</h${level}>\n<!--${comment}-->` :
                 `${'#'.repeat(level)} ${item.header}`),
             item.description,

tests/complex-object.md

@@ -1,5 +1,4 @@
 <!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file tests/complex-object.sql -->
-<!-- Generated 2024-12-22T09:44:14.403Z -->
 <!-- markdownlint-disable MD003 MD012 MD024 MD033 -->
 
 Overall Level One Header

tests/demo.md

@@ -1,5 +1,4 @@
 <!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file tests/demo.pks -->
-<!-- Generated 2024-12-22T09:44:14.396Z -->
 <!-- markdownlint-disable MD003 MD012 MD024 MD033 -->
 
 Your Leading Level One Header

tests/test.md

@@ -1,5 +1,4 @@
 <!-- DO NOT EDIT THIS FILE DIRECTLY - it is generated from source file tests/test.sql -->
-<!-- Generated 2024-12-22T09:44:14.378Z -->
 <!-- markdownlint-disable MD003 MD012 MD024 MD033 -->
 
 # Leading Level One Header