utility/telescope: custom extensions API

modules/plugins/utility/telescope/config.nix

@@ -5,8 +5,8 @@
   ...
 }: let
   inherit (lib.modules) mkIf;
-  inherit (lib.strings) optionalString;
-  inherit (lib.lists) optionals;
+  inherit (lib.strings) optionalString concatMapStringsSep;
+  inherit (lib.lists) optionals concatLists;
   inherit (lib.nvim.binds) pushDownDefault mkKeymap;
 
   cfg = config.vim.telescope;
@@ -16,7 +16,7 @@
 in {
   config = mkIf cfg.enable {
     vim = {
-      startPlugins = ["plenary-nvim"];
+      startPlugins = ["plenary-nvim"] ++ concatLists (map (x: x.packages) cfg.extensions);
 
       lazy.plugins.telescope = {
         package = "telescope";
@@ -28,11 +28,14 @@ in {
           vim.g.loaded_telescope = nil
         '';
 
-        after = ''
+        after = let
+          enabledExtensions = map (x: x.name) cfg.extensions;
+        in ''
           local telescope = require("telescope")
           ${optionalString config.vim.ui.noice.enable "telescope.load_extension('noice')"}
           ${optionalString config.vim.notify.nvim-notify.enable "telescope.load_extension('notify')"}
           ${optionalString config.vim.projects.project-nvim.enable "telescope.load_extension('projects')"}
+          ${concatMapStringsSep "\n" (x: "telescope.load_extension('${x}')") enabledExtensions}
         '';
 
         cmd = ["Telescope"];

modules/plugins/utility/telescope/telescope.nix

@@ -1,12 +1,15 @@
 {
+  config,
   pkgs,
   lib,
   ...
 }: let
-  inherit (lib.options) mkEnableOption mkOption;
-  inherit (lib.types) int str listOf float bool either enum submodule attrsOf;
+  inherit (lib.options) mkOption mkEnableOption literalExpression;
+  inherit (lib.types) int str listOf float bool either enum submodule attrsOf anything package;
   inherit (lib.nvim.binds) mkMappingOption;
   inherit (lib.nvim.types) mkPluginSetupOption luaInline;
+
+  cfg = config.vim.telescope;
   setupOptions = {
     pickers.find_files.find_command = mkOption {
       description = "cmd to use for finding files";
@@ -16,10 +19,6 @@
 
     defaults = {
       vimgrep_arguments = mkOption {
-        description = ''
-          Defines the command that will be used for `live_grep` and `grep_string` pickers.
-          Make sure that color is set to `never` because telescope does not yet interpret color codes.
-        '';
         type = listOf str;
         default = [
           "${pkgs.ripgrep}/bin/rg"
@@ -32,114 +31,169 @@
           "--hidden"
           "--no-ignore"
         ];
+
+        description = ''
+          Defines the command that will be used for `live_grep` and `grep_string` pickers.
+          Make sure that color is set to `never` because telescope does not yet interpret color codes.
+        '';
       };
+
+      pickers.find_command = mkOption {
+        type = either (listOf str) luaInline;
+        default = ["${pkgs.fd}/bin/fd"];
+        description = ''
+          Command to use for finding files. If using an executable from {env}`PATH` then you must
+          make sure that the package is available in [](#opt-vim.extraPackages).
+        '';
+      };
+
       prompt_prefix = mkOption {
-        description = "Shown in front of Telescope's prompt";
         type = str;
         default = "     ";
+        description = "Shown in front of Telescope's prompt";
       };
+
       selection_caret = mkOption {
-        description = "Character(s) to show in front of the current selection";
         type = str;
         default = "  ";
+        description = "Character(s) to show in front of the current selection";
       };
+
       entry_prefix = mkOption {
-        description = "Prefix in front of each result entry. Current selection not included.";
         type = str;
         default = "  ";
+        description = "Prefix in front of each result entry. Current selection not included.";
       };
+
       initial_mode = mkOption {
-        description = "Determines in which mode telescope starts.";
         type = enum ["insert" "normal"];
         default = "insert";
+        description = "Determines in which mode telescope starts.";
       };
+
       selection_strategy = mkOption {
-        description = "Determines how the cursor acts after each sort iteration.";
         type = enum ["reset" "follow" "row" "closest" "none"];
         default = "reset";
+        description = "Determines how the cursor acts after each sort iteration.";
       };
+
       sorting_strategy = mkOption {
-        description = ''Determines the direction "better" results are sorted towards.'';
         type = enum ["descending" "ascending"];
         default = "ascending";
+        description = ''Determines the direction "better" results are sorted towards.'';
       };
+
       layout_strategy = mkOption {
-        description = "Determines the default layout of Telescope pickers. See `:help telescope.layout`.";
         type = str;
         default = "horizontal";
+        description = "Determines the default layout of Telescope pickers. See `:help telescope.layout`.";
       };
+
       layout_config = mkOption {
-        description = ''
-          Determines the default configuration values for layout strategies.
-          See telescope.layout for details of the configurations options for
-          each strategy.
-        '';
         default = {};
         type = submodule {
           options = {
             horizontal = {
               prompt_position = mkOption {
-                description = "";
-                type = str;
+                type = enum ["top" "bottom"];
                 default = "top";
+                description = "Where to place prompt window";
               };
+
               preview_width = mkOption {
-                description = "";
                 type = float;
                 default = 0.55;
+                description = "Change the width of Telescope's preview window";
               };
             };
+
             vertical = {
               mirror = mkOption {
-                description = "";
                 type = bool;
                 default = false;
+                description = "Flip the location of the results/prompt and preview windows";
               };
             };
+
             width = mkOption {
-              description = "";
               type = float;
               default = 0.8;
+              description = "How wide to make Telescope's entire layout";
             };
+
             height = mkOption {
-              description = "";
               type = float;
               default = 0.8;
+              description = "How tall to make Telescope's entire layout";
             };
+
             preview_cutoff = mkOption {
-              description = "";
               type = int;
               default = 120;
+              description = "When lines are less than this value, the preview will be disabled";
             };
           };
         };
+
+        description = ''
+          Determines the default configuration values for layout strategies.
+          See `telescope.layout` for details of the configurations options for
+          each strategy.
+        '';
       };
+
       file_ignore_patterns = mkOption {
-        description = "A table of lua regex that define the files that should be ignored.";
         type = listOf str;
         default = ["node_modules" "%.git/" "dist/" "build/" "target/" "result/"];
+        description = "File patterns to omit from Telescope results";
       };
-      color_devicons = mkOption {
-        description = "Boolean if devicons should be enabled or not.";
-        type = bool;
-        default = true;
-      };
+
+      color_devicons = mkEnableOption "colored devicons";
+
       path_display = mkOption {
-        description = "Determines how file paths are displayed.";
         type = listOf (enum ["hidden" "tail" "absolute" "smart" "shorten" "truncate"]);
         default = ["absolute"];
+        description = "Determines how file paths are displayed.";
       };
+
       set_env = mkOption {
-        description = "Set an environment for term_previewer";
         type = attrsOf str;
-        default = {
-          COLORTERM = "truecolor";
-        };
+        default = {COLORTERM = "truecolor";};
+        description = "Set an environment for term_previewer";
       };
+
       winblend = mkOption {
-        description = "pseudo-transparency of keymap hints floating window";
         type = int;
         default = 0;
+        description = "Pseudo-transparency of keymap hints floating window";
+      };
+
+      extensions = mkOption {
+        type = attrsOf anything;
+        default = builtins.foldl' (acc: x: acc // (x.setup or {})) {} cfg.extensions;
+        description = "Attribute set containing per-extension settings for Telescope";
+      };
+    };
+  };
+
+  extensionOpts = {
+    options = {
+      name = mkOption {
+        type = str;
+        description = "Name of the extension, will be used to load it with a `require`";
+      };
+
+      packages = mkOption {
+        type = listOf (either str package);
+        default = [];
+        description = "Package or packages providing the Telescope extension to be loaded.";
+      };
+
+      setup = mkOption {
+        type = attrsOf anything;
+        default = {};
+        example = {fzf = {fuzzy = true;};};
+        description = "Named attribute set to be inserted into Telescope's extensions table.";
       };
     };
   };
@@ -174,5 +228,24 @@ in {
     enable = mkEnableOption "telescope.nvim: multi-purpose search and picker utility";
 
     setupOpts = mkPluginSetupOption "Telescope" setupOptions;
+
+    extensions = mkOption {
+      type = listOf (submodule extensionOpts);
+      default = [];
+      example = literalExpression ''
+        [
+          {
+            name = "fzf";
+            packages = [pkgs.vimPlugins.telescope-fzf-native-nvim];
+            setup = {fzf = {fuzzy = true;};};
+          }
+        ]
+      '';
+      description = ''
+        Individual extension configurations containing **name**, **packages** and **setup**
+        fields to resolve dependencies, handle `load_extension` calls and add the `setup`
+        table into the `extensions` portion of Telescope's setup table.
+      '';
+    };
   };
 }