plugins/auto-save: switch to mkNeovimPlugin

plugins/utils/auto-save.nix

@@ -6,30 +6,62 @@
   ...
 }:
 with lib;
-let
+helpers.neovim-plugin.mkNeovimPlugin config {
-  cfg = config.plugins.auto-save;
+  name = "auto-save";
-in
+  originalName = "auto-save.nvim";
-{
+  defaultPackage = pkgs.vimPlugins.auto-save-nvim;
-  options.plugins.auto-save = helpers.neovim-plugin.extraOptionsOptions // {
-    enable = mkEnableOption "auto-save";
 
-    package = helpers.mkPluginPackageOption "auto-save" pkgs.vimPlugins.auto-save-nvim;
+  maintainers = [ helpers.maintainers.braindefender ];
 
-    keymaps = {
+  # TODO: introduced 2024-06-21, remove after 24.11
-      silent = mkOption {
+  deprecateExtraOptions = true;
-        type = types.bool;
+  optionsRenamedToSettings = [
-        description = "Whether auto-save keymaps should be silent.";
+    [
-        default = false;
+      "executionMessage"
-      };
+      "message"
+    ]
+    [
+      "executionMessage"
+      "dim"
+    ]
+    [
+      "executionMessage"
+      "cleaningInterval"
+    ]
+    "triggerEvents"
+    "writeAllBuffers"
+    "debounceDelay"
+  ];
 
-      toggle = helpers.mkNullOrOption types.str "Keymap for running auto-save.";
+  imports =
-    };
+    let
+      basePluginPath = [
+        "plugins"
+        "auto-save"
+      ];
+      settingsPath = basePluginPath ++ [ "settings" ];
+    in
+    [
+      (mkRenamedOptionModule (basePluginPath ++ [ "enableAutoSave" ]) (settingsPath ++ [ "enabled" ]))
+      (mkRemovedOptionModule (basePluginPath ++ [ "keymaps" ]) ''
+        Use the top-level `keymaps` option to create a keymap that runs :ASToggle
 
-    enableAutoSave = helpers.defaultNullOpts.mkBool true ''
+        keymaps = [
+          { key = "<leader>s"; action = "<cmd>ASToggle<CR>"; }
+        ];
+      '')
+    ];
+
+  settingsOptions = {
+    enabled = helpers.defaultNullOpts.mkBool true ''
       Whether to start auto-save when the plugin is loaded.
     '';
 
-    executionMessage = {
+    execution_message = {
+      enabled = helpers.defaultNullOpts.mkBool true ''
+        Show execution message after successful auto-save.
+      '';
+
       message =
         helpers.defaultNullOpts.mkStr
           {
@@ -40,7 +72,7 @@ in
             '';
           }
           ''
-            The message to print en save.
+            The message to print on save.
             This can be a lua function that returns a string.
           '';
 
@@ -48,97 +80,101 @@ in
         1
       ) 0.18 "Dim the color of `message`.";
 
-      cleaningInterval = helpers.defaultNullOpts.mkInt 1250 ''
+      cleaning_interval = helpers.defaultNullOpts.mkUnsignedInt 1250 ''
         Time (in milliseconds) to wait before automatically cleaning MsgArea after displaying
         `message`.
         See `:h MsgArea`.
       '';
     };
 
-    triggerEvents =
+    trigger_events = {
-      helpers.defaultNullOpts.mkListOf types.str
+      immediate_save =
-        [
+        helpers.defaultNullOpts.mkListOf types.str
-          "InsertLeave"
+          [
-          "TextChanged"
+            "BufLeave"
-        ]
+            "FocusLost"
-        ''
+          ]
-          Vim events that trigger auto-save.
+          ''
-          See `:h events`.
+            Vim events that trigger an immediate save.\
-        '';
+            See `:h events` for events description.
+          '';
 
-    condition =
+      defer_save =
-      helpers.defaultNullOpts.mkLuaFn
+        helpers.defaultNullOpts.mkListOf types.str
-        ''
+          [
-          function(buf)
+            "InsertLeave"
-            local fn = vim.fn
+            "TextChanged"
-            local utils = require("auto-save.utils.data")
+          ]
+          ''
+            Vim events that trigger a deferred save (saves after `debounceDelay`).\
+            See `:h events` for events description.
+          '';
 
-            if
+      cancel_defered_save = helpers.defaultNullOpts.mkListOf types.str [ "InsertEnter" ] ''
-              fn.getbufvar(buf, "&modifiable") == 1 and utils.not_in(fn.getbufvar(buf, "&filetype"), {}) then
+        Vim events that cancel a pending deferred save.\
-              return true -- met condition(s), can save
+        See `:h events` for events description.
-            end
+      '';
-            return false -- can't save
+    };
+
+    condition = helpers.defaultNullOpts.mkLuaFn' {
+      pluginDefault = null;
+      description = ''
+        Function that determines whether to save the current buffer or not.
+        - return true: if buffer is ok to be saved
+        - return false: if it's not ok to be saved
+
+        In this example, the second argument of `utils.not_in(..., {})`
+        determines which filetypes will be ignored by auto-save plugin.
+
+        Buffers that are `nomodifiable` are not saved by default.
+      '';
+      example = ''
+        function(buf)
+          local fn = vim.fn
+          local utils = require("auto-save.utils.data")
+
+          if utils.not_in(fn.getbufvar(buf, "&filetype"), {}) then
+            return true
           end
-        ''
+          return false
-        ''
+        end
-          Function that determines whether to save the current buffer or not.
+      '';
-          - return true: if buffer is ok to be saved
+    };
-          - return false: if it's not ok to be saved
-        '';
 
-    writeAllBuffers = helpers.defaultNullOpts.mkBool false ''
+    write_all_buffers = helpers.defaultNullOpts.mkBool false ''
       Write all buffers when the current one meets `condition`.
     '';
 
-    debounceDelay = helpers.defaultNullOpts.mkInt 135 ''
+    noautocmd = helpers.defaultNullOpts.mkBool false ''
+      Do not execute autocmds when saving.
+    '';
+
+    lockmarks = helpers.defaultNullOpts.mkBool false ''
+      Lock marks when saving, see `:h lockmarks` for more details.
+    '';
+
+    debounce_delay = helpers.defaultNullOpts.mkUnsignedInt 1000 ''
       Saves the file at most every `debounce_delay` milliseconds.
     '';
 
-    callbacks =
+    debug = helpers.defaultNullOpts.mkBool false ''
-      mapAttrs (name: desc: helpers.mkNullOrLuaFn "The code of the function that runs ${desc}.")
+      Log debug messages to `auto-save.log` file in NeoVim cache directory.
-        {
+    '';
-          enabling = "when enabling auto-save";
-          disabling = "when disabling auto-save";
-          beforeAssertingSave = "before checking `condition`";
-          beforeSaving = "before doing the actual save";
-          afterSaving = "after doing the actual save";
-        };
   };
 
-  config =
+  settingsExample = {
-    let
+    condition = ''
-      options = {
+      function(buf)
-        enabled = cfg.enableAutoSave;
+        local fn = vim.fn
-        execution_message = with cfg.executionMessage; {
+        local utils = require("auto-save.utils.data")
-          inherit message dim;
-          cleaning_interval = cleaningInterval;
-        };
-        trigger_events = cfg.triggerEvents;
-        inherit (cfg) condition;
-        write_all_buffers = cfg.writeAllBuffers;
-        debounce_delay = cfg.debounceDelay;
-        callbacks = with cfg.callbacks; {
-          inherit enabling disabling;
-          before_asserting_save = beforeAssertingSave;
-          before_saving = beforeSaving;
-          after_saving = afterSaving;
-        };
-      } // cfg.extraOptions;
-    in
-    mkIf cfg.enable {
-      extraPlugins = [ cfg.package ];
 
-      extraConfigLua = ''
+        if utils.not_in(fn.getbufvar(buf, "&filetype"), {'oil'}) then
-        require('auto-save').setup(${helpers.toLuaObject options})
+          return true
-      '';
+        end
-
+        return false
-      keymaps =
+      end
-        with cfg.keymaps;
+    '';
-        optional (toggle != null) {
+    write_all_buffers = true;
-          mode = "n";
+    debounce_delay = 1000;
-          key = toggle;
+  };
-          action = ":ASToggle<CR>";
-          options.silent = cfg.keymaps.silent;
-        };
-    };
 }

