plugins/toggleterm: switch to mkNeovimPlugin

plugins/utils/toggleterm.nix

@@ -5,199 +5,253 @@
   pkgs,
   ...
 }:
-with lib; let
+with lib;
-  cfg = config.plugins.toggleterm;
+  helpers.neovim-plugin.mkNeovimPlugin config {
-in {
+    name = "toggleterm";
-  options.plugins.toggleterm = {
+    originalName = "toggleterm.nvim";
-    enable = mkEnableOption "toggleterm";
+    defaultPackage = pkgs.vimPlugins.toggleterm-nvim;
 
-    package = helpers.mkPackageOption "toggleterm" pkgs.vimPlugins.toggleterm-nvim;
+    maintainers = [maintainers.GaetanLepage];
 
-    size = helpers.defaultNullOpts.mkStrLuaFnOr types.number "12" ''
+    # TODO: introduced 2024-04-07, remove on 2024-06-07
-      Size of the terminal.
+    deprecateExtraOptions = true;
-      `size` can be a number or function
+    optionsRenamedToSettings = [
-      Example:
+      "size"
-      ```nix
+      "onCreate"
-      size = 20
+      "onOpen"
-      ```
+      "onClose"
-      OR
+      "onStdout"
-      ```
+      "onStderr"
-      size = function(term)
+      "onExit"
-        if term.direction == "horizontal" then
+      "hideNumbers"
-          return 15
+      "shadeFiletypes"
-        elseif term.direction == "vertical" then
+      "autochdir"
-          return vim.o.columns * 0.4
+      "highlights"
-        end
+      "shadeTerminals"
-      end
+      "shadingFactor"
-      ```
+      "startInInsert"
-    '';
+      "insertMappings"
-
+      "terminalMappings"
-    openMapping = helpers.mkNullOrOption types.str ''
+      "persistSize"
-      Setting the open_mapping key to use for toggling the terminal(s) will set up mappings for
+      "persistMode"
-      normal mode.
+      "direction"
-    '';
+      "closeOnExit"
-
+      "shell"
-    onCreate = helpers.defaultNullOpts.mkLuaFn "nil" ''
+      "autoScroll"
-      Function to run when the terminal is first created.
+      ["floatOpts" "border"]
-    '';
+      ["floatOpts" "width"]
-
+      ["floatOpts" "height"]
-    onOpen = helpers.defaultNullOpts.mkLuaFn "nil" ''
+      ["floatOpts" "winblend"]
-      Function to run when the terminal opens.
+      ["floatOpts" "zindex"]
-    '';
+      ["winbar" "enabled"]
-
+      ["winbar" "nameFormatter"]
-    onClose = helpers.defaultNullOpts.mkLuaFn "nil" ''
+    ];
-      Function to run when the terminal closes.
+    imports = [
-    '';
+      (
-
+        mkRemovedOptionModule
-    onStdout = helpers.defaultNullOpts.mkLuaFn "nil" ''
+        ["plugins" "toggleterm" "openMapping"]
-      Callback for processing output on stdout.
-    '';
-
-    onStderr = helpers.defaultNullOpts.mkLuaFn "nil" ''
-      Callback for processing output on stderr.
-    '';
-
-    onExit = helpers.defaultNullOpts.mkLuaFn "nil" ''
-      Function to run when terminal process exits.
-    '';
-
-    hideNumbers = helpers.defaultNullOpts.mkBool true ''
-      Hide the number column in toggleterm buffers.
-    '';
-
-    shadeFiletypes = helpers.defaultNullOpts.mkNullable (types.listOf types.str) "[]" "";
-
-    autochdir = helpers.defaultNullOpts.mkBool false ''
-      When neovim changes it current directory the terminal will change it's own when next it's
-      opened.
-    '';
-
-    highlights = helpers.mkNullOrOption (with types; (attrsOf (attrsOf str))) ''
-      Highlights which map to a highlight group name and a table of it's values.
-
-      Example:
-      ```nix
-        highlights = {
-          Normal = {
-            guibg = "<VALUE-HERE>";
-          };
-          NormalFloat = {
-            link = "Normal";
-          },
-          FloatBorder = {
-            guifg = "<VALUE-HERE>";
-            guibg = "<VALUE-HERE>";
-          };
-        };
-      ```
-    '';
-
-    shadeTerminals = helpers.defaultNullOpts.mkBool false ''
-      NOTE: This option takes priority over highlights specified so if you specify Normal highlights
-      you should set this to false.
-    '';
-
-    shadingFactor = helpers.defaultNullOpts.mkInt (-30) ''
-      The percentage by which to lighten terminal background.
-
-      Default: -30 (gets multiplied by -3 if background is light).
-    '';
-
-    startInInsert = helpers.defaultNullOpts.mkBool true "";
-
-    insertMappings = helpers.defaultNullOpts.mkBool true ''
-      Whether or not the open mapping applies in insert mode.
-    '';
-
-    terminalMappings = helpers.defaultNullOpts.mkBool true ''
-      Whether or not the open mapping applies in the opened terminals.
-    '';
-
-    persistSize = helpers.defaultNullOpts.mkBool true "";
-
-    persistMode = helpers.defaultNullOpts.mkBool true ''
-      If set to true (default) the previous terminal mode will be remembered.
-    '';
-
-    direction =
-      helpers.defaultNullOpts.mkEnumFirstDefault
-      ["vertical" "horizontal" "tab" "float"]
-      "";
-
-    closeOnExit = helpers.defaultNullOpts.mkBool true ''
-      Close the terminal window when the process exits.
-    '';
-
-    shell = helpers.defaultNullOpts.mkStr "`vim.o.shell`" ''
-      Change the default shell.
-    '';
-
-    autoScroll = helpers.defaultNullOpts.mkBool true ''
-      Automatically scroll to the bottom on terminal output.
-    '';
-
-    floatOpts = {
-      border =
-        helpers.defaultNullOpts.mkBorder "single" "toggleterm"
         ''
-          `border` = 'single' | 'double' | 'shadow' | 'curved' | ... other options supported by
+          Please use `plugins.toggleterm.settings.open_mapping` instead but beware, you have to provide the value in this form: `"[[<c-\>]]"`.
+        ''
+      )
+    ];
+
+    settingsOptions = {
+      size = helpers.defaultNullOpts.mkStrLuaFnOr types.number "12" ''
+        Size of the terminal.
+        `size` can be a number or a function.
+
+        Example:
+        ```nix
+          size = 20
+        ```
+        OR
+
+        ```nix
+        size = \'\'
+          function(term)
+            if term.direction == "horizontal" then
+              return 15
+            elseif term.direction == "vertical" then
+              return vim.o.columns * 0.4
+            end
+          end
+        \'\';
+        ```
+      '';
+
+      open_mapping = helpers.mkNullOrLua ''
+        Setting the `open_mapping` key to use for toggling the terminal(s) will set up mappings for
+        normal mode.
+      '';
+
+      on_create = helpers.mkNullOrLuaFn ''
+        Function to run when the terminal is first created.
+
+        `fun(t: Terminal)`
+      '';
+
+      on_open = helpers.mkNullOrLuaFn ''
+        Function to run when the terminal opens.
+
+        `fun(t: Terminal)`
+      '';
+
+      on_close = helpers.mkNullOrLuaFn ''
+        Function to run when the terminal closes.
+
+        `fun(t: Terminal)`
+      '';
+
+      on_stdout = helpers.mkNullOrLuaFn ''
+        Callback for processing output on stdout.
+
+        `fun(t: Terminal, job: number, data: string[], name: string)`
+      '';
+
+      on_stderr = helpers.mkNullOrLuaFn ''
+        Callback for processing output on stderr.
+
+        `fun(t: Terminal, job: number, data: string[], name: string)`
+      '';
+
+      on_exit = helpers.mkNullOrLuaFn ''
+        Function to run when terminal process exits.
+
+        `fun(t: Terminal, job: number, exit_code: number, name: string)`
+      '';
+
+      hide_numbers = helpers.defaultNullOpts.mkBool true ''
+        Hide the number column in toggleterm buffers.
+      '';
+
+      shade_filetypes = helpers.defaultNullOpts.mkListOf types.str "[]" ''
+        Shade filetypes.
+      '';
+
+      autochdir = helpers.defaultNullOpts.mkBool false ''
+        When neovim changes it current directory the terminal will change it's own when next it's
+        opened.
+      '';
+
+      highlights =
+        helpers.defaultNullOpts.mkAttrsOf helpers.nixvimTypes.highlight
+        ''
+          {
+            NormalFloat.link = "Normal";
+            FloatBorder.link = "Normal";
+            StatusLine.gui = "NONE";
+            StatusLineNC = {
+              cterm = "italic";
+              gui = "NONE";
+            };
+          }
+        ''
+        "Highlights which map a highlight group name to an attrs of it's values.";
+
+      shade_terminals = helpers.defaultNullOpts.mkBool true ''
+        NOTE: This option takes priority over highlights specified so if you specify Normal
+        highlights you should set this to `false`.
+      '';
+
+      shading_factor = helpers.mkNullOrOption types.int ''
+        The percentage by which to lighten terminal background.
+
+        default: -30 (gets multiplied by -3 if background is light).
+      '';
+
+      start_in_insert = helpers.defaultNullOpts.mkBool true ''
+        Whether to start toggleterm in insert mode.
+      '';
+
+      insert_mappings = helpers.defaultNullOpts.mkBool true ''
+        Whether or not the open mapping applies in insert mode.
+      '';
+
+      terminal_mappings = helpers.defaultNullOpts.mkBool true ''
+        Whether or not the open mapping applies in the opened terminals.
+      '';
+
+      persist_size = helpers.defaultNullOpts.mkBool true ''
+        Whether the terminal size should persist.
+      '';
+
+      persist_mode = helpers.defaultNullOpts.mkBool true ''
+        If set to true (default) the previous terminal mode will be remembered.
+      '';
+
+      direction =
+        helpers.defaultNullOpts.mkEnum
+        ["vertical" "horizontal" "tab" "float"] "horizontal"
+        "The direction the terminal should be opened in.";
+
+      close_on_exit = helpers.defaultNullOpts.mkBool true ''
+        Close the terminal window when the process exits.
+      '';
+
+      shell = helpers.defaultNullOpts.mkStr ''{__raw = "vim.o.shell";}'' ''
+        Change the default shell.
+      '';
+
+      auto_scroll = helpers.defaultNullOpts.mkBool true ''
+        Automatically scroll to the bottom on terminal output.
+      '';
+
+      float_opts = {
+        border = helpers.mkNullOrOption helpers.nixvimTypes.border ''
+          `border` = "single" | "double" | "shadow" | "curved" | ... other options supported by
           `win open`.
           The border key is *almost* the same as 'nvim_open_win'.
           The 'curved' border is a custom border type not natively supported but implemented in this plugin.
         '';
 
-      width = helpers.defaultNullOpts.mkInt 50 "";
+        width = helpers.mkNullOrOption types.ints.unsigned "";
 
-      height = helpers.defaultNullOpts.mkInt 50 "";
+        height = helpers.mkNullOrOption types.ints.unsigned "";
 
-      winblend = helpers.defaultNullOpts.mkInt 3 "";
+        row = helpers.mkNullOrOption types.ints.unsigned "";
 
-      zindex = helpers.defaultNullOpts.mkInt 50 "";
+        col = helpers.mkNullOrOption types.ints.unsigned "";
-    };
-    winbar = {
-      enabled = helpers.defaultNullOpts.mkBool false "";
 
-      nameFormatter =
+        winblend = helpers.defaultNullOpts.mkUnsignedInt 0 "";
-        helpers.defaultNullOpts.mkLuaFn
+
-        ''
+        zindex = helpers.mkNullOrOption types.ints.unsigned "";
-          function(term)
+
-            return term.name
+        title_pos = helpers.defaultNullOpts.mkStr "left" "";
-          end
+      };
-        '' "";
+
-    };
+      winbar = {
-  };
+        enabled = helpers.defaultNullOpts.mkBool false ''
-  config = let
+          Whether to enable winbar.
-    setupOptions = with cfg; {
+        '';
-      inherit autochdir highlights direction shell size;
+
-      open_mapping = helpers.ifNonNull' openMapping (helpers.mkRaw "[[${openMapping}]]");
+        name_formatter =
-      on_create = onCreate;
+          helpers.defaultNullOpts.mkLuaFn
-      on_open = onOpen;
+          ''
-      on_close = onClose;
+            function(term)
-      on_stdout = onStdout;
+              return term.name
-      on_stderr = onStderr;
+            end
-      on_exit = onExit;
+          ''
-      hide_numbers = hideNumbers;
+          ''
-      shade_filetypes = shadeFiletypes;
+            `func(term: Terminal):string`
-      shade_terminals = shadeTerminals;
+
-      shading_factor = shadingFactor;
+            Example:
-      start_in_insert = startInInsert;
+            ```lua
-      insert_mappings = insertMappings;
+              function(term)
-      terminal_mappings = terminalMappings;
+                return fmt("%d:%s", term.id, term:_display_name())
-      persist_size = persistSize;
+              end
-      persist_mode = persistMode;
+            ```
-      close_on_exit = closeOnExit;
+          '';
-      auto_scroll = autoScroll;
-      float_opts = floatOpts;
-      winbar = with winbar; {
-        inherit enabled;
-        name_formatter = nameFormatter;
       };
     };
-  in
+
-    mkIf cfg.enable {
+    settingsExample = {
-      extraPlugins = [cfg.package];
+      open_mapping = "[[<c-\>]]";
-      extraConfigLua = ''
+      direction = "float";
-        require("toggleterm").setup(${helpers.toLuaObject setupOptions})
+      float_opts = {
-      '';
+        border = "curved";
+        width = 130;
+        height = 30;
+      };
     };
-}
+  }

tests/test-sources/plugins/utils/toggleterm.nix

@@ -3,57 +3,134 @@
     plugins.toggleterm.enable = true;
   };
 
-  test = {
+  simple-example = {
     plugins.toggleterm = {
       enable = true;
 
-      size = ''
+      settings = {
-        function(term)
+        open_mapping = "[[<c-\>]]";
-          if term.direction == "horizontal" then
+        direction = "float";
-            return 15
+        float_opts = {
-          elseif term.direction == "vertical" then
+          border = "curved";
-            return vim.o.columns * 0.4
+          width = 130;
-          end
+          height = 30;
-        end
+        };
-      '';
-      openMapping = "<c-\\>";
-      onCreate = "function() end";
-      onOpen = "function() end";
-      onClose = "function() end";
-      onStdout = "function() end";
-      onStderr = "function() end";
-      onExit = "function() end";
-      hideNumbers = false;
-      shadeFiletypes = [""];
-      autochdir = true;
-      highlights = {
-        Normal.guibg = "#000000";
-        NormalFloat.link = "#FFFFFF";
       };
-      shadeTerminals = true;
+    };
-      shadingFactor = -40;
+  };
-      startInInsert = false;
+
-      insertMappings = false;
+  example = {
-      terminalMappings = true;
+    plugins.toggleterm = {
-      persistSize = false;
+      enable = true;
-      direction = "tab";
+
-      closeOnExit = false;
+      settings = {
-      shell = "bash";
+        size = ''
-      autoScroll = false;
-      floatOpts = {
-        border = "double";
-        width = 30;
-        height = 30;
-        winblend = 5;
-        zindex = 20;
-      };
-      winbar = {
-        enabled = true;
-        nameFormatter = ''
           function(term)
-            return term.name + "Test"
+            if term.direction == "horizontal" then
+              return 15
+            elseif term.direction == "vertical" then
+              return vim.o.columns * 0.4
+            end
           end
         '';
+        open_mapping = "[[<c-\>]]";
+        on_create = "function() end";
+        on_open = "function() end";
+        on_close = "function() end";
+        on_stdout = "function() end";
+        on_stderr = "function() end";
+        on_exit = "function() end";
+        hide_numbers = false;
+        shade_filetypes = [""];
+        autochdir = true;
+        highlights = {
+          Normal.guibg = "#000000";
+          NormalFloat.link = "#FFFFFF";
+        };
+        shade_terminals = true;
+        shading_factor = -40;
+        start_in_insert = false;
+        insert_mappings = false;
+        terminal_mappings = true;
+        persist_size = false;
+        persist_mode = false;
+        direction = "tab";
+        close_on_exit = false;
+        shell = "bash";
+        auto_scroll = false;
+        float_opts = {
+          border = "double";
+          width = 30;
+          height = 30;
+          winblend = 5;
+          zindex = 20;
+        };
+        winbar = {
+          enabled = true;
+          name_formatter = ''
+            function(term)
+              return term.name + "Test"
+            end
+          '';
+        };
+      };
+    };
+  };
+
+  defaults = {
+    plugins.toggleterm = {
+      enable = true;
+
+      settings = {
+        size = 12;
+        open_mapping = null;
+        on_create = null;
+        on_open = null;
+        on_close = null;
+        on_stdout = null;
+        on_stderr = null;
+        on_exit = null;
+        hide_numbers = true;
+        shade_filetypes = [];
+        autochdir = false;
+        highlights = {
+          NormalFloat.link = "Normal";
+          FloatBorder.link = "Normal";
+          StatusLine.gui = "NONE";
+          StatusLineNC = {
+            cterm = "italic";
+            gui = "NONE";
+          };
+        };
+        shade_terminals = true;
+        shading_factor = -30;
+        start_in_insert = true;
+        insert_mappings = true;
+        terminal_mappings = true;
+        persist_size = true;
+        persist_mode = true;
+        direction = "horizontal";
+        close_on_exit = true;
+        shell.__raw = "vim.o.shell";
+        auto_scroll = true;
+        float_opts = {
+          border = null;
+          width = null;
+          height = null;
+          row = null;
+          col = null;
+          winblend = 0;
+          zindex = null;
+          title_pos = "left";
+        };
+        winbar = {
+          enabled = false;
+          name_formatter = ''
+            function(term)
+              return term.name
+            end
+          '';
+        };
       };
     };
   };