Docs | Autocomplete

Autocomplete

Vorpal supports powerful, robust tabbed autocompletion by default, along with custom autocompletion on both commands and options.

This feature is designed to exactly mirror the Linux-style tabbed autocompletion you are familiar with.

• How it Works
• Command Autocompletion
  • Using a Function
  • Using a Callback
  • Using a Promise
• Option Autocompletion
  • Using an Array
  • Using a Function
  • Using a Callback
  • Using a Promise

How it works

Let's suppose you are running a Vorpal app with three commands registered: eat, feed and water. When you start the app and press tab twice, you'll get those three commands suggested:

$ node ./myapp.js
app$ [tab] [tab]
eat  feed  water

Typing f and then pressing tab will autocomplete to feed:

app$ f [tab]
app$ feed 

Command Autocompletion

Now suppose we want to suggest that one should feed the cat, dog or horse. We would register the following command in our app:

vorpal.command('feed [animal]')
  .autocomplete(['cat', 'dog', 'horse'])
  .action(feedThem);

On pressing tab now, we would get those suggestions:

$ node ./myapp.js
app$ feed [tab] [tab]
cat  dog  horse

Using a Function

If the list of animals we feed is somewhat dynamic, we can run a function to determine it:

vorpal.command('feed [animal]')
  .autocomplete({
    data: function () {
      return getAnimals;
    }
  })
  .action(feedThem);

Using a Callback

If we need it to be async, we can pass in a callback as the second parameter (the first is what the user has typed so far):

vorpal.command('feed [animal]')
  .autocomplete({
    data: function (input, callback) {
      getAnimals(function (array) {
        callback(array);
      });
    }
  })
  .action(feedThem);

Using a Promise

We can also do a Promise:

vorpal.command('feed [animal]')
  .autocomplete({
    data: function () {
      return getAnimalsPromise;
    }
  })
  .action(feedThem);

Option Autocompletion

We can also give autocompletion for a command's options.

Vorpal will automatically list out the possible options for a given command. Suppose feed had the options --day and --amount. After typing feed horse, we can add a - and press tab twice to get a list of the available options:

app$ feed horse -[tab] [tab]
--amount  --day

We can then press tab to autocomplete a given option:

app$ feed horse --d [tab]
app$ feed horse --day 

Using an Array

Beyond just listing which options are available, Vorpal can autocomplete the possible option values based on information you provide.

To list the days of the week as possible values for the day option, pass an array into the third parameter of command.option():

var days = ['Monday', 'Tuesday', 'Wednesday', '...'];
vorpal.command('feed [animal]')
  .option('--day', 'Day of the week to feed', days)
  .action(feedThem);

And now:

app$ feed horse --day [tab] [tab]
Monday  Tuesday  Wednesday  Thursday  Friday  Saturday  Sunday

Using a Function

We can also call a function to get the possible values if needed:

vorpal.command('feed [animal]')
  .option('--day', 'Day of the week to feed', function () {
    return getDaysOfWeek;
  });
  .action(feedThem);

Using a Callback

We can turn it async by passing in a callback as the second parameter:

vorpal.command('feed [animal]')
  .option('--day', 'Day of the week to feed', function (input, callback) {
    getDaysOfWeek(callback);
  });
  .action(feedThem);

Using a Promise

We can return a promise as well:

vorpal.command('feed [animal]')
  .option('--day', 'Day of the week to feed', function () {
    return getDaysOfWeekPromise;
  });
  .action(feedThem);