Generators
Generators let you run shell commands to generate a list of Suggestions for a given Argument.
Generators are used to programmatically generate suggestion objects. For instance, a generator can fetch a list of git remotes, grab all the folders in the current working directory, or even hit an API endpoint.
For a high level overview of Generators and their usage, see "Dynamic Suggestions".
Quick Summary
Generators let you run shell commands on the user's device to generate suggestions for arguments
Basic Generators
Run a shell command to provide dynamic suggestions.
See "Basic Generators" to understand the most common usage pattern.
Templates
Some generators, like the ones for filepaths and folders, are so common across CLI tools that it doesn't make sense for every spec to reimplement them from scratch.
See "Templates" to quickly provide rich suggestions for files and folders.
Contextual Generators
Provide suggestions that require context from other flags or options in the current edit buffer.
To handle this case, a Generator needs to run a script
which incorporates text that the user has typed.
heroku addons:remove --app my-example-app |
For example, when completing this heroku
command, Fig should only suggest addons that are associated with the specific app, my-example-app
.
See "Contextual Generators" to learn how to run a
script
that incorporates text from the user's edit buffer.
Triggers & Filtering
Provide a new set of suggestions after the user types a certain character, like the /
in a filepath, for instance.
See "Reimplementing the Filepath Generator" for more information of how to use
triggers
andfilterTerm
.
Caching & Debouncing
Suggestions are computed by an expensive function — a web request, for instance — and should be cached or debounced.
See "Making an HTTP Request from a Generator" for details on how to handle expensive functions.
Custom Generators
Write imperative code where suggestions must be recomputed on every keypress, to handle tools with non-standard parsing, like chmod
.
See "Custom Generators" to learn more.