commander-completion

Shell completion for commander.js

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
commander-completion
2541.0.15 years ago9 years agoMinified + gzip package size for commander-completion in KB

Readme

commander-completion Build status
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.

Donating

Support this project and others by twolfsontwolfson-projects via donationstwolfson-support-me.

Unlicense

As of Dec 16 2013, Todd Wolfson has released this repository and its contents to the public domain.
It has been released under the UNLICENSE.