cmdln - npm Package Compare versions

Comparing version 3.2.4 to 3.3.0

CHANGES.md

 # node-cmdln Changelog
 
+## 3.3.0
+
+- `<MyCLI instance>.bashCompletions()` will generate bash completions
+  for the `MyCLI` tool. You can add, e.g., a 'completion(s)' command
+  to your CLI for users to run. Or you could generate completions
+  and distribute those with your tool.
+
+  See "examples/conan.js" for example usage.
+
+        $ alias conan="node examples/conan.js"
+        $ conan completion > conan.completion
+        $ source conan.completion
+        $ conan <TAB>
+        --help      --version   -v          completion  hear        see
+        --verbose   -h          -x          crush       help        smash
+
+  Bash completion support is mostly by <github.com/bahamas10>.
+
+
 ## 3.2.4
@@ -4,0 +23,0 @@

lib/cmdln.js

@@ -30,2 +30,3 @@ /*
 
+
 // ---- globals
@@ -83,2 +84,10 @@
 
+// Replace {{variable}} in `s` with the template data in `d`.
+function renderTemplate(s, d) {
+    return s.replace(/{{([a-zA-Z]+)}}/g, function(match, key) {
+        return d.hasOwnProperty(key) ? d[key] : match;
+    });
+}
+
+
 // ---- Errors
@@ -445,2 +454,71 @@
 /**
+ * Generate and return Bash completion for this Cmdln subclass instance.
+ */
+Cmdln.prototype.bashCompletion = function bashCompletion() {
+    var self = this;
+
+    var args = namesFromOptions(self.options);
+    var commands = {};
+
+    // loop subcommands
+    self._subcmdOrder.forEach(function (name, idx) {
+        if (typeof (name) !== 'string')
+            return;
+
+        var handler = self._handlerFromName[name];
+        if (handler.hidden)
+            return;
+
+        var opts = namesFromOptions(handler.options);
+
+        var names = [name].concat(handler.aliases || []);
+        names.forEach(function (name) {
+            if (name === '?') {
+                return;
+            }
+            commands[name] = opts;
+            args.push(name);
+        });
+    });
+
+    // create template
+    var data = {
+        name: self.name,
+        args: args.join('\n'),
+        date: new Date(),
+    };
+
+    var c = [];
+    Object.keys(commands).forEach(function (command) {
+        c.push(format('\'%s\') words=(%s);;',
+            command, commands[command].join(' ')));
+    });
+    data.commands = c.join('\n');
+
+    // render template
+    var template = fs.readFileSync(
+        path.join(__dirname, '../etc/completion.bash.in'), 'utf8');
+    return renderTemplate(template, data);
+
+
+    function namesFromOptions(options) {
+        var opts = [];
+        (options || []).forEach(function (option) {
+            var names = option.names || [];
+            if (option.name)
+                names.push(option.name);
+            names = names.map(function (name) {
+                if (name.length === 1)
+                    return '-' + name;
+                else
+                    return '--' + name;
+            });
+            opts = opts.concat(names);
+        });
+        return opts;
+    }
+};
+
+
+/**
  * Handler called for an empty line of input. By default this prints help
@@ -447,0 +525,0 @@ * output and returns a `NoCommandError` (exitStatus == 1).

package.json

 {
     "name": "cmdln",
-    "version": "3.2.4",
+    "version": "3.3.0",
     "description": "helper lib for creating CLI tools with subcommands; think `git`, `svn`, `zfs`",
@@ -5,0 +5,0 @@ "author": "Trent Mick (http://trentm.com)",

README.md

@@ -131,2 +131,29 @@ `node-cmdln` is a node.js helper lib for creating CLI tools with subcommands
 
+# Bash completion
+
+One can generate Bash completion code for a `Cmdln` subclass via
+
+    cli.bashCompletion()
+
+One possible usage is to add a `completion` subcmd to your CLI:
+
+    CLI.prototype.do_completion = function (subcmd, opts, args, cb) {
+        console.log( this.bashCompletion() );
+        cb();
+    };
+
+and get users to use that to setup Bash completion:
+
+    $ alias conan="node examples/conan.js"
+    $ conan completion > conan.completion
+    $ source conan.completion
+    $ conan <TAB>
+    --help      --version   -v          completion  hear        see
+    --verbose   -h          -x          crush       help        smash
+
+
+Another potential usage could be to pre-generate a completion file for, and
+distribute it with, your tool.
+
+
 # Reference
@@ -205,9 +232,9 @@
 
-- `<Cmdln>.prototype.init(opts, args, cb)` Hook run after option processing
+- `CLI.prototype.init(opts, args, cb)` Hook run after option processing
   (`this.opts` is set), but before the subcommand handler is run.
 
-- `<Cmdln>.prototype.fini(subcmd, cb)` Hook run after the subcommand handler is
+- `CLI.prototype.fini(subcmd, cb)` Hook run after the subcommand handler is
   run.
 
-- `<Cmdln>.showErrStack` boolean. Set to true to have `cmdln.main()`, if used,
+- `cli.showErrStack` boolean. Set to true to have `cmdln.main()`, if used,
   print a full stack on a shown error. When wanted, this is typically set
@@ -217,11 +244,14 @@ in If you want this option it is typically
 
-- `<Cmdln>.handlerFromSubcmd(<subcmd>)` will return the appropriate
+- `cli.handlerFromSubcmd(<subcmd>)` will return the appropriate
   `do_<subcmd>` method that handles the given sub-command. This resolves
   sub-command aliases.
 
-- `<Cmdln>.helpFromSubcmd(<subcmd>)` will return the help string for
+- `cli.helpFromSubcmd(<subcmd>)` will return the help string for
   that subcmd *or*, if defined, the help function defined for that subcmd.
   This is used by the default `do_help` implementation.
 
+- `cli.bashCompletion()` generates and returns bash completion for
+  the CLI.
 
+
 ## `cmdln.main()`
@@ -228,0 +258,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

55209

increased by8.37%

Number of package files

9

increased by12.5%

Lines of code

824

increased by8.28%

Number of lines in readme file

265

increased by12.77%

No dependency changes