feat(prompt): prompt_appendbuf() appends to prompt buffer #37763

Problem:
Currently, we recommend always inserting text above prompt-line in
prompt-buffer. This can be done using the `:` mark. However, although
we recommend it this way it can sometimes get confusing how to do it
best.

Solution:
Provide an api to append text to prompt buffer. This is a common
use-case for things using prompt-buffer.

src/nvim/eval.lua

@@ -8371,6 +8371,32 @@ M.funcs = {
     signature = 'printf({fmt}, {expr1} ...)',
     returns = 'string',
   },
+  prompt_appendbuf = {
+    args = 2,
+    base = 2,
+    desc = [=[
+      Appends text to prompt buffer before current prompt. When {text} is
+      a |List|: Append each item of the |List| as a text line above
+      prompt-line in the buffer. Any type of item is accepted and converted
+      to a String. Returns 1 for failure ({buf} not a prmopt buffer),
+      0 for success.  When {text} is an empty list zero is returned.
+
+      Example: >vim
+        func TextEntered(text)
+          call prompt_appendbuf(bufnr(''), split('Entered: "' . a:text . '"', '\n'))
+        endfunc
+
+        set buftype=prompt
+        call prompt_setcallback(bufnr(''), function("TextEntered"))
+        eval bufnr("")->prompt_setprompt("cmd: ")
+        startinsert
+      <
+    ]=],
+    name = 'prompt_appendbuf',
+    params = { { 'buf', 'integer|string' }, { 'text', 'string|string[]' } },
+    returns = '0|1',
+    signature = 'prompt_appendbuf({buf}, {text})',
+  },
   prompt_getinput = {
     args = 1,
     base = 1,