Shell completion for Commander.js
This was built as part of foundry, a CLI utility for making releases painless.
$ npm pub|
$ npm publish |
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);
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
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
Function
- Error-first callback that will callback with matches
-completion
should have a signature of function (info, cb)
Object
- Collection of distilled information about original input
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
Object
- Information similar to that passed in by bash's
tab completion
String
- Input to complete against (similar to COMP_LINE
)Number
- Index within line
of the cursor (similar to COMP_POINT
)Function
- Optional error-first callback function that receives matches
cb
should have a signature of function (err, results)
cb
is not provided, err
will be thrown and results
will be printed to stdout
via console.log
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']
});
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
.
Support this project and others by twolfson via donations.
http://twolfson.com/support-me
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.