Completion NPM

completion

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/

Getting Started

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']
});

How it works

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
]

Documentation

completion exposes the Completion constructor via its module.exports

`new Completion(tree)`

Create a new completion instance

tree Object - Outline of a program/command
- name String - Command that is being executed (e.g. git, checkout)
- options Object[] - Optional array of objects that represent options
  - name String - Name of option (e.g. --help)
  - completion Function - Optional function to complete the remainder of the invocation
    - If no completion is specified, we assume this is terminal and stop recursing
    - More info is available in the commands/option completion section
- commands Object[] - Optional array of new tree instances to complete against
  - This cannot exist on the same node as completion as they are contradictory
- completion Function - Optional completion function to determine results for a command
  - More info is available in the commands/option completion section

`completion.complete(params, cb)`

Get potential completion matches for given parameters

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 - Error-first callback function that receives matches
- cb should have a signature of function (err, results)

`command/option completion` functions

options 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

info Object - Information about original input
- Content will be information from twolfson/line-info
- We provide 2 additional properties
  - words.matchedLeft String[] - Words matched from words.partialLeft while walking the tree
  - words.remainingLeft String[] - Unmatched words that need to be/can be matched against
cb Function - 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

info Object - Information passed into completion functon

var 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

leftWord String - Word to match left content of
- leftWord gets its name from usually coming from words.partialLeft
words String[] - Array of words to filter against

Returns:

matchedWords 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

info Object - CLI information provided by twolfson/line-info
- This is converted from params to its current equivalent by twolfson/line-info
cb Function - Error first callback function that receives matches
- cb should be the same as in completion.complete

Examples

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 git@github.com:...`
      // 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']
});

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 grunt and test via npm test.