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.

Architecture

Fall decomposes the functionality of a Fuzzy Finder into the following modules:

Name	Description
Coordinator	A module that determines the style and layout of the picker.
Theme	A theme structure used to define the style of the picker.
Source	Retrieves data from arbitrary sources and generates an AsyncIterableIterator of items.
Matcher	Filters the AsyncIterableIterator received from the Source based on user input.
Curator	Combines Source and Matcher, performing data retrieval and filtering based on user input.
Sorter	Sorts items received from the Matcher or Curator.
Renderer	Processes sorted items from the Sorter for user display.
Previewer	Generates content for previewing the currently selected item.
Action	Executes actions on the selected target item.

In addition, Fall provides the following features to refine and combine individual modules:

Name	Description
Refiner	Applies to Source or Curator to refine and process generated items.
Source composer	Combines multiple Sources to create a new Source that sequentially retrieves items from all Sources.
Matcher composer	Combines multiple Matchers to create a new Matcher that filters items through all Matchers.
Curator composer	Combines multiple Curators to create a new Curator that retrieves items through all Curators.
Sorter composer	Combines multiple Sorters to create a new Sorter that sorts items through all Sorters.
Renderer composer	Combines multiple Renderers to create a new Renderer that processes items through all Renderers.
Previewer composer	Combines multiple Previewers to create a new Previewer that generates content from any of the Previewers.

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 a Renderer that displays NerdFont icons and relative paths:

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

const renderer = composeRenderer(
  builtin.renderer.nerdfont,
  builtin.renderer.relativePath,
);

Customization

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.