refactor(lua): deprecate tbl_flatten

Problem:
Besides being redundant with vim.iter():flatten(), `tbl_flatten` has
these problems:

- Has `tbl_` prefix but only accepts lists.
- Discards some results! Compare the following:
  - iter.flatten():
    ```
    vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
    ```
  - tbl_flatten:
    ```
    vim.tbl_flatten({1, { { a = 2 } }, { 3 } })
    ```

Solution:
Deprecate tbl_flatten.

Note:
iter:flatten() currently fails ("flatten() requires a list-like table")
on this code from gen_lsp.lua:

    local anonym = vim.iter({ -- remove nil
      anonymous_num > 1 and '' or nil,
      '---@class ' .. anonymous_classname,
    }):flatten():totable()

Should we enhance :flatten() to work for arrays?

1 files changed, 2 insertions, 2 deletions

diff --git a/test/functional/core/fileio_spec.lua b/test/functional/core/fileio_spec.lua
index 04d745a6c3..349f79e316 100644
--- a/test/functional/core/fileio_spec.lua
+++ b/test/functional/core/fileio_spec.lua
@@ -54,7 +54,7 @@ describe('fileio', function()
   --- Starts a new nvim session and returns an attached screen.
   local function startup(extra_args)
     extra_args = extra_args or {}
-    local argv = vim.tbl_flatten({ args, '--embed', extra_args })
+    local argv = vim.iter({ args, '--embed', extra_args }):flatten():totable()
     local screen_nvim = spawn(argv)
     set_session(screen_nvim)
     local screen = Screen.new(70, 10)
@@ -100,7 +100,7 @@ describe('fileio', function()
     eq('foozubbaz', trim(read_file('Xtest_startup_file1')))
 
     -- 4. Exit caused by deadly signal (+ 'swapfile').
-    local j = fn.jobstart(vim.tbl_flatten({ args, '--embed' }), { rpc = true })
+    local j = fn.jobstart(vim.iter({ args, '--embed' }):flatten():totable(), { rpc = true })
     fn.rpcrequest(
       j,
       'nvim_exec2',