tests/test-sources/plugins/utils/auto-save.nix

@@ -3,47 +3,61 @@
     plugins.auto-save.enable = true;
   };
 
+  example = {
+    plugins.auto-save = {
+      enable = true;
+
+      settings = {
+        condition = ''
+          function(buf)
+            local fn = vim.fn
+            local utils = require("auto-save.utils.data")
+
+            if utils.not_in(fn.getbufvar(buf, "&filetype"), {'oil'}) then
+              return true
+            end
+            return false
+          end
+        '';
+        write_all_buffers = true;
+        debounce_delay = 1000;
+      };
+    };
+  };
+
   defaults = {
     plugins.auto-save = {
       enable = true;
 
-      keymaps = {
+      settings = {
-        silent = true;
+        enabled = true;
-        toggle = "<leader>s";
+        execution_message = {
-      };
+          enabled = true;
-      enableAutoSave = true;
+          dim = 0.18;
-      executionMessage = {
+          cleaning_interval = 1250;
-        message.__raw = ''
+          message.__raw = ''
-          function()
+            function()
-            return ("AutoSave: saved at " .. vim.fn.strftime("%H:%M:%S"))
+              return ("AutoSave: saved at " .. vim.fn.strftime("%H:%M:%S"))
-          end
+            end
-        '';
+          '';
-        dim = 0.18;
+        };
-        cleaningInterval = 1250;
+        trigger_events = {
-      };
+          immediate_save = [
-      triggerEvents = [
+            "BufLeave"
-        "InsertLeave"
+            "FocusLost"
-        "TextChanged"
+          ];
-      ];
+          defer_save = [
-      condition = ''
+            "InsertLeave"
-        function(buf)
+            "TextChanged"
-          local fn = vim.fn
+          ];
-          local utils = require("auto-save.utils.data")
+          cancel_defered_save = [ "InsertEnter" ];
-
+        };
-          if fn.getbufvar(buf, "&modifiable") == 1 and utils.not_in(fn.getbufvar(buf, "&filetype"), {}) then
+        condition = null;
-            return true -- met condition(s), can save
+        write_all_buffers = false;
-          end
+        noautocmd = false;
-          return false -- can't save
+        lockmarks = false;
-        end
+        debounce_delay = 1000;
-      '';
+        debug = false;
-      writeAllBuffers = false;
-      debounceDelay = 135;
-      callbacks = {
-        enabling = null;
-        disabling = null;
-        beforeAssertingSave = null;
-        beforeSaving = null;
-        afterSaving = null;
       };
     };
   };

typos.toml

@@ -5,6 +5,7 @@ darcula = "darcula"       # base16-list
 Parm = "Parm"             # clangd-extensions
 Definitons = "Definitons" # TODO: ./plugins/languages/treesitter/treesitter-refactor.nix
 deffered = "deffered"     # TODO: ./plugins/utils/vim-matchup.nix
+defered = "defered"       # ./plugins/utils/auto-save.nix
 Highligt = "Highligt"     # TODO: ./plugins/utils/neogen.nix
 Annote = "Annote"         # TODO: ./plugins/lsp/fidget.nix
 ket = "ket"               # ./plugins/utils/sandwich.nix