Basic Generators

Run a shell command to provide dynamic suggestions.

A Generator defines a function that transforms the output of a shell command into an array of Suggestion objects.

For example, the following is an Argument object (with an associated Generator) that could provide branch suggestions for git checkout,

{
  name: "branch",
  generators: [
    {
      script: "git branch -l",
      postProcess: function(out) {
        return out.split('\n').map(branch => {
          return { name: branch, description: "branch"}
        })
      }
    }
  ]
}

The script property is executed as a command in the same working directory as the interactive shell.

See "Executing Shell Commands" for more details.

The result of running git branch -l looks something like this:

$ git branch -l
  main
  staging
  mschrage/aws
  mschrage/feature-abc
  mschrage/eng-334-build-universal-binary-to-support-m1
  mschrage/filepath-issues
  mschrage/fix-cp

The output of the script is passed to to the postProcess function, which converts the raw string to a list of Suggestion objects. In the example above, the string is split on the newline character, then each line is iterated over and turned into a suggestion.

This is a very common pattern when building your own generator.

1. Find a shell command that outputs relevant information.
2. Write a function that parses it into a richer format — adding a relevant description, setting a custom icon or determining the appropriate priority.

Tip: You can use the contents of files, like package.json, in a Generator by running the cat command.