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][command-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][command-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 methodshift-left-word.
For completing partial matches, we provide the matchLeftWord methodmatch-left-word.
To create non-terminal options, we can use the method resolveInforesolve-info 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.

Donating

Support this project and others by twolfsongittip via gittip.
!Support via Gittipgittip-badgegittip

Unlicense

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.