Filters - FluxxField/smart-motion.nvim GitHub Wiki

Filters

Filters are the third stage in the SmartMotion pipeline. They operate after targets have been extracted and decide which ones should remain visible or selectable.

[!TIP] Extractors generate all possible targets. Filters narrow them down based on context - like direction, visibility, or custom logic.


? What a Filter Does

A filter receives a list of targets (from an extractor) and returns a modified version of that list.

Typical filter jobs:

  • Remove targets before/after the cursor (based on motion_state.direction)
  • Limit targets to those visible in the current window
  • Filter by custom metadata or motion-specific needs

?? Example Usage

Defined in the pipeline:

pipeline = {
  collector = "lines",
  extractor = "words",
  filter = "filter_visible_lines",
  visualizer = "hint_start",
}

This would:

  • Extract words from all lines
  • Only keep those visible in the current window

?? Built-in Filters

Name Description
default No filtering - returns all targets unchanged
filter_visible_lines Keeps only targets in visible screen range

[!NOTE] Directional filtering (before/after cursor) is expected to move to filters in future versions.


? Building Your Own Filter

A filter is a simple Lua function:

---@type SmartMotionFilterModule
local M = {}

function M.run(targets, ctx, cfg, motion_state)
  return vim.tbl_filter(function(target)
    return target.row > ctx.cursor_line  -- only after cursor
  end, targets)
end

return M

Then register it:

require("smart-motion.core.registries")
  :get().filters.register("only_after", MyFilter)

?? Future Possibilities

You could build filters for:

  • Limiting based on text contents
  • Highlight group presence
  • Diagnostic severity from LSP
  • Target types (e.g., filter out lines but keep words)

Continue to: