Commander-completion NPM

commander-completion

Shell completion for Commander.js

This was built as part of foundry, a CLI utility for making releases painless.

$ npm pub|
$ npm publish |

Getting Started

Install the module with: npm install commander-completion

var program = require('commander-completion')(require('commander'));
program.name = 'git';
program
  .command('checkout')
  .completion(function (info, cb) {
    // For `git checkout dev/|`
    // info.words.value = ['git', 'checkout', 'dev/']
    // info.word.partialLeft = 'dev/'
    getGitBranches(function (err, allBranches) {
      if (err) {
        return cb(err);
      }

      var branches = allBranches.filter(function (branch) {
        // 'chec' === 'chec' (from 'checkout')
        return partialLeftWord === branch.substr(0, partialLeftWord.length);
      });
      cb(null, branches);
    });
  })
  .action(function () {
    // Checkout a git branch
  });
program
  .command('completion')
  .action(function () {
    program.completion({
      line: process.env.COMP_LINE,
      cursor: process.env.COMP_POINT
    });
  });

// Parse in arguments (e.g. `COMP_LINE="git che" COMP_POINT=7 git completion`)
// Logs: ['checkout']
program.parse(process.argv);

Documentation

commander-completion exposes a mixin function, mixinCommanderCompletion, as its module.exports. After we mixin to Commander.js, we add more methods onto command() objects.

Currently, you are required to specify the name property of your program.

`mixinCommanderCompletion(commander)`

Add new completion methods to Commander.js' Command objects

commander Object - Instance of Commander.js

`Command.completion(completionFn)`

New method available on Commander.js Commands (e.g. program.command('remote').completion(completionFn))

Save completion function to call when completing the current command

completionFn Function - Error-first callback that will callback with matches -completion should have a signature of function (info, cb)
- info Object - Collection of distilled information about original input
  - The format will be the returned value from twolfson/line-info
- cb Function - Error-first callback function to run with matches
  - cb has a signature of function (err, results)

`Command.complete(params, cb)`

New method available on Commander.js Commands (e.g. program.command('remote').complete(params, cb))

Get completion results for current command

params Object - Information similar to that passed in by bash's tab completion
- line String - Input to complete against (similar to COMP_LINE)
- cursor Number - Index within line of the cursor (similar to COMP_POINT)
cb Function - Optional error-first callback function that receives matches
- cb should have a signature of function (err, results)
- If cb is not provided, err will be thrown and results will be printed to stdout via console.log

Examples

An full example of git would be

var program = require('commander-completion')(require('commander'));
program.name = 'git';
program
  // `git checkout master`
  .command('checkout')
  .option('-b', 'Checkout new branch') // `git checkout -b dev/hai`
  .completion(function (info, cb) {
    // Get git branches and find matches
  })
  .action(function () {
    // Checkout a `git` branch
  });
var remote = program.command('remote');
remote
  // `git remote add origin git@github.com:...`
  // No possible tab completion here
  .command('add')
  .action(function () {
    // Add a `git` remote
  });
remote
  // `git remote rm origin`
  .command('rm')
  .completion(function (info, cb) {
    // Get git branches and find matches
  })
  .action(function () {
    // Remove a `git` remote
  });

program.complete({
  // `git remo|add`
  line: 'git remoadd',
  cursor: 8
}, function (err, results) {
  results; // ['remote']
});

program.complete({
  // `git remote |`
  line: 'git remote ',
  cursor: 11
}, function (err, results) {
  results; // ['add', 'rm']
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint and test via npm test.