feat(jobs): jobstart(…,{term=true}), deprecate termopen() #31343

Problem:
`termopen` has long been a superficial wrapper around `jobstart`, and
has no real purpose. Also, `vim.system` and `nvim_open_term` presumably
will replace all features of `jobstart` and `termopen`, so centralizing
the logic will help with that.

Solution:
- Introduce `eval/deprecated.c`, where all deprecated eval funcs will live.
- Introduce "term" flag of `jobstart`.
- Deprecate `termopen`.

8 files changed, 30 insertions, 25 deletions

diff --git a/test/functional/terminal/buffer_spec.lua b/test/functional/terminal/buffer_spec.lua
index edb4c928c1..e209ed9025 100644
--- a/test/functional/terminal/buffer_spec.lua
+++ b/test/functional/terminal/buffer_spec.lua
@@ -378,7 +378,7 @@ describe(':terminal buffer', function()
     }, exec_lua('return _G.input'))
   end)
 
-  it('no heap-buffer-overflow when using termopen(echo) #3161', function()
+  it('no heap-buffer-overflow when using jobstart("echo",{term=true}) #3161', function()
     local testfilename = 'Xtestfile-functional-terminal-buffers_spec'
     write_file(testfilename, 'aaaaaaaaaaaaaaaaaaaaaaaaaaaa')
     finally(function()
@@ -387,8 +387,8 @@ describe(':terminal buffer', function()
     feed_command('edit ' .. testfilename)
     -- Move cursor away from the beginning of the line
     feed('$')
-    -- Let termopen() modify the buffer
-    feed_command('call termopen("echo")')
+    -- Let jobstart(…,{term=true}) modify the buffer
+    feed_command([[call jobstart("echo", {'term':v:true})]])
     assert_alive()
     feed_command('bdelete!')
   end)
@@ -411,7 +411,7 @@ describe(':terminal buffer', function()
 
   it('handles split UTF-8 sequences #16245', function()
     local screen = Screen.new(50, 7)
-    fn.termopen({ testprg('shell-test'), 'UTF-8' })
+    fn.jobstart({ testprg('shell-test'), 'UTF-8' }, { term = true })
     screen:expect([[
       ^å                                                 |
       ref: å̲                                            |
@@ -669,7 +669,7 @@ if is_os('win') then
   end)
 end
 
-describe('termopen()', function()
+describe('termopen() (deprecated alias to `jobstart(…,{term=true})`)', function()
   before_each(clear)
 
   it('disallowed when textlocked and in cmdwin buffer', function()
diff --git a/test/functional/terminal/channel_spec.lua b/test/functional/terminal/channel_spec.lua
index 9912c1ff7b..bb97411f43 100644
--- a/test/functional/terminal/channel_spec.lua
+++ b/test/functional/terminal/channel_spec.lua
@@ -75,8 +75,8 @@ describe('terminal channel is closed and later released if', function()
     eq(chans - 1, eval('len(nvim_list_chans())'))
   end)
 
-  it('opened by termopen(), exited, and deleted by pressing a key', function()
-    command([[let id = termopen('echo')]])
+  it('opened by jobstart(…,{term=true}), exited, and deleted by pressing a key', function()
+    command([[let id = jobstart('echo',{'term':v:true})]])
     local chans = eval('len(nvim_list_chans())')
     -- wait for process to exit
     screen:expect({ any = '%[Process exited 0%]' })
@@ -96,8 +96,8 @@ describe('terminal channel is closed and later released if', function()
   end)
 
   -- This indirectly covers #16264
-  it('opened by termopen(), exited, and deleted by :bdelete', function()
-    command([[let id = termopen('echo')]])
+  it('opened by jobstart(…,{term=true}), exited, and deleted by :bdelete', function()
+    command([[let id = jobstart('echo', {'term':v:true})]])
     local chans = eval('len(nvim_list_chans())')
     -- wait for process to exit
     screen:expect({ any = '%[Process exited 0%]' })
@@ -124,7 +124,7 @@ it('chansend sends lines to terminal channel in proper order', function()
   screen._default_attr_ids = nil
   local shells = is_os('win') and { 'cmd.exe', 'pwsh.exe -nop', 'powershell.exe -nop' } or { 'sh' }
   for _, sh in ipairs(shells) do
-    command([[let id = termopen(']] .. sh .. [[')]])
+    command([[let id = jobstart(']] .. sh .. [[', {'term':v:true})]])
     command([[call chansend(id, ['echo "hello"', 'echo "world"', ''])]])
     screen:expect {
       any = [[echo "hello".*echo "world"]],
@@ -149,7 +149,7 @@ describe('no crash when TermOpen autocommand', function()
     })
   end)
 
-  it('processes job exit event when using termopen()', function()
+  it('processes job exit event when using jobstart(…,{term=true})', function()
     command([[autocmd TermOpen * call input('')]])
     async_meths.nvim_command('terminal foobar')
     screen:expect {
@@ -179,7 +179,7 @@ describe('no crash when TermOpen autocommand', function()
     assert_alive()
   end)
 
-  it('wipes buffer and processes events when using termopen()', function()
+  it('wipes buffer and processes events when using jobstart(…,{term=true})', function()
     command([[autocmd TermOpen * bwipe! | call input('')]])
     async_meths.nvim_command('terminal foobar')
     screen:expect {
diff --git a/test/functional/terminal/clipboard_spec.lua b/test/functional/terminal/clipboard_spec.lua
index 4a1a0e29fd..f0ce407eaa 100644
--- a/test/functional/terminal/clipboard_spec.lua
+++ b/test/functional/terminal/clipboard_spec.lua
@@ -56,7 +56,7 @@ describe(':terminal', function()
       return string.format('\027]52;;%s\027\\', arg)
     end
 
-    fn.termopen({ testprg('shell-test'), '-t', osc52(encoded) })
+    fn.jobstart({ testprg('shell-test'), '-t', osc52(encoded) }, { term = true })
 
     retry(nil, 1000, function()
       eq(text, exec_lua([[ return vim.g.clipboard_data ]]))
diff --git a/test/functional/terminal/cursor_spec.lua b/test/functional/terminal/cursor_spec.lua
index 368afd6d36..8594a9ce16 100644
--- a/test/functional/terminal/cursor_spec.lua
+++ b/test/functional/terminal/cursor_spec.lua
@@ -239,7 +239,7 @@ describe(':terminal cursor', function()
     feed([[<C-\><C-N>]])
     command('set statusline=~~~')
     command('new')
-    call('termopen', { testprg('tty-test') })
+    call('jobstart', { testprg('tty-test') }, { term = true })
     feed('i')
     screen:expect({
       grid = [[
diff --git a/test/functional/terminal/ex_terminal_spec.lua b/test/functional/terminal/ex_terminal_spec.lua
index 5ebe7bd4fc..5224d322d3 100644
--- a/test/functional/terminal/ex_terminal_spec.lua
+++ b/test/functional/terminal/ex_terminal_spec.lua
@@ -175,7 +175,7 @@ local function test_terminal_with_fake_shell(backslash)
     api.nvim_set_option_value('shellxquote', '', {}) -- win: avoid extra quotes
   end)
 
-  it('with no argument, acts like termopen()', function()
+  it('with no argument, acts like jobstart(…,{term=true})', function()
     command('autocmd! nvim_terminal TermClose')
     feed_command('terminal')
     screen:expect([[
@@ -196,7 +196,7 @@ local function test_terminal_with_fake_shell(backslash)
     ]])
   end)
 
-  it("with no argument, but 'shell' has arguments, acts like termopen()", function()
+  it("with no argument, but 'shell' has arguments, acts like jobstart(…,{term=true})", function()
     api.nvim_set_option_value('shell', shell_path .. ' INTERACT', {})
     feed_command('terminal')
     screen:expect([[
diff --git a/test/functional/terminal/highlight_spec.lua b/test/functional/terminal/highlight_spec.lua
index 5ed3c72b72..c43d139f70 100644
--- a/test/functional/terminal/highlight_spec.lua
+++ b/test/functional/terminal/highlight_spec.lua
@@ -33,7 +33,7 @@ describe(':terminal highlight', function()
       [12] = { bold = true, underdouble = true },
       [13] = { italic = true, undercurl = true },
     })
-    command(("enew | call termopen(['%s'])"):format(testprg('tty-test')))
+    command(("enew | call jobstart(['%s'], {'term':v:true})"):format(testprg('tty-test')))
     feed('i')
     screen:expect([[
       tty ready                                         |
@@ -150,7 +150,7 @@ it(':terminal highlight has lower precedence than editor #9964', function()
     },
   })
   -- Child nvim process in :terminal (with cterm colors).
-  fn.termopen({
+  fn.jobstart({
     nvim_prog_abs(),
     '-n',
     '-u',
@@ -163,6 +163,7 @@ it(':terminal highlight has lower precedence than editor #9964', function()
     '+norm! ichild nvim',
     '+norm! oline 2',
   }, {
+    term = true,
     env = {
       VIMRUNTIME = os.getenv('VIMRUNTIME'),
     },
@@ -200,7 +201,7 @@ it('CursorLine and CursorColumn work in :terminal buffer in Normal mode', functi
     [4] = { background = Screen.colors.Grey90, reverse = true },
     [5] = { background = Screen.colors.Red },
   })
-  command(("enew | call termopen(['%s'])"):format(testprg('tty-test')))
+  command(("enew | call jobstart(['%s'], {'term':v:true})"):format(testprg('tty-test')))
   screen:expect([[
     ^tty ready                                         |
                                                       |*6
@@ -318,7 +319,7 @@ describe(':terminal highlight forwarding', function()
       [2] = { { fg_indexed = true, foreground = tonumber('0xe0e000') }, { foreground = 3 } },
       [3] = { { foreground = tonumber('0xff8000') }, {} },
     })
-    command(("enew | call termopen(['%s'])"):format(testprg('tty-test')))
+    command(("enew | call jobstart(['%s'], {'term':v:true})"):format(testprg('tty-test')))
     feed('i')
     screen:expect([[
       tty ready                                         |
@@ -364,7 +365,7 @@ describe(':terminal highlight with custom palette', function()
       [9] = { bold = true },
     })
     api.nvim_set_var('terminal_color_3', '#123456')
-    command(("enew | call termopen(['%s'])"):format(testprg('tty-test')))
+    command(("enew | call jobstart(['%s'], {'term':v:true})"):format(testprg('tty-test')))
     feed('i')
     screen:expect([[
       tty ready                                         |
diff --git a/test/functional/terminal/scrollback_spec.lua b/test/functional/terminal/scrollback_spec.lua
index 0de7873200..804c5367eb 100644
--- a/test/functional/terminal/scrollback_spec.lua
+++ b/test/functional/terminal/scrollback_spec.lua
@@ -355,7 +355,9 @@ describe(':terminal prints more lines than the screen height and exits', functio
   it('will push extra lines to scrollback', function()
     clear()
     local screen = Screen.new(30, 7, { rgb = false })
-    command(("call termopen(['%s', '10']) | startinsert"):format(testprg('tty-test')))
+    command(
+      ("call jobstart(['%s', '10'], {'term':v:true}) | startinsert"):format(testprg('tty-test'))
+    )
     screen:expect([[
       line6                         |
       line7                         |
@@ -623,7 +625,7 @@ describe('pending scrollback line handling', function()
       local bufnr = vim.api.nvim_create_buf(false, true)
       local args = ...
       vim.api.nvim_buf_call(bufnr, function()
-        vim.fn.termopen(args)
+        vim.fn.jobstart(args, { term = true })
       end)
       vim.api.nvim_win_set_buf(0, bufnr)
       vim.cmd('startinsert')
diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua
index 832bacb534..de92aefd5b 100644
--- a/test/functional/terminal/tui_spec.lua
+++ b/test/functional/terminal/tui_spec.lua
@@ -2114,7 +2114,7 @@ describe('TUI', function()
       [5] = { bold = true, reverse = true },
       [6] = { foreground = Screen.colors.White, background = Screen.colors.DarkGreen },
     })
-    fn.termopen({
+    fn.jobstart({
       nvim_prog,
       '--clean',
       '--cmd',
@@ -2124,6 +2124,7 @@ describe('TUI', function()
       '--cmd',
       'let start = reltime() | while v:true | if reltimefloat(reltime(start)) > 2 | break | endif | endwhile',
     }, {
+      term = true,
       env = {
         VIMRUNTIME = os.getenv('VIMRUNTIME'),
       },
@@ -2146,7 +2147,7 @@ describe('TUI', function()
   for _, guicolors in ipairs({ 'notermguicolors', 'termguicolors' }) do
     it('has no black flicker when clearing regions during startup with ' .. guicolors, function()
       local screen = Screen.new(50, 10)
-      fn.termopen({
+      fn.jobstart({
         nvim_prog,
         '--clean',
         '--cmd',
@@ -2154,6 +2155,7 @@ describe('TUI', function()
         '--cmd',
         'sleep 10',
       }, {
+        term = true,
         env = {
           VIMRUNTIME = os.getenv('VIMRUNTIME'),
         },