feat!: Make the window picker function configurable. (#11)

sindrets · web-flow · commit 2a8e50d02fc4 · 2022-06-22T14:47:19.000+02:00
BREAKING CHANGE:

The configuration for the window picker has changed as a result of the
function now being fully configurable. If you have previously configured
the window picker, see `:h winshift.changelog-11` for more information
about how to update your config.
diff --git a/README.md b/README.md
@@ -70,24 +70,31 @@ require("winshift").setup({
       ["<S-right>"] = "far_right",
     },
   },
-  -- The window picker is used to select a window while swapping windows with
-  -- ':WinShift swap'.
-  -- A string of chars used as identifiers by the window picker.
-  window_picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
-  window_picker_ignore = {
-    -- This table allows you to indicate to the window picker that a window
-    -- should be ignored if its buffer matches any of the following criteria.
-    filetype = {  -- List of ignored file types
-      "NvimTree",
-    },
-    buftype = {   -- List of ignored buftypes
-      "terminal",
-      "quickfix",
-    },
-    bufname = {   -- List of regex patterns matching ignored buffer names
-      [[.*foo/bar/baz\.qux]]
-    },
-  },
+  ---A function that should prompt the user to select a window.
+  ---
+  ---The window picker is used to select a window while swapping windows with
+  ---`:WinShift swap`.
+  ---@return integer? winid # Either the selected window ID, or `nil` to
+  ---   indicate that the user cancelled / gave an invalid selection.
+  window_picker = function()
+    return require("winshift.lib").pick_window({
+      -- A string of chars used as identifiers by the window picker.
+      picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
+      filter_rules = {
+        -- This table allows you to indicate to the window picker that a window
+        -- should be ignored if its buffer matches any of the following criteria.
+        cur_win = true, -- Filter out the current window
+        floats = true,  -- Filter out floating windows
+        filetype = {},  -- List of ignored file types
+        buftype = {},   -- List of ignored buftypes
+        bufname = {},   -- List of vim regex patterns matching ignored buffer names
+      },
+      ---A function used to filter the list of selectable windows.
+      ---@param winids integer[] # The list of selectable window IDs.
+      ---@return integer[] filtered # The filtered list of window IDs.
+      filter_func = nil,
+    })
+  end,
 })
 ```
 
diff --git a/doc/winshift.txt b/doc/winshift.txt
@@ -1,25 +1,25 @@
-*winshift.nvim*  WinShift.nvim
+*winshift.txt*  WinShift.nvim
 
 Rearrange your windows with ease.
 
 Author: Sindre T. Strøm
 
 ==============================================================================
 
-INTRODUCTION                                           *winshift-introduction*
+INTRODUCTION                                    *winshift.nvim* *winshift*
 
 WinShift lets you move windows, not only around each other, but also in and
 out of rows and columns.
 
-USAGE                                         *Win-Move-mode* *winshift-usage*
+USAGE                                           *Win-Move-mode* *winshift-usage*
 
 Enter Win-Move mode by calling `:WinShift`. This will target your current
 window for moving. You can move the window either by using |hjkl| or the arrow
 keys. You can move the window to any of the far ends of the viewport by
 pressing one of `HJKL`, or shift + any arrow key. Exit Win-Move mode by
 pressing `q` / `<esc>` / `<C-c>`.
 
-CONFIGURATION                                                *winshift-config*
+CONFIGURATION                                   *winshift-config*
 
 Example configuration with default settings:
 >
@@ -56,12 +56,37 @@ Example configuration with default settings:
           ["<S-right>"] = "far_right",
         },
       },
+      ---A function that should prompt the user to select a window.
+      ---
+      ---The window picker is used to select a window while swapping windows with
+      ---`:WinShift swap`.
+      ---@return integer? winid # Either the selected window ID, or `nil` to
+      ---   indicate that the user cancelled / gave an invalid selection.
+      window_picker = function()
+        return require("winshift.lib").pick_window({
+          -- A string of chars used as identifiers by the window picker.
+          picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
+          filter_rules = {
+            -- This table allows you to indicate to the window picker that a window
+            -- should be ignored if its buffer matches any of the following criteria.
+            cur_win = true, -- Filter out the current window
+            floats = true,  -- Filter out floating windows
+            filetype = {},  -- List of ignored file types
+            buftype = {},   -- List of ignored buftypes
+            bufname = {},   -- List of vim regex patterns matching ignored buffer names
+          },
+          ---A function used to filter the list of selectable windows.
+          ---@param winids integer[] # The list of selectable window IDs.
+          ---@return integer[] filtered # The filtered list of window IDs.
+          filter_func = nil,
+        })
+      end,
     })
 <
 
-COMMANDS                                                   *winshift-commands*
+COMMANDS                                        *winshift-commands*
 
-                                                                   *:WinShift*
+                                                *:WinShift*
 :WinShift [direction]
                         When called without [direction]: starts Win-Move mode
                         targeting the current window for moving. For how to
@@ -82,7 +107,7 @@ COMMANDS                                                   *winshift-commands*
                         pressing the character displayed in the statusline of
                         the target window. The input is case-insensitive.
 
-CAVEATS                                                     *winshift-caveats*
+CAVEATS                                         *winshift-caveats*
 
 Moving through windows with 'winfixwidth' and / or 'winfixheight' can be a bit
 wonky. It will work, but it can be a bit hard to follow the movement, and the
diff --git a/doc/winshift_changelog.txt b/doc/winshift_changelog.txt
@@ -0,0 +1,63 @@
+================================================================================
+                                                *winshift.changelog*
+
+CHANGELOG
+
+                                                *winshift.changelog-11*
+
+PR: https://github.com/sindrets/winshift.nvim/pull/11
+
+The configuration for the window picker has changed as a result of the
+function now being fully configurable. If you have previously configured
+options for the window picker, move them into the options passed to the
+`pick_window` function:
+
+        Before: ~
+>
+                require("winshift").setup({
+                  -- ...
+                  window_picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
+                  window_picker_ignore = {
+                    filetype = {
+                      "NvimTree",
+                    },
+                    buftype = {
+                      "terminal",
+                      "quickfix",
+                    },
+                    bufname = {
+                      [[.*foo/bar/baz\.qux]]
+                    },
+                  },
+                })
+<
+        After: ~
+>
+                require("winshift").setup({
+                  -- ...
+                  window_picker = function()
+                    return require("winshift.lib").pick_window({
+                      picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
+                      filter_rules = {
+                        cur_win = true,
+                        floats = true,
+                        filetype = {
+                          "NvimTree",
+                        },
+                        buftype = {
+                          "terminal",
+                          "quickfix",
+                        },
+                        bufname = {
+                          [[.*foo/bar/baz\.qux]]
+                        },
+                      },
+                    })
+                  end,
+                })
+<
+
+See |winshift-config| more information about how to configure the window
+picker.
+
+ vim:tw=78:ts=8:ft=help:norl:
diff --git a/lua/winshift/config.lua b/lua/winshift/config.lua
@@ -32,12 +32,28 @@ M.defaults = {
       ["<S-right>"] = "far_right",
     },
   },
-  window_picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
-  window_picker_ignore = {
-    filetype = {},
-    buftype = {},
-    bufname = {},
-  },
+  ---A function that should prompt the user to select a window.
+  ---
+  ---The window picker is used to select a window while swapping windows with
+  ---`:WinShift swap`.
+  ---@return integer? winid # Either the selected window ID, or `nil` to
+  ---   indicate that the user cancelled / gave an invalid selection.
+  window_picker = function()
+    return require("winshift.lib").pick_window({
+      picker_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
+      filter_rules = {
+        cur_win = true,
+        floats = true,
+        filetype = {},
+        buftype = {},
+        bufname = {},
+      },
+      ---A function used to filter the list of selectable windows.
+      ---@param winids integer[] # The list of selectable window IDs.
+      ---@return integer[] filtered # The filtered list of window IDs.
+      filter_func = nil,
+    })
+  end,
 }
 -- stylua: ignore end
 
@@ -65,6 +81,17 @@ function M.setup(user_config)
 
   M._config.moving_win_options = user_config.moving_win_options or M._config.moving_win_options
 
+  --#region DEPRECATION NOTICES
+
+  if M._config.window_picker_chars or M._config.window_picker_ignore then
+    utils.warn(table.concat({
+      "'window_picker_chars' and 'window_picker_ignore' has been deprecated!",
+      " See ':h winshift.changelog-11' for more information.",
+    }, ""))
+  end
+
+  --#endregion
+
   if M._config.keymaps.disable_defaults then
     for name, _ in pairs(M._config.keymaps) do
       if name ~= "disable_defaults" then
diff --git a/lua/winshift/lib.lua b/lua/winshift/lib.lua
@@ -277,47 +277,66 @@ function M.next_node_vertical(leaf, dir)
   end
 end
 
+---@class WindowPickerFilterRules
+---@field cur_win boolean
+---@field floats boolean
+---@field filetype string[]
+---@field buftype string[]
+---@field bufname string[]
+
+---@class WindowPickerSpec
+---@field picker_chars string
+---@field filter_rules WindowPickerFilterRules
+---@field filter_func fun(winids: integer[]): integer[]
+
 ---Get user to pick a window. Selectable windows are all windows in the current
 ---tabpage.
----@param ignore table<integer, boolean>
+---@param opt? WindowPickerSpec
 ---@return integer|nil -- If a valid window was picked, return its id. If an
 ---       invalid window was picked / user canceled, return nil. If there are
 ---       no selectable windows, return -1.
-function M.pick_window(ignore)
+function M.pick_window(opt)
+  opt = opt or {}
   local tabpage = api.nvim_get_current_tabpage()
   local win_ids = api.nvim_tabpage_list_wins(tabpage)
-  local exclude = config.get_config().window_picker_ignore
+  local curwin = api.nvim_get_current_win()
+  local filter_rules = opt.filter_rules or {}
 
   local selectable = vim.tbl_filter(function (id)
-    local bufid = api.nvim_win_get_buf(id)
-    local bufname = api.nvim_buf_get_name(bufid)
-
-    if ignore[id] then
+    if filter_rules.cur_win and curwin == id then
+      return false
+    elseif filter_rules.floats and api.nvim_win_get_config(id).relative ~= "" then
       return false
     end
 
+    local bufid = api.nvim_win_get_buf(id)
+    local bufname = api.nvim_buf_get_name(bufid)
+
     for _, option in ipairs({ "filetype", "buftype" }) do
-      if vim.tbl_contains(exclude[option], vim.bo[bufid][option]) then
+      if vim.tbl_contains(filter_rules[option] or {}, vim.bo[bufid][option]) then
         return false
       end
     end
 
-    for _, pattern in ipairs(exclude.bufname) do
+    for _, pattern in ipairs(filter_rules.bufname or {}) do
       local regex = vim.regex(pattern)
       if regex:match_str(bufname) ~= nil then
         return false
       end
     end
 
-    local win_config = api.nvim_win_get_config(id)
-    return win_config.focusable and not win_config.external
+    return true
   end, win_ids)
 
+  if opt.filter_func then
+    selectable = opt.filter_func(selectable)
+  end
+
   -- If there are no selectable windows: return. If there's only 1, return it without picking.
   if #selectable == 0 then return -1 end
   if #selectable == 1 then return selectable[1] end
 
-  local chars = config.get_config().window_picker_chars:upper()
+  local chars = (opt.picker_chars or "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"):upper()
   local i = 1
   local win_opts = {}
   local win_map = {}
@@ -360,8 +379,8 @@ function M.pick_window(ignore)
 
   -- Restore window options
   for _, id in ipairs(selectable) do
-    for opt, value in pairs(win_opts[id]) do
-      api.nvim_win_set_option(id, opt, value)
+    for option, value in pairs(win_opts[id]) do
+      api.nvim_win_set_option(id, option, value)
     end
   end
 
@@ -568,7 +587,7 @@ function M.start_swap_mode()
   vim.cmd("redraw")
 
   local ok, err = pcall(function()
-    local target = M.pick_window({ [cur_win] = true })
+    local target = conf.window_picker()
 
     if target == -1 or target == nil then
       return
