feat(terminal): added Snacks.terminal.get(). Closes #122

doc/snacks-terminal.txt

@@ -12,6 +12,7 @@ Table of Contents                          *snacks-terminal-table-of-contents*
 5. Module                                             |snacks-terminal-module|
   - Snacks.terminal()               |snacks-terminal-module-snacks.terminal()|
   - Snacks.terminal.colorize()|snacks-terminal-module-snacks.terminal.colorize()|
+  - Snacks.terminal.get()       |snacks-terminal-module-snacks.terminal.get()|
   - Snacks.terminal.open()     |snacks-terminal-module-snacks.terminal.open()|
   - Snacks.terminal.toggle() |snacks-terminal-module-snacks.terminal.toggle()|
 6. Links                                               |snacks-terminal-links|
@@ -158,6 +159,19 @@ Example:
 <
 
 
+`Snacks.terminal.get()`                                *Snacks.terminal.get()*
+
+Get or create a terminal window. The terminal id is based on the `cmd`, `cwd`,
+`env` and `vim.v.count1` options. `opts.create` defaults to `true`.
+
+>lua
+    ---@param cmd? string | string[]
+    ---@param opts? snacks.terminal.Opts| {create?: boolean}
+    ---@return snacks.win? terminal, boolean? created
+    Snacks.terminal.get(cmd, opts)
+<
+
+
 `Snacks.terminal.open()`                              *Snacks.terminal.open()*
 
 Open a new terminal window.

docs/terminal.md

@@ -133,6 +133,19 @@ ls -la --color=always | nvim - -c "lua Snacks.terminal.colorize()"
 Snacks.terminal.colorize()
 ```
 
+### `Snacks.terminal.get()`
+
+Get or create a terminal window.
+The terminal id is based on the `cmd`, `cwd`, `env` and `vim.v.count1` options.
+`opts.create` defaults to `true`.
+
+```lua
+---@param cmd? string | string[]
+---@param opts? snacks.terminal.Opts| {create?: boolean}
+---@return snacks.win? terminal, boolean? created
+Snacks.terminal.get(cmd, opts)
+```
+
 ### `Snacks.terminal.open()`
 
 Open a new terminal window.

lua/snacks/terminal.lua

@@ -120,21 +120,30 @@ function M.open(cmd, opts)
   return terminal
 end
 
+--- Get or create a terminal window.
+--- The terminal id is based on the `cmd`, `cwd`, `env` and `vim.v.count1` options.
+--- `opts.create` defaults to `true`.
+---@param cmd? string | string[]
+---@param opts? snacks.terminal.Opts| {create?: boolean}
+---@return snacks.win? terminal, boolean? created
+function M.get(cmd, opts)
+  opts = opts or {}
+  local id = vim.inspect({ cmd = cmd, cwd = opts.cwd, env = opts.env, count = vim.v.count1 })
+  local created = false
+  if not (terminals[id] and terminals[id]:buf_valid()) and (opts.create ~= false) then
+    terminals[id] = M.open(cmd, opts)
+    created = true
+  end
+  return terminals[id], created
+end
+
 --- Toggle a terminal window.
 --- The terminal id is based on the `cmd`, `cwd`, `env` and `vim.v.count1` options.
 ---@param cmd? string | string[]
 ---@param opts? snacks.terminal.Opts
 function M.toggle(cmd, opts)
-  opts = opts or {}
-
-  local id = vim.inspect({ cmd = cmd, cwd = opts.cwd, env = opts.env, count = vim.v.count1 })
-
-  if terminals[id] and terminals[id]:buf_valid() then
-    terminals[id]:toggle()
-  else
-    terminals[id] = M.open(cmd, opts)
-  end
-  return terminals[id]
+  local terminal, created = M.get(cmd, opts)
+  return created and terminal or assert(terminal):toggle()
 end
 
 --- Parses a shell command into a table of arguments.

lua/snacks/win.lua

@@ -225,6 +225,7 @@ end
 
 function M:hide()
   self:close({ buf = false })
+  return self
 end
 
 function M:toggle()
@@ -233,6 +234,7 @@ function M:toggle()
   else
     self:show()
   end
+  return self
 end
 
 ---@private