feat: add name param to ToggleTerm and TermExec (#479)

README.md

@@ -225,10 +225,10 @@ require("toggleterm").setup{
 
 This is the command the mappings call under the hood. You can use it directly
 and prefix it with a count to target a specific terminal. This function also takes
-arguments `size`, `dir` and `direction`. e.g.
+arguments `size`, `dir`, `direction` and `name`. e.g.
 
 ```vim
-:ToggleTerm size=40 dir=~/Desktop direction=horizontal
+:ToggleTerm size=40 dir=~/Desktop direction=horizontal name=desktop
 ```
 
 If `dir` is specified on creation toggle term will open at the specified directory.
@@ -244,6 +244,9 @@ the height/width of all terminals in the same direction will be changed to `size
 If `direction` is specified, and the command opens a terminal,
 the terminal will be changed to the specified direction.
 
+If `name` is specified, the display name is set for the toggled terminal. This name will be visible
+when using `TermSelect` command to indicate the specific terminal.
+
 `size` and `direction` are ignored if the command closes a terminal.
 
 #### Caveats
@@ -268,7 +271,7 @@ The `cmd` and `dir` arguments can also expand the same special keywords as `:h e
 
 These special keywords can be escaped using the `\` character, if you want to print character as is.
 
-The `size` and `direction` arguments are like the `size` and `direction` arguments of `ToggleTerm`.
+The `size`, `direction` and `name` arguments are like the `size`, `direction` and `name` arguments of `ToggleTerm`.
 
 By default, focus is returned to the original window after executing the command
 (except for floating terminals). Use argument `go_back=0` to disable this behaviour.

lua/toggleterm.lua

@@ -55,12 +55,13 @@ end
 ---@param size number?
 ---@param dir string?
 ---@param direction string?
-local function smart_toggle(size, dir, direction)
+---@param name string?
+local function smart_toggle(size, dir, direction, name)
   local has_open, windows = ui.find_open_windows()
   if not has_open then
     if not ui.open_terminal_view(size, direction) then
       local term_id = terms.get_toggled_id()
-      terms.get_or_create_term(term_id, dir, direction):open(size, direction)
+      terms.get_or_create_term(term_id, dir, direction, name):open(size, direction)
     end
   else
     ui.close_and_save_terminal_view(windows)
@@ -71,8 +72,9 @@ end
 --- @param size number?
 --- @param dir string?
 --- @param direction string?
-local function toggle_nth_term(num, size, dir, direction)
+--- @param name string?
-  local term = terms.get_or_create_term(num, dir, direction)
+local function toggle_nth_term(num, size, dir, direction, name)
+  local term = terms.get_or_create_term(num, dir, direction, name)
   ui.update_origin_window(term.window)
   term:toggle(size, direction)
   -- Save the terminal in view if it was last closed terminal.
@@ -149,10 +151,20 @@ function M.exec_command(args, count)
     size = { parsed.size, "number", true },
     dir = { parsed.dir, "string", true },
     direction = { parsed.direction, "string", true },
+    name = { parsed.name, "string", true },
     go_back = { parsed.go_back, "boolean", true },
     open = { parsed.open, "boolean", true },
   })
-  M.exec(parsed.cmd, count, parsed.size, parsed.dir, parsed.direction, parsed.go_back, parsed.open)
+  M.exec(
+    parsed.cmd,
+    count,
+    parsed.size,
+    parsed.dir,
+    parsed.direction,
+    parsed.name,
+    parsed.go_back,
+    parsed.open
+  )
 end
 
 --- @param cmd string
@@ -160,21 +172,23 @@ end
 --- @param size number?
 --- @param dir string?
 --- @param direction string?
+--- @param name string?
 --- @param go_back boolean? whether or not to return to original window
 --- @param open boolean? whether or not to open terminal window
-function M.exec(cmd, num, size, dir, direction, go_back, open)
+function M.exec(cmd, num, size, dir, direction, name, go_back, open)
   vim.validate({
     cmd = { cmd, "string" },
     num = { num, "number", true },
     size = { size, "number", true },
     dir = { dir, "string", true },
     direction = { direction, "string", true },
+    name = { name, "string", true },
     go_back = { go_back, "boolean", true },
     open = { open, "boolean", true },
   })
   num = (num and num >= 1) and num or terms.get_toggled_id()
   open = open == nil or open
-  local term = terms.get_or_create_term(num, dir, direction)
+  local term = terms.get_or_create_term(num, dir, direction, name)
   if not term:is_open() then term:open(size, direction) end
   -- going back from floating window closes it
   if term:is_float() then go_back = false end
@@ -235,9 +249,10 @@ function M.toggle_command(args, count)
     size = { parsed.size, "number", true },
     dir = { parsed.dir, "string", true },
     direction = { parsed.direction, "string", true },
+    name = { parsed.name, "string", true },
   })
   if parsed.size then parsed.size = tonumber(parsed.size) end
-  M.toggle(count, parsed.size, parsed.dir, parsed.direction)
+  M.toggle(count, parsed.size, parsed.dir, parsed.direction, parsed.name)
 end
 
 function _G.___toggleterm_winbar_click(id)
@@ -259,11 +274,12 @@ end
 --- @param size number?
 --- @param dir string?
 --- @param direction string?
-function M.toggle(count, size, dir, direction)
+--- @param name string?
+function M.toggle(count, size, dir, direction, name)
   if count and count >= 1 then
-    toggle_nth_term(count, size, dir, direction)
+    toggle_nth_term(count, size, dir, direction, name)
   else
-    smart_toggle(size, dir, direction)
+    smart_toggle(size, dir, direction, name)
   end
 end
 

lua/toggleterm/commandline.lua

@@ -15,6 +15,7 @@ local is_windows = vim.loop.os_uname().version:match("Windows")
 ---@field cmd string?
 ---@field dir string?
 ---@field size number?
+---@field name string?
 ---@field go_back boolean?
 ---@field open boolean?
 
@@ -144,12 +145,16 @@ local term_exec_options = {
   --- The size param takes in arbitrary numbers, we keep this function only to
   --- match the signature of other options
   size = function() return {} end,
+  --- The name param takes in arbitrary strings, we keep this function only to
+  --- match the signature of other options
+  name = function() return {} end,
 }
 
 local toggle_term_options = {
   dir = term_exec_options.dir,
   direction = term_exec_options.direction,
   size = term_exec_options.size,
+  name = term_exec_options.name,
 }
 
 ---@param options table a dictionary of key to function

lua/toggleterm/terminal.lua

@@ -195,6 +195,7 @@ function Terminal:new(term)
   self.__index = self
   term.direction = term.direction or conf.direction
   term.id = id or next_id()
+  term.display_name = term.display_name
   term.float_opts = vim.tbl_deep_extend("keep", term.float_opts or {}, conf.float_opts)
   term.clear_env = term.clear_env
   term.auto_scroll = vim.F.if_nil(term.auto_scroll, conf.auto_scroll)
@@ -519,13 +520,14 @@ end
 ---@param num number?
 ---@param dir string?
 ---@param direction string?
+---@param name string?
 ---@return Terminal
 ---@return boolean
-function M.get_or_create_term(num, dir, direction)
+function M.get_or_create_term(num, dir, direction, name)
   local term = M.get(num)
   if term then return term, false end
   if dir and fn.isdirectory(fn.expand(dir)) == 0 then dir = nil end
-  return Terminal:new({ id = num, dir = dir, direction = direction }), true
+  return Terminal:new({ id = num, dir = dir, direction = direction, display_name = name }), true
 end
 
 ---Get a single terminal by id, unless it is hidden

tests/command-complete_spec.lua

@@ -3,7 +3,7 @@ describe("command-complete", function()
   it("should return the default options", function()
     local results = command_complete.term_exec_complete("", "TermExec ", 9)
 
-    assert.is_equal("cmd=, dir=, direction=, size=", table.concat(results, ", "))
+    assert.is_equal("cmd=, dir=, direction=, name=, size=", table.concat(results, ", "))
   end)
 
   describe("helpers", function()

tests/commandline_spec.lua

@@ -34,6 +34,13 @@ describe("Commandline tests:", function()
     assert.equal(34, result.size)
   end)
 
+  it("should handle name args correctly", function()
+    local result = parser.parse("name=sample")
+    assert.is_truthy(result.name)
+    assert.is_true(type(result.name) == "string")
+    assert.equal("sample", result.name)
+  end)
+
   it("should handle go_back args correctly", function()
     local result = parser.parse("go_back=0")
     assert.is_true(type(result.go_back) == "boolean")