feat: add skip_toggle option to ignore some opened terminals when toggling

README.md

@@ -127,7 +127,7 @@ I'm also going to be pretty conservative about what I add.
 This plugin must be explicitly enabled by using `require("toggleterm").setup{}`
 
 Setting the `open_mapping` key to use for toggling the terminal(s) will set up mappings for _normal_ mode.
-If you prefix the mapping with a number that particular terminal will be opened. Otherwise if a prefix is not set, then the last toggled terminal will be opened. In case there are multiple terminals opened they'll all be closed, and on the next mapping key they'll be restored.
+If you prefix the mapping with a number that particular terminal will be opened. Otherwise if a prefix is not set, then the last toggled terminal will be opened. Without a prefix and if the `skip_toggle(t: Terminal)` function is set, terminals with the function returning `true` will be skipped and the first one with `false` will be toggled. In case there are multiple terminals opened they'll all be closed, and on the next mapping key they'll be restored.
 
 If you set the `insert_mappings` key to `true`, the mapping will also take effect in insert mode; similarly setting `terminal_mappings` to `true` will have the mappings take effect in the opened terminal.
 
@@ -162,6 +162,7 @@ require("toggleterm").setup{
     end
   end,
   open_mapping = [[<c-\>]],
+  skip_toggle = function (t: Terminal) -> bool, -- function to filter terminals to avoid toggling unwanted one(s)
   on_create = fun(t: Terminal), -- function to run when the terminal is first created
   on_open = fun(t: Terminal), -- function to run when the terminal opens
   on_close = fun(t: Terminal), -- function to run when the terminal closes

doc/toggleterm.txt

@@ -105,8 +105,10 @@ Setting the `open_mapping` key to use for toggling the terminal(s) will set up
 mappings for _normal_ mode. If you prefix the mapping with a number that
 particular terminal will be opened. Otherwise if a prefix is not set, then the
 last toggled terminal will be opened. In case there are multiple terminals
-opened they’ll all be closed, and on the next mapping key they’ll be
-restored.
+opened they’ll all be closed, and on the next mapping key they’ll be restored.
+Without a prefix and if the `skip_toggle(t: Terminal)` function is set,
+terminals with the function returning `true` will be skipped and the first one
+with `false` will be toggled.
 
 If you set the `insert_mappings` key to `true`, the mapping will also take
 effect in insert mode; similarly setting `terminal_mappings` to `true` will
@@ -148,6 +150,7 @@ what options are available. It is not written to be used as is.
         end
       end,
       open_mapping = [[<c-\>]],
+      skip_toggle = function (t: Terminal) -> bool, -- function to filter terminals to avoid toggling unwanted ones
       on_create = fun(t: Terminal), -- function to run when the terminal is first created
       on_open = fun(t: Terminal), -- function to run when the terminal opens
       on_close = fun(t: Terminal), -- function to run when the terminal closes

lua/toggleterm/terminal.lua

@@ -107,11 +107,22 @@ local function next_id()
 end
 
 ---Get an opened (valid) toggle terminal by id, defaults to the first opened
+---one which does not satisfy the skip_toggle function
 ---@param position number?
 ---@return number?
 function M.get_toggled_id(position)
-  position = position or 1
+  if position then
+    specified = true
+  else
+    specified = false
+    position = 1
+  end
   local t = M.get_all()
+  if not specified and config.skip_toggle then
+    while t[position] and config.skip_toggle(t[position]) do
+        position = position + 1
+    end
+  end
   return t[position] and t[position].id or nil
 end