ploc/ploc-cli.js

PL/SQL code to doc converter

#!/usr/bin/env node

const fs = require('fs-extra');
const { globSync } = require('glob');
const ploc = require('./ploc.js');
const package = require('./package.json');

// Util for parsing arguments: We reuse and extend ploc attributes here.
ploc.utils.parseCliArgs = require('minimist');
ploc.conf.cliArgs = {
    string: ["in", "out", "tocStyles"],
    boolean: ["help", "autoHeaderIds", "version", "timestamp"],
    alias: {
        i: "in",
        o: "out",
        t: "toc",
        h: "help",
        d: "debug",
        v: "version"
    },
    default: {
        in: "**/*.pks",
        out: "{folder}{file}.md",
        toc: ploc.conf.minItemsForToc
    }
};

// cli help text.
ploc.conf.cliHelp = [
    '',
    'Usage: ploc [options]',
    '',
    '-i, --in:         The glob pattern for the code files to read.',
    '                  (default is "' + ploc.conf.cliArgs.default.in + '")',
    '',
    '-o, --out:        The pattern for the doc files to write.',
    '                  (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.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',
    '                  Markdown list to be able to use the styles.',
    '',
    '--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.',
    '',
    '-v, --version:    Print ploc version.',
    '',
    'Example 1: npx ploc --in "**/*.pks" --out {folder}{file}.md',
    'Example 2: npx ploc --out docs/{file}.md',
    'Example 3: npx ploc -i "**/*.*(pks|sql)" -o docs/{file}.md -t 5',
    'Example 4: npx ploc --in "src/*.pks" --out docs/{file}.md --autoHeaderIds --tocStyles "float: right;"',
    'https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner',
    '',
].join('\n');

// Utility to calculate one out file path from an in file path and an out file pattern.
ploc.utils.getOutFilePath = function (inFilePath, outFilePattern) {
    const regexp = /(.*(?:\\|\/)+)?((.*)(\.([^?\s]*)))\??(.*)?/i;
    let folder, file, match;
    /*
    This regex is taken from https://regexr.com/3dns9 and splits a URL it its components:
    - $1: folder path
    - $2: file name(including extension)
    - $3: file name without extension
    - $4: extension
    - $5: extension without dot sign
    - $6: variables
    */

    // Extract folder and file from inFilePath for replacements of {folder} and {file} in outFilePattern.
    match = inFilePath.match(regexp);
    folder = match[1] || '';
    file = match[3];

    // Do the final replacements and return.
    return outFilePattern.replace('{folder}', folder).replace('{file}', file);
};

// Utility to process all files for the provided in and out file patterns.
ploc.utils.files2docs = function (inFilePattern, outFilePattern) {
    const options = { matchBase: false };
    const files = globSync(inFilePattern, options);
    if (args.debug) {
        console.log('Files:', files);
    }
    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} -->`,
                `${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.conf.cliArgs);

// 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.conf.cliHelp);
}
else if (args.version) {
    // Print version, if options -v or --version were provided.
    console.log(package.version);
}
else {
    // Otherwise create the documents.
    if (args.debug) {
        console.log('CLI arguments:', args);
    }
    ploc.utils.files2docs(args.in, args.out)
}