commander-completion 

Shell completion for [Commander.js][]

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

[Commander.js]: https://github.com/tj/commander.js
[foundry]: https://github.com/twolfson/foundry

``js
$ npm pub|
$ npm publish |
`

Getting Started


Install the module with: npm install commander-completion

`js
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.

$3


Add new completion methods to Commander.js' Command objects

- commander Object - Instance of Commander.js

$3


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)

[twolfson/line-info]: https://github.com/twolfson/line-info#lineinfoparams

$3


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

`js
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 twolfson][twolfson-projects] via [donations][twolfson-support-me].

[twolfson-projects]: http://twolfson.com/projects
[twolfson-support-me]: http://twolfson.com/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][].

[UNLICENSE]: UNLICENSE