completion

completion

Completion library for words, commands, and sentences

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({
  git: {
    checkout: 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 partialLeftWord = info.word.partialLeft;
        var branches = allBranches.filter(function (branch) {
          // 'chec' === 'chec' (from 'checkout')
          return partialLeftWord === branch.substr(0, partialLeftWord.length);
        });
        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 program
  • Each key represents a new command (e.g. git, checkout)
  • Each value can be
    • An object representing another layer of commands
    • A function that will callback with potential matches
      • The function should be error-first; have a signature of function (info, cb)
      • info Object - Collection of distilled information
        • 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)
    • null representing a terminal function which has no further predictive input
      • If you want to list out files, do so. Don't use null for that case.

completion.complete(params, cb)

Get potential completion matches

• 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)

Examples

An example of git would be

var gitCompletion = new Completion({
  git: {
    // `git checkout master`
    checkout: function (info, cb) {
      // Get git branches and find matches
    },
    remote: {
      // `git remote add origin [e-mail]:...`
      add: null, // No possible tab completion here
      // `git remote rm origin`
      rm: function (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 twolfson via gittip.

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.