npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

completion

v1.0.3

Published

Completion library for CLI commands

Downloads

871

Readme

completion Build status

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

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

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.

Support 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.