@rse/nunjucks-cli 1.4.0 → 1.4.2

package/README.md

@@ -46,7 +46,8 @@ Options
 
 ```
 $ nunjucks
-  [-h|--help] [-V|--version]
+  [-h|--help]
+  [-V|--version]
   [-c|--config <config-file>]
   [-C|--option <key>=<value>]
   [-d|--defines <context-file>]

package/nunjucks.1

@@ -0,0 +1,47 @@
+.TH "NUNJUCKS" "1" "August 2023" "" ""
+.SH "NAME"
+\fBnunjucks\fR - Template Rendering Engine
+.SH "SYNOPSIS"
+.P
+\fBnunjucks\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-V\fR|\fB--version\fR\[rB] \[lB]\fB-c\fR|\fB--config\fR \fIconfig-file\fR\[rB] \[lB]\fB-C\fR|\fB--option\fR \fIkey\fR=\fIvalue\fR\[rB] \[lB]\fB-d\fR|\fB--defines\fR \fIcontext-file\fR\[rB] \[lB]\fB-D\fR|\fB--define\fR \fIkey\fR=\fIvalue\fR\[rB] \[lB]\fB-e\fR|\fB--extension\fR \fImodule-name\fR\[rB] \[lB]\fB-o\fR|\fB--output\fR \fIoutput-file\fR|\fB-\fR\[rB] \[lB]\fIinput-file\fR|\fB-\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBnunjucks\fR(1) is a small command-line utility to render templates with the rich and powerful templating language \fBMozilla Nunjucks\fR \fI\(lahttps://mozilla.github.io/nunjucks/\(ra\fR. This allows you to define your configuration in a YAML file and then render an output file based on a template input file where your configuration can be expanded. It optionally can load Nunjucks addons like the ones from the companion \fBNunjucks Addons\fR \fI\(lahttps://github.com/rse/nunjucks-addons\(ra\fR package.
+.SH "OPTIONS"
+.P
+The following top-level options and arguments exist:
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB] Show usage help.
+.IP \(bu 4
+\[lB]\fB-V\fR|\fB--version\fR\[rB] show program version information.
+.IP \(bu 4
+\[lB]\fB-c\fR|\fB--config\fR \fIconfig-file\fR\[rB] load Nunjucks configuration YAML file.
+.IP \(bu 4
+\[lB]\fB-C\fR|\fB--option\fR \fIkey\fR=\fIvalue\fR\[rB] set Nunjucks configuration option.
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--defines\fR \fIcontext-file\fR\[rB] load context definition YAML file.
+.IP \(bu 4
+\[lB]\fB-D\fR|\fB--define\fR \fIkey\fR=\fIvalue\fR\[rB] set context definition key/value.
+.IP \(bu 4
+\[lB]\fB-e\fR|\fB--extension\fR \fImodule-name\fR\[rB] load Nunjucks JavaScript extension module (installed via NPM).
+.IP \(bu 4
+\[lB]\fB-o\fR|\fB--output\fR \fIoutput-file\fR|\fB-\fR\[rB] save output file (or stdout).
+.IP \(bu 4
+\[lB]\fB<input-file>\fR|\fB-\fR\[rB] load input file (or stdin).
+.RE 0
+
+.SH "EXAMPLE"
+.P
+.RS 2
+.nf
+$ echo "Hello, {{who}}!" | nunjucks -D who=world -
+Hello, world!
+.fi
+.RE
+.SH "HISTORY"
+.P
+The \fBnunjucks\fR(1) utility was developed in August 2023 for being able to easily generate multiple configuration files for a complex \fIDocker-Compose\fR based setup.
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/nunjucks.js

@@ -6,48 +6,41 @@
 */
 
 /*  own information  */
-const my       = require("./package.json")
+const my        = require("./package.json")
 
 /*  internal requirements  */
-const fs       = require("node:fs")
-const path     = require("node:path")
+const fs        = require("node:fs")
+const path      = require("node:path")
 
 /*  external requirements  */
-const yargs    = require("yargs")
-const chalk    = require("chalk")
-const jsYAML   = require("js-yaml")
-const nunjucks = require("nunjucks")
+const commander = require("commander")
+const chalk     = require("chalk")
+const jsYAML    = require("js-yaml")
+const nunjucks  = require("nunjucks")
 
 /*  parse command-line arguments  */
-const argv = yargs
-    .usage("Usage: nunjucks " +
-        "[-h|--help] " +
-        "[-V|--version] " +
-        "[-c|--config <config-file>] " +
-        "[-C|--option <key>=<value>] " +
-        "[-d|--defines <context-file>] " +
-        "[-D|--define <key>=<value>] " +
-        "[-e|--extension <module-name>] " +
-        "[-o|--output <output-file>|-] " +
-        "<input-file>|-")
-    .version(false)
-    .help("h").alias("h", "help").default("h", false).describe("h", "show usage help")
-    .boolean("V").alias("V", "version").describe("V", "show program version information")
-    .string("c").nargs("c", 1).alias("c", "config").describe("c", "load Nunjucks configuration YAML file")
-    .array("C").nargs("C", 1).alias("C", "option").describe("C", "set Nunjucks configuration option")
-    .string("d").nargs("d", 1).alias("d", "defines").describe("d", "load context definition YAML file")
-    .array("D").nargs("D", 1).alias("D", "define").describe("D", "set context definition key/value")
-    .array("e").nargs("e", 1).alias("e", "extension").describe("e", "load Nunjucks JavaScript extension module")
-    .string("o").nargs("o", 1).alias("o", "output").default("o", "-").describe("o", "save output file")
-    .strict()
-    .showHelpOnFail(true)
-    .demand(0)
-    .parserConfiguration({
-        "short-option-groups": true,
-        "parse-numbers":       true,
-        "boolean-negation":    true
-    })
-    .parse(process.argv.slice(2))
+const program = new commander.Command()
+program.name("nunjucks")
+    .description("Nunjucks Template Rendering Command-Line Interface")
+    .showHelpAfterError("hint: use option --help for usage information")
+    .option("-h, --help", "show usage help", false)
+    .option("-V, --version", "show program version information", false)
+    .option("-c, --config <config-file>", "load Nunjucks configuration YAML file", "")
+    .option("-C, --option <key>=<value>", "set Nunjucks configuration option", (v, l) => l.concat([ v ]), [])
+    .option("-d, --defines <context-file>", "load context definition YAML file", "")
+    .option("-D, --define <key>=<value>", "set context definition key/value", (v, l) => l.concat([ v ]), [])
+    .option("-e, --extension <module-name>", "load Nunjucks JavaScript extension module", (v, l) => l.concat([ v ]), [])
+    .option("-o, --output <output-file>", "save output file", "-")
+    .argument("[<input-file>]", "input file")
+program.parse(process.argv)
+const argv = { ...program.opts(), _: program.args }
+
+/*  handle special help request  */
+if (argv.help) {
+    console.log(program.helpInformation())
+    console.log("Example:\n  $ echo \"Hello, {{ who }}!\" | nunjucks -Dwho=World -\n")
+    process.exit(0)
+}
 
 /*  handle special version request  */
 if (argv.version) {
@@ -60,11 +53,11 @@ if (argv.version) {
 
 /*  read input file  */
 let input = ""
-if (argv._.length !== 1) {
-    console.error(chalk.red("nunjucks: ERROR: missing input file"))
+if (argv._.length > 1) {
+    console.error(chalk.red("nunjucks: ERROR: invalid number of arguments (zero or one input file expected)"))
     process.exit(1)
 }
-let inputFile = argv._[0]
+let inputFile = argv._[0] ?? "-"
 if (inputFile === "-") {
     inputFile = "<stdin>"
     process.stdin.setEncoding("utf-8")
@@ -109,14 +102,12 @@ if (argv.defines) {
 context.env = process.env
 
 /*  add context defines  */
-if (argv.define) {
-    argv.define.forEach((define) => {
-        let [ , key, val ] = define.match(/^([^=]+)(?:=(.*))?$/)
-        if (val === undefined)
-            val = true
-        context[key] = val
-    })
-}
+argv.define.forEach((define) => {
+    let [ , key, val ] = define.match(/^([^=]+)(?:=(.*))?$/)
+    if (val === undefined)
+        val = true
+    context[key] = val
+})
 
 /*  determine Nunjucks options  */
 let options = {}
@@ -129,10 +120,8 @@ if (argv.config) {
         process.exit(1)
     }
 }
-if (argv.options) {
-    console.log(argv.options)
-    options = Object.assign(options, argv.options)
-}
+if (argv.option.length > 0)
+    options = Object.assign(options, argv.option)
 options = Object.assign({}, {
     autoescape:       false,
     throwOnUndefined: false,
@@ -146,28 +135,26 @@ options = Object.assign({}, {
 const env = nunjucks.configure(inputFile, options)
 
 /*  load external extension files  */
-if (typeof argv.extension === "object" && argv.extension instanceof Array) {
-    for (let extension of argv.extension) {
-        let modpath = path.resolve(extension)
-        if (!fs.existsSync(modpath)) {
-            try {
-                modpath = require.resolve(extension)
-            }
-            catch (ex) {
-                modpath = null
-            }
-        }
-        if (modpath === null) {
-            console.error(chalk.red(`nunjucks: ERROR: failed to find extension module: ${extension}`))
-            process.exit(1)
+for (const extension of argv.extension) {
+    let modpath = path.resolve(extension)
+    if (!fs.existsSync(modpath)) {
+        try {
+            modpath = require.resolve(extension)
         }
-        const mod = require(modpath)
-        if (!(mod !== null && typeof mod === "function")) {
-            console.error(chalk.red(`nunjucks: ERROR: failed to call extension file: ${modpath}`))
-            process.exit(1)
+        catch (ex) {
+            modpath = null
         }
-        mod(env)
     }
+    if (modpath === null) {
+        console.error(chalk.red(`nunjucks: ERROR: failed to find extension module: ${extension}`))
+        process.exit(1)
+    }
+    const mod = require(modpath)
+    if (!(mod !== null && typeof mod === "function")) {
+        console.error(chalk.red(`nunjucks: ERROR: failed to call extension file: ${modpath}`))
+        process.exit(1)
+    }
+    mod(env)
 }
 
 /*  render Nunjucks template  */

package/nunjucks.md

@@ -0,0 +1,73 @@
+
+# nunjucks(1) -- Template Rendering Engine
+
+## SYNOPSIS
+
+`nunjucks`
+\[`-h`|`--help`\]
+\[`-V`|`--version`\]
+\[`-c`|`--config` *config-file*\]
+\[`-C`|`--option` *key*=*value*\]
+\[`-d`|`--defines` *context-file*\]
+\[`-D`|`--define` *key*=*value*\]
+\[`-e`|`--extension` *module-name*\]
+\[`-o`|`--output` *output-file*|`-`\]
+\[*input-file*|`-`\]
+
+## DESCRIPTION
+
+`nunjucks`(1) is a small command-line utility to render templates with the rich
+and powerful templating language [Mozilla Nunjucks](https://mozilla.github.io/nunjucks/).
+This allows you to define your configuration in a YAML file and then render
+an output file based on a template input file where your configuration can be expanded.
+It optionally can load Nunjucks addons like the ones from the companion
+[Nunjucks Addons](https://github.com/rse/nunjucks-addons) package.
+
+## OPTIONS
+
+The following top-level options and arguments exist:
+
+- \[`-h`|`--help`\]
+  Show usage help.
+
+- \[`-V`|`--version`\]
+  show program version information.
+
+- \[`-c`|`--config` *config-file*\]
+  load Nunjucks configuration YAML file.
+
+- \[`-C`|`--option` *key*=*value*\]
+  set Nunjucks configuration option.
+
+- \[`-d`|`--defines` *context-file*\]
+  load context definition YAML file.
+
+- \[`-D`|`--define` *key*=*value*\]
+  set context definition key/value.
+
+- \[`-e`|`--extension` *module-name*\]
+  load Nunjucks JavaScript extension module (installed via NPM).
+
+- \[`-o`|`--output` *output-file*|`-`\]
+  save output file (or stdout).
+
+- \[`<input-file>`|`-`\]
+  load input file (or stdin).
+
+## EXAMPLE
+
+```
+$ echo "Hello, {{who}}!" | nunjucks -D who=world -
+Hello, world!
+```
+
+## HISTORY
+
+The `nunjucks`(1) utility was developed in August 2023 for being
+able to easily generate multiple configuration files for a complex
+*Docker-Compose* based setup.
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>
+

package/package.json

@@ -1,7 +1,7 @@
 {
     "name":                       "@rse/nunjucks-cli",
     "publishConfig":              { "access": "public" },
-    "version":                    "1.4.0",
+    "version":                    "1.4.2",
     "description":                "Nunjucks Template Rendering Command-Line Interface",
     "author": {
         "name":                   "Dr. Ralf S. Engelschall",
@@ -10,11 +10,11 @@
     },
     "license":                    "MIT",
     "repository": {
-        "type": "git",
-        "url":  "git://github.com/rse/nunjucks-cli.git"
+        "type":                   "git",
+        "url":                    "git://github.com/rse/nunjucks-cli.git"
     },
     "bugs": {
-        "url":  "http://github.com/rse/nunjucks-cli/issues"
+        "url":                    "http://github.com/rse/nunjucks-cli/issues"
     },
     "bin": {
         "nunjucks":               "nunjucks.js"
@@ -22,19 +22,23 @@
     "dependencies": {
         "nunjucks":               "3.2.4",
         "chalk":                  "4.1.0",
-        "yargs":                  "17.7.2",
+        "commander":              "11.0.0",
         "js-yaml":                "4.1.0"
     },
     "devDependencies": {
-        "eslint":                 "8.47.0",
+        "eslint":                 "8.48.0",
         "eslint-config-standard": "17.1.0",
         "eslint-plugin-promise":  "6.1.1",
         "eslint-plugin-import":   "2.28.1",
-        "eslint-plugin-node":     "11.1.0"
+        "eslint-plugin-node":     "11.1.0",
+        "remark-cli":             "11.0.0",
+        "remark":                 "14.0.3",
+        "remark-man":             "8.0.1"
     },
     "upd":                        [ "!chalk" ],
     "scripts": {
         "lint":                   "eslint --config eslint.yaml nunjucks.js",
+        "man":                    "remark --quiet --use remark-man --output nunjucks.1 nunjucks.md",
         "test":                   "echo 'Hello, {{who}}!' | node nunjucks.js -D who=world -"
     }
 }