DocsReferenceGeneratorTriggers and filtering

Triggers & Filtering

Provide a new set of suggestions after the user types a certain character, like the / in a filepath.

Trigger

Defines a trigger that determines when to regenerate suggestions for this argument by re-running the generators.

By default, Fig runs the generators for an argument once when the user is about to enter the argument. Afterwards, as the user continues typing, suggestions are filtered from the original list of generated suggestions.

Trigger is used when we need the generators to regenerate all the unfiltered, base level suggestions.

Types

  • String
    • e.g. if Trigger: "/", re-run the generators every time the last index of "/" is different between the previous input and the current input
  • Function
    • Write a function to define custom logic for when a Trigger should fire.
fn(currentString: str, previousString: str): bool { }

e.g. fn("desk", "Desktop/") if fn was:

fn function (curr,prev) {
  if (curr.lastIndexOf("/") !== prev.lastIndexOf("/")) return true
  else return false
})

When would you want to use Trigger?

When you use cd in Fig, we set a trigger for /.

Every time a / is encountered, Fig will run the generator again to find the new folders under the new working directory.

Filter Term

A function to determine what part of the string the user is currently typing we should use to filter our suggestions.

The default is the full string containing the user's input.

const filterTerm: (currentString: string): string => {
  // ...
}

When would you want to use Filter Term?

e.g. For cd, the user may have typed ~/Desktop/b

  • Our trigger function tells us to regenerate suggestions when we see a new /
  • Our suggestions show all the folders in the ~/Desktop directory
  • As the user types, Fig defaults to filter over the suggestions using ~/Desktop/b as the search term. We only want the search term to be "b"

Here is the function we would write:

const generator: Fig.Generator = {
  filterTerm: (curr) => {
    if (curr.includes("/")) {
      return curr.slice(curr.lastIndexOf("/") + 1);
    } else {
      return curr;
    }
  },
};

Because this use case may be common, we have also defined a string that makes this simpler. Here, we filter by everything to the right of the last occurrence of our filterTerm property.

filterTerm: "/"

Finally, if you have multiple generators, Fig will only take into account the very last filterTerm function or string you define.

Note: If you want to use multiple generators for an argument, and one of the generators is template suggestions, you should make sure to include the template generator first in the generators array and to define your filterTerm function after.