Customization

In Fall, settings written in TypeScript to enhance Fall’s behavior are categorized as “Customization.” This specifically refers to modifications made to the user customization file, which can be accessed via the FallCustom command.

Note

Read Architecture to find the purpose of each modules.

When you run the FallCustom command, the user customization file opens. In this file, Pickers are defined, and only the Pickers defined here can be used in Fall.

For example, if you create a user customization file without defining any Pickers, as shown below, Fall will not have any Pickers available:

import type { Entrypoint } from "jsr:@vim-fall/custom";

export const main: Entrypoint = () => {
  // WARNING: Since no Pickers are defined, Fall provides no functionality
};

A Picker can be defined by specifying at least its name, source, matcher, and actions. Additionally, if no additional options are required, modules can be passed as functions directly:

import type { Entrypoint } from "jsr:@vim-fall/custom";
import * as builtin from "jsr:@vim-fall/std/builtin";

export const main: Entrypoint = ({ definePickerFromSource }) => {
  definePickerFromSource(
    "file",
    // builtin.source.file and builtin.source.file() are treated as equivalent
    builtin.source.file,
    {
      matchers: [builtin.matcher.fzf],
      actions: {
        open: builtin.action.open,
      },
      defaultAction: "open",
    },
  );
};

To define a Picker, you use the definePickerFromSource function as shown above. The main function receives the following arguments:

Argument Name	Description
denops	A Denops instance.
definePickerFromSource	A function to define a Picker using a Source and a Matcher.
definePickerFromCurator	A function to define a Picker using a Curator.
refineActionPicker	A function to refine the Picker used for selecting actions.
refineSetting	A function to adjust various settings.

Users can utilize these functions to define Pickers and customize their configurations.

See @vim-fall/std/builtin for available official builtin extensions and @vim-fall/extra for available official extra extensions.　And see ./denops/fall/_assets/default.custom.ts for the latest default customization file.