Completion library for CLI commands
This was built as part of foundry, a CLI utility for making releases painless.
$ git chec|
$ git checkout |
$ git checkout dev/|
dev/hello.world dev/goodbye.moon
$ git chec|dev/
$ git checkout |dev/
Install the module with: npm install completion
var Completion = require('completion');
var completion = new Completion({
name: 'git',
commands: [{
name: 'checkout',
completion: function (info, cb) {
// For `git checkout dev/|`
// info.words.value = ['git', 'checkout', 'dev/']
// info.word.partialLeft = 'dev/'
var that = this;
getGitBranches(function (err, allBranches) {
if (err) {
return cb(err);
}
// Match 'dev/' === 'dev/' (from 'dev/hello')
var partialLeftWord = info.word.partialLeft;
var branches = that.matchLeftWord(partialLeftWord, allBranches);
cb(null, branches);
});
}
}]
});
completion.complete({
// `git chec|`
line: 'git chec',
cursor: 8
}, function (err, results) {
results; // ['checkout']
});
In bash
, tab completion will override the the left half of the current word.
As a result, for cases like:
$ git chec|
$ git checkout| # requires ['checkout'] to be returned
Unfortunately, while we can deal with commands, we cannot predict the values of those.
You will still be responsible for handling of right partials in the autocompleted items.
$ git checkout a|c
[
'abc', # `git checkout abc` - Checkout `abc` branch
'aaa' # `git checkout aaa c` - Chekckout `c` file from `aaa` branch
]
completion
exposes the Completion
constructor via its module.exports
new Completion(tree)
Create a new completion
instance
Object
- Outline of a program/command
String
- Command that is being executed (e.g. git
, checkout
)Object[]
- Optional array of objects that represent options
String
- Name of option (e.g. --help
)Function
- Optional function to complete the remainder of the invocation
completion
is specified, we assume this is terminal and stop recursingcommands/option completion
section
Object[]
- Optional array of new tree
instances to complete against
completion
as they are contradictoryFunction
- Optional completion function to determine results for a command
commands/option completion
section
completion.complete(params, cb)
Get potential completion matches for given parameters
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
- Error-first callback function that receives matches
cb
should have a signature of function (err, results)
command/option completion
functionsoptions
and commands
share a common completion function signature, function (info, cb)
Each completion
function will be executed with the command node as its this
context
Object
- Information about original input
String[]
- Words matched from words.partialLeft
while walking the treeString[]
- Unmatched words that need to be/can be matched againstFunction
- Error-first callback function to return matches via
cb
has a signature of function (err, results)
For options, it is often preferred to remove more words that are matched (e.g. -m <msg>
). For this, we suggest using the shiftLeftWord
method.
For completing partial matches, we provide the matchLeftWord
method.
To create non-terminal options, we can use the method resolveInfo
to keep on searching against the remainingLeft
words.
completion.shiftLeftWord(info)
Helper function to shift word from info.words.remainingLeft
to info.words.matchedLeft
Object
- Information passed into completion
functonvar info = {words: {remainingLeft: ['hello', 'world'], matchedLeft: []}};
info = this.shiftLeftWord(info);
info; // {words: {remainingLeft: ['world'], matchedLeft: ['hello']}}
completion.matchLeftWord(leftWord, words)
Helper function to find words from words
that start with leftWord
String
- Word to match left content of
leftWord
gets its name from usually coming from words.partialLeft
String[]
- Array of words to filter againstReturns:
String[]
- Matching words from words
that start with leftWord
this.matchLeftWord('hello', ['hello-world', 'hello-there', 'goodbye-moon']);
// ['hello-world', 'hello-there'];
completion.resolveInfo(info, cb)
Recursively find matches against the Completion's tree
with a given info
Object
- CLI information provided by twolfson/line-info
params
to its current equivalent by twolfson/line-info
Function
- Error first callback function that receives matches
cb
should be the same as in completion.complete
An example of git
would be
var gitCompletion = new Completion({
name: 'git',
options: [{
// `git --help`, a terminal option
name: '--help'
}],
commands: [{
// `git checkout master`
name: 'checkout',
option: [{
// `git checkout -b dev/hello`
name: '-b',
completion: function (info, cb) {
// `-b` was matched by `completion` so keep on recursing
return this.resolveInfo(info, cb);
}
}],
completion: function getGitBranches (info, cb) {
// Get git branches and find matches
}
}, {
name: 'remote',
commands: [{
// `git remote add origin [email protected]:...`
// No possible completion here
name: 'add'
}, {
// `git remote rm origin`
name: 'rm',
completion: function getGitBranches (info, cb) {
// Get git branches and find matches
}
}]
}]
});
gitCompletion.complete({
// `git remo|add`
line: 'git remoadd',
cursor: 8
}, function (err, results) {
results; // ['remote']
});
gitCompletion.complete({
// `git remote |`
line: 'git remote ',
cursor: 11
}, function (err, results) {
results; // ['add', 'remove']
});
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 grunt and test via npm test
.
Support this project and others by twolfson via gittip.
As of Dec 15 2013, Todd Wolfson has released this repository and its contents to the public domain.
It has been released under the UNLICENSE.