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.

In addition, @vim-fall/std provides the following functions to refine and compose individual modules:

Name	Description
refineSource	Applies multiple Refiners to Source to refine and process generated items.
refineCurator	Applies multiple Refiners to Curator to refine and process generated items.
composeSources	Combines multiple Sources to create a new Source that sequentially retrieves items from all Sources.
composeMatchers	Combines multiple Matchers to create a new Matcher that filters items through all Matchers.
composeCurators	Combines multiple Curators to create a new Curator that retrieves items through all Curators.
composeSorters	Combines multiple Sorters to create a new Sorter that sorts items through all Sorters.
composeRenderers	Combines multiple Renderers to create a new Renderer that processes items through all Renderers.
composePreviewers	Combines multiple Previewers to create a new Previewer that generates content from any of the Previewers.
composeActions	Combines multiple Actions to create a new Action that invokes all Actions.

By combining these modules, Fall enables flexible functionality.

For example, the following code demonstrates how to create a Source that retrieves files recorded in Vim’s oldfiles that exist in the current directory:

import { refineSource } from "jsr:@vim-fall/std"
import * as builtin from "jsr:@vim-fall/std/builtin"

const source = refineSource(
  builtin.source.oldfiles,
  builtin.refiner.exists,
  builtin.refiner.cwd,
);

Similarly, the following example shows how to create an Action that change directory and open.

import { composeActions } from "jsr:@vim-fall/std"
import * as builtin from "jsr:@vim-fall/std/builtin"

const action = composeActions(
  builtin.action.cd,
  builtin.action.open,
);