From 11fa03e7a4602d857c33b3420dd1e3a605372807 Mon Sep 17 00:00:00 2001 From: Axel Hahn Date: Sun, 18 Sep 2022 20:33:07 +0200 Subject: [PATCH 1/8] load a config to customize output --- docblox2md.js | 84 ++++++++++++++++++++++---------- docblox2md_config.js | 25 ++++++++++ docblox2md_config_custom_dist.js | 28 +++++++++++ 3 files changed, 111 insertions(+), 26 deletions(-) create mode 100644 docblox2md_config.js create mode 100644 docblox2md_config_custom_dist.js diff --git a/docblox2md.js b/docblox2md.js index 13e4a74..a2d38fa 100644 --- a/docblox2md.js +++ b/docblox2md.js @@ -2,6 +2,17 @@ var fs = require('fs'); +// load a config for rendering replacemnts +const path = require('path') +const customconfig = path.join(__dirname, './docblox2md_config_custom.js') + +if(fs.existsSync(customconfig)){ + var _aRender=require('./docblox2md_config_custom.js'); +} else { + var _aRender=require('./docblox2md_config.js'); +} +// /load config + /* eslint-disable max-len */ var re = { // Document level @@ -158,6 +169,26 @@ function srcToBlocks(src) { return blocks; } +// https://stackoverflow.com/questions/610406/javascript-equivalent-to-printf-string-format?page=2&tab=scoredesc#tab-top +function _sprintf(message){ + const regexp = RegExp('%s','g'); + let match; + let index = 1; + while((match = regexp.exec(message)) !== null) { + let replacement = arguments[index]; + if (replacement) { + let messageToArray = message.split(''); + messageToArray.splice(match.index, regexp.lastIndex - match.index, replacement); + message = messageToArray.join(''); + index++; + } else { + break; + } + } + + return message; +} + /** * Generate Markdown from abstract blocks * @@ -291,16 +322,17 @@ function blocksToMarkdown(blocks, level, threshold) { // Header md.push( - '\n' - + '#'.repeat(Number(level) + (inClass && !isClass ? 1 : 0)) - + ' `' - // + (visibility ? visibility + ' ' : '') - // + (type ? type + ' ' : '') - // + (name ? name + ' ' : '') - + (implem ? 'implements ' + implem + ' ' : '') - + blocks[i].code - + '`\n\n' - ); + _sprintf( + _aRender.header.item, + '#'.repeat(Number(level) + (inClass && !isClass ? 1 : 0)) + + ' ' + // + (visibility ? visibility + ' ' : '') + // + (type ? type + ' ' : '') + // + (name ? name + ' ' : '') + + (implem ? 'implements ' + implem + ' ' : '') + + blocks[i].code + ) + ) // Verbatim lines for (j = 0; j < blocks[i].lines.length; j++) { @@ -315,29 +347,29 @@ function blocksToMarkdown(blocks, level, threshold) { // Parameters if (params.length > 0) { - md.push('\n**Parameters:**\n\n'); + md.push(_aRender.params.pre) } for (j = 0; j < params.length; j++) { md.push( - '* `' - + params[j].name - + '` — `' - + params[j].type - + '`' - + (params[j].desc ? ' — ' + params[j].desc : '') - + '\n' - ); + _sprintf( + _aRender.params.item, + params[j].name, + params[j].type, + (params[j].desc ? params[j].desc : '') + ) + ) } // Return value if (returnType !== '' || returnDesc !== '') { - md.push('\n**Returns:**'); - if (returnType !== '') { - md.push(' `' + returnType + '`'); - } - if (returnDesc !== '') { - md.push((returnType !== '' ? ' — ' : ' ') + returnDesc + '\n'); - } + md.push(_aRender.return.pre) + md.push( + _sprintf( + _aRender.return.item, + returnType+' ', + returnDesc+' ' + ) + ) } // Final empty line diff --git a/docblox2md_config.js b/docblox2md_config.js new file mode 100644 index 0000000..c6da9e6 --- /dev/null +++ b/docblox2md_config.js @@ -0,0 +1,25 @@ +/** + * CONFIG for output of blocks + * Do not modify it - it is part of distribution. + * To customize output see the file docblox2md_config_custom_dist.js + */ + +module.exports = { + 'header': { + 'pre': '', + 'item': "\n%s\n\n", + 'post': '' + }, + 'params': { + 'pre': '\n**Parameters:**\n\n' + +'Var | Type | Desciption\n' + +'-- |-- |--\n', + 'item': "%s | %s | %s\n", + 'post': '' + }, + 'return': { + 'pre': '\n**Return:**\n\n', + 'item': "%s %s\n", + 'post': '' + } +} \ No newline at end of file diff --git a/docblox2md_config_custom_dist.js b/docblox2md_config_custom_dist.js new file mode 100644 index 0000000..41d8cf5 --- /dev/null +++ b/docblox2md_config_custom_dist.js @@ -0,0 +1,28 @@ +/** + * CUSTOM CONFIG for output of blocks + * + * rename docblox2md_config_custom_dist.js + * to docblox2md_config_custom.js + * + * Then your settings overide data from docblox2md_config.js + */ + +module.exports = { + 'header': { + 'pre': '', + 'item': "\n%s\n\n", + 'post': '' + }, + 'params': { + 'pre': '\n**Parameters:**\n\n' + +'Var | Type | Desciption\n' + +'-- |-- |--\n', + 'item': "%s | %s | %s\n", + 'post': '' + }, + 'return': { + 'pre': '\n**Return:**\n\n', + 'item': "%s %s\n", + 'post': '' + } +} \ No newline at end of file From 3534f90d9d8251ca4d58667ca7bbeb06f06041cb Mon Sep 17 00:00:00 2001 From: Axel Hahn Date: Mon, 19 Sep 2022 18:01:52 +0200 Subject: [PATCH 2/8] update config elements for header --- docblox2md.js | 16 +++++++++++----- docblox2md_config.js | 8 ++++---- docblox2md_config_custom_dist.js | 8 ++++---- 3 files changed, 19 insertions(+), 13 deletions(-) diff --git a/docblox2md.js b/docblox2md.js index a2d38fa..483138c 100644 --- a/docblox2md.js +++ b/docblox2md.js @@ -322,17 +322,22 @@ function blocksToMarkdown(blocks, level, threshold) { // Header md.push( - _sprintf( + '' + + (_aRender.header.pre ? _aRender.header.pre : '') + + '#'.repeat(Number(level) + (inClass && !isClass ? 1 : 0)) + + ' ' + +_sprintf( _aRender.header.item, - '#'.repeat(Number(level) + (inClass && !isClass ? 1 : 0)) - + ' ' + '' // + (visibility ? visibility + ' ' : '') // + (type ? type + ' ' : '') // + (name ? name + ' ' : '') + (implem ? 'implements ' + implem + ' ' : '') - + blocks[i].code + + blocks[i].code.replace(/\$/, "\\$") ) + + (_aRender.header.post ? _aRender.header.post : '') ) + md.push('\n'); // Verbatim lines for (j = 0; j < blocks[i].lines.length; j++) { @@ -369,7 +374,8 @@ function blocksToMarkdown(blocks, level, threshold) { returnType+' ', returnDesc+' ' ) - ) + ), + md.push(_aRender.return.post) } // Final empty line diff --git a/docblox2md_config.js b/docblox2md_config.js index c6da9e6..e390bc0 100644 --- a/docblox2md_config.js +++ b/docblox2md_config.js @@ -4,10 +4,10 @@ * To customize output see the file docblox2md_config_custom_dist.js */ -module.exports = { + module.exports = { 'header': { - 'pre': '', - 'item': "\n%s\n\n", + 'pre': '\n---\n', + 'item': "`%s`", 'post': '' }, 'params': { @@ -22,4 +22,4 @@ module.exports = { 'item': "%s %s\n", 'post': '' } -} \ No newline at end of file +} diff --git a/docblox2md_config_custom_dist.js b/docblox2md_config_custom_dist.js index 41d8cf5..8ab38ff 100644 --- a/docblox2md_config_custom_dist.js +++ b/docblox2md_config_custom_dist.js @@ -7,10 +7,10 @@ * Then your settings overide data from docblox2md_config.js */ -module.exports = { + module.exports = { 'header': { - 'pre': '', - 'item': "\n%s\n\n", + 'pre': '\n---\n', + 'item': "`%s`", 'post': '' }, 'params': { @@ -25,4 +25,4 @@ module.exports = { 'item': "%s %s\n", 'post': '' } -} \ No newline at end of file +} From 99dd8cc4128b051e8a5767e170c6f7c04343b82e Mon Sep 17 00:00:00 2001 From: Axel Hahn Date: Tue, 20 Sep 2022 00:25:00 +0200 Subject: [PATCH 3/8] scan custom config in a list of files --- docblox2md.js | 57 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 15 deletions(-) diff --git a/docblox2md.js b/docblox2md.js index 483138c..b43a9c7 100644 --- a/docblox2md.js +++ b/docblox2md.js @@ -2,16 +2,41 @@ var fs = require('fs'); +var _aRender={ + 'header': { + 'pre': '', + 'item': "`%s`\n", + 'post': '' + }, + 'params': { + 'pre': '\n**Parameters:**\n\n', + 'item': "* `%s` — `%s` — %s\n", // varname, type, description + 'post': '\n' + }, + 'return': { + 'pre': '\n**Return:**\n\n', + 'item': "%s %s\n", + 'post': '' + } +} + // load a config for rendering replacemnts const path = require('path') -const customconfig = path.join(__dirname, './docblox2md_config_custom.js') -if(fs.existsSync(customconfig)){ - var _aRender=require('./docblox2md_config_custom.js'); -} else { - var _aRender=require('./docblox2md_config.js'); +// list of optional custom config files to read ... 1st match wins +const aCfgfiles=[ + process.cwd()+'/.docblox2md.js', // in working directory + path.join(process.env.HOME, '/.docblox2md.js'), // in $HOME + path.join(__dirname, '/.docblox2md.js'), // in install dir +]; + +for (var i=0; i 0) { md.push(_aRender.params.pre) - } - for (j = 0; j < params.length; j++) { - md.push( - _sprintf( - _aRender.params.item, - params[j].name, - params[j].type, - (params[j].desc ? params[j].desc : '') + + for (j = 0; j < params.length; j++) { + md.push( + _sprintf( + _aRender.params.item, + params[j].name, + params[j].type, + (params[j].desc ? params[j].desc : '') + ) ) - ) + } + md.push(_aRender.params.post) } // Return value From 3ee970917084768a1a2582111630282aedd94e78 Mon Sep 17 00:00:00 2001 From: Axel Hahn Date: Thu, 22 Sep 2022 20:24:37 +0200 Subject: [PATCH 4/8] cli: do not write file if there is no change --- cli.js | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/cli.js b/cli.js index 3b33471..f57e692 100755 --- a/cli.js +++ b/cli.js @@ -49,9 +49,7 @@ files = process.argv.slice(parser.optind()); files.forEach(function(filename) { var file; - if (verbose) { - process.stderr.write('Processing ' + filename + '...\n'); - } + if (verbose) {process.stderr.write('Processing ' + filename + '...\n');} try { file = fs.readFileSync(filename, {encoding: 'utf-8'}); @@ -63,10 +61,13 @@ files.forEach(function(filename) { } try { - fs.writeFileSync( - filename, - docblox2md.filterDocument(file, options.threshold) - ); + var newdata=docblox2md.filterDocument(file, options.threshold); + if(file===newdata){ + if (verbose) {process.stderr.write('SKIP: ' + filename + ' has no changes\n');} + } else { + fs.writeFileSync(filename,newdata); + if (verbose) {process.stderr.write('OK: '+filename + ' was written\n');} + } } catch (e) { process.stderr.write( 'Error: unable to write to ' + filename + ':' + e + '\n' From 8ecbfa0274fb63b5fc0d4c357c36adbf1981e2ce Mon Sep 17 00:00:00 2001 From: Axel Hahn Date: Thu, 22 Sep 2022 20:25:35 +0200 Subject: [PATCH 5/8] add config hash and custom config file --- docblox2md.js | 59 ++++++++++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/docblox2md.js b/docblox2md.js index b43a9c7..86ee47d 100644 --- a/docblox2md.js +++ b/docblox2md.js @@ -1,28 +1,29 @@ 'use strict'; var fs = require('fs'); +const path = require('path') -var _aRender={ - 'header': { - 'pre': '', - 'item': "`%s`\n", - 'post': '' - }, - 'params': { - 'pre': '\n**Parameters:**\n\n', - 'item': "* `%s` — `%s` — %s\n", // varname, type, description - 'post': '\n' - }, - 'return': { - 'pre': '\n**Return:**\n\n', - 'item': "%s %s\n", - 'post': '' +// default config data +var config={ + 'output': { + 'header': { + 'pre': '', + 'item': "`%s`\n", + 'post': '' + }, + 'params': { + 'pre': '\n**Parameters:**\n\n', + 'item': "* `%s` — `%s` — %s\n", // varname, type, description + 'post': '\n' + }, + 'return': { + 'pre': '\n**Return:**\n\n', + 'item': "%s %s\n", + 'post': '' + } } } -// load a config for rendering replacemnts -const path = require('path') - // list of optional custom config files to read ... 1st match wins const aCfgfiles=[ process.cwd()+'/.docblox2md.js', // in working directory @@ -32,8 +33,8 @@ const aCfgfiles=[ for (var i=0; i 0) { - md.push(_aRender.params.pre) + md.push(config.output.params.pre) for (j = 0; j < params.length; j++) { md.push( _sprintf( - _aRender.params.item, + config.output.params.item, params[j].name, params[j].type, (params[j].desc ? params[j].desc : '') ) ) } - md.push(_aRender.params.post) + md.push(config.output.params.post) } // Return value if (returnType !== '' || returnDesc !== '') { - md.push(_aRender.return.pre) + md.push(config.output.return.pre) md.push( _sprintf( - _aRender.return.item, + config.output.return.item, returnType+' ', returnDesc+' ' ) ), - md.push(_aRender.return.post) + md.push(config.output.return.post) } // Final empty line From acb688016416a1aa253ed48f5a101f1c886e5c14 Mon Sep 17 00:00:00 2001 From: Axel Hahn Date: Thu, 22 Sep 2022 20:28:54 +0200 Subject: [PATCH 6/8] update code formatting --- cli.js | 18 +++++++++++++++--- docblox2md.js | 4 +++- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/cli.js b/cli.js index f57e692..66cce03 100755 --- a/cli.js +++ b/cli.js @@ -49,7 +49,11 @@ files = process.argv.slice(parser.optind()); files.forEach(function(filename) { var file; - if (verbose) {process.stderr.write('Processing ' + filename + '...\n');} + if (verbose) { + process.stderr.write( + 'Processing ' + filename + '...\n' + ); + } try { file = fs.readFileSync(filename, {encoding: 'utf-8'}); @@ -63,10 +67,18 @@ files.forEach(function(filename) { try { var newdata=docblox2md.filterDocument(file, options.threshold); if(file===newdata){ - if (verbose) {process.stderr.write('SKIP: ' + filename + ' has no changes\n');} + if (verbose) { + process.stderr.write( + 'SKIP: ' + filename + ' has no changes\n' + ); + } } else { fs.writeFileSync(filename,newdata); - if (verbose) {process.stderr.write('OK: '+filename + ' was written\n');} + if (verbose) { + process.stderr.write( + 'OK: '+filename + ' was written\n' + ); + } } } catch (e) { process.stderr.write( diff --git a/docblox2md.js b/docblox2md.js index 86ee47d..944fb20 100644 --- a/docblox2md.js +++ b/docblox2md.js @@ -33,7 +33,9 @@ const aCfgfiles=[ for (var i=0; i Date: Thu, 22 Sep 2022 20:29:21 +0200 Subject: [PATCH 7/8] remove unneeded files --- docblox2md_config.js | 25 ------------------------- docblox2md_config_custom_dist.js | 28 ---------------------------- 2 files changed, 53 deletions(-) delete mode 100644 docblox2md_config.js delete mode 100644 docblox2md_config_custom_dist.js diff --git a/docblox2md_config.js b/docblox2md_config.js deleted file mode 100644 index e390bc0..0000000 --- a/docblox2md_config.js +++ /dev/null @@ -1,25 +0,0 @@ -/** - * CONFIG for output of blocks - * Do not modify it - it is part of distribution. - * To customize output see the file docblox2md_config_custom_dist.js - */ - - module.exports = { - 'header': { - 'pre': '\n---\n', - 'item': "`%s`", - 'post': '' - }, - 'params': { - 'pre': '\n**Parameters:**\n\n' - +'Var | Type | Desciption\n' - +'-- |-- |--\n', - 'item': "%s | %s | %s\n", - 'post': '' - }, - 'return': { - 'pre': '\n**Return:**\n\n', - 'item': "%s %s\n", - 'post': '' - } -} diff --git a/docblox2md_config_custom_dist.js b/docblox2md_config_custom_dist.js deleted file mode 100644 index 8ab38ff..0000000 --- a/docblox2md_config_custom_dist.js +++ /dev/null @@ -1,28 +0,0 @@ -/** - * CUSTOM CONFIG for output of blocks - * - * rename docblox2md_config_custom_dist.js - * to docblox2md_config_custom.js - * - * Then your settings overide data from docblox2md_config.js - */ - - module.exports = { - 'header': { - 'pre': '\n---\n', - 'item': "`%s`", - 'post': '' - }, - 'params': { - 'pre': '\n**Parameters:**\n\n' - +'Var | Type | Desciption\n' - +'-- |-- |--\n', - 'item': "%s | %s | %s\n", - 'post': '' - }, - 'return': { - 'pre': '\n**Return:**\n\n', - 'item': "%s %s\n", - 'post': '' - } -} From 058284a5457b333bbd23e2e9288efee7d66b654d Mon Sep 17 00:00:00 2001 From: Axel Hahn Date: Fri, 30 Sep 2022 00:09:33 +0200 Subject: [PATCH 8/8] skip md files without placeholder --- cli.js | 18 ++++++------------ docblox2md.js | 27 +++++++++++++++++++++++---- 2 files changed, 29 insertions(+), 16 deletions(-) diff --git a/cli.js b/cli.js index 66cce03..abb091d 100755 --- a/cli.js +++ b/cli.js @@ -50,9 +50,7 @@ files.forEach(function(filename) { var file; if (verbose) { - process.stderr.write( - 'Processing ' + filename + '...\n' - ); + process.stderr.write('Info: Processing ' + filename + '...\n'); } try { @@ -65,19 +63,15 @@ files.forEach(function(filename) { } try { - var newdata=docblox2md.filterDocument(file, options.threshold); - if(file===newdata){ + if(!docblox2md.hasPlaceholder(file)){ if (verbose) { - process.stderr.write( - 'SKIP: ' + filename + ' has no changes\n' - ); - } + process.stderr.write('Skip: ' + filename + ' has no docblox2md placeholder.\n'); + } } else { + var newdata=docblox2md.filterDocument(file, options.threshold); fs.writeFileSync(filename,newdata); if (verbose) { - process.stderr.write( - 'OK: '+filename + ' was written\n' - ); + process.stderr.write('OK: '+filename + ' was written\n'); } } } catch (e) { diff --git a/docblox2md.js b/docblox2md.js index 944fb20..ccbf918 100644 --- a/docblox2md.js +++ b/docblox2md.js @@ -33,9 +33,7 @@ const aCfgfiles=[ for (var i=0; i 1; +} + /** * Filter Markdown document for our placeholders * @@ -525,6 +542,8 @@ module.exports = { blocksToMarkdown: blocksToMarkdown, srcToMarkdown : srcToMarkdown, + hasPlaceholder : hasPlaceholder, + // End-to-end processing filterDocument: filterDocument, };