vim-patch:8.1.1610: there is no way to add or load a buffer without side effects

Problem:    There is no way to add or load a buffer without side effects.
Solution:   Add the bufadd() and bufload() functions.
15e248e37f

runtime/doc/eval.txt

@@ -2006,8 +2006,10 @@ atan2({expr}, {expr})		Float   arc tangent of {expr1} / {expr2}
 browse({save}, {title}, {initdir}, {default})
 				String	put up a file requester
 browsedir({title}, {initdir})	String	put up a directory requester
+bufadd({name})			Number	add a buffer to the buffer list
 bufexists({expr})		Number	|TRUE| if buffer {expr} exists
 buflisted({expr})		Number	|TRUE| if buffer {expr} is listed
+bufload({expr})			Number	load buffer {expr} if not loaded yet
 bufloaded({expr})		Number	|TRUE| if buffer {expr} is loaded
 bufname({expr})		String	Name of the buffer {expr}
 bufnr({expr} [, {create}])	Number	Number of the buffer {expr}
@@ -2679,6 +2681,14 @@ browsedir({title}, {initdir})
 		When the "Cancel" button is hit, something went wrong, or
 		browsing is not possible, an empty string is returned.
 
+bufadd({name})						*bufadd()*
+		Add a buffer to the buffer list with {name}.
+		If a buffer for file {name} already exists, return that buffer
+		number.  Otherwise return the buffer number of the newly
+		created buffer.  When {name} is an empty string then a new
+		buffer is always created.
+		The buffer will not have' 'buflisted' set.
+
 bufexists({expr})					*bufexists()*
 		The result is a Number, which is |TRUE| if a buffer called
 		{expr} exists.
@@ -2706,6 +2716,15 @@ buflisted({expr})					*buflisted()*
 		{expr} exists and is listed (has the 'buflisted' option set).
 		The {expr} argument is used like with |bufexists()|.
 
+bufload({expr})						*bufload()*
+		Ensure the buffer {expr} is loaded.  When the buffer name
+		refers to an existing file then the file is read.  Otherwise
+		the buffer will be empty.  If the buffer was already loaded
+		then there is no change.
+		If there is an existing swap file for the file of the buffer,
+		there will be no dialog, the buffer will be loaded anyway.
+		The {expr} argument is used like with |bufexists()|.
+
 bufloaded({expr})					*bufloaded()*
 		The result is a Number, which is |TRUE| if a buffer called
 		{expr} exists and is loaded (shown in a window or hidden).

src/nvim/eval.c

@@ -7289,6 +7289,12 @@ static buf_T *find_buffer(typval_T *avar)
   return buf;
 }
 
+// "bufadd(expr)" function
+static void f_bufadd(typval_T *argvars, typval_T *rettv, FunPtr fptr)
+{
+  rettv->vval.v_number = buflist_add(tv_get_string(&argvars[0]), 0);
+}
+
 /*
  * "bufexists(expr)" function
  */
@@ -7308,6 +7314,21 @@ static void f_buflisted(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   rettv->vval.v_number = (buf != NULL && buf->b_p_bl);
 }
 
+// "bufload(expr)" function
+static void f_bufload(typval_T *argvars, typval_T *rettv unused)
+{
+  buf_T *buf = get_buf_arg(&argvars[0]);
+
+  if (buf != NULL && buf->b_ml.ml_mfp == NULL) {
+    aco_save_T aco;
+
+    aucmd_prepbuf(&aco, buf);
+    swap_exists_action = SEA_NONE;
+    open_buffer(FALSE, NULL, 0);
+    aucmd_restbuf(&aco);
+  }
+}
+
 /*
  * "bufloaded(expr)" function
  */

src/nvim/eval.lua

@@ -40,11 +40,13 @@ return {
     atan2={args=2},
     browse={args=4},
     browsedir={args=2},
+    bufadd={args=1},
     bufexists={args=1},
     buffer_exists={args=1, func='f_bufexists'},  -- obsolete
     buffer_name={args=1, func='f_bufname'},  -- obsolete
     buffer_number={args=1, func='f_bufnr'},  -- obsolete
     buflisted={args=1},
+    bufload={args=1},
     bufloaded={args=1},
     bufname={args=1},
     bufnr={args={1, 2}},

src/nvim/testdir/test_functions.vim

@@ -1188,3 +1188,31 @@ func Test_libcall_libcallnr()
   call assert_fails("call libcall('Xdoesnotexist_', 'getenv', 'HOME')", 'E364:')
   call assert_fails("call libcallnr('Xdoesnotexist_', 'strlen', 'abcd')", 'E364:')
 endfunc
+
+func Test_bufadd_bufload()
+  call assert_equal(0, bufexists('someName'))
+  let buf = bufadd('someName')
+  call assert_notequal(0, buf)
+  call assert_equal(1, bufexists('someName'))
+  call assert_equal(0, getbufvar(buf, '&buflisted'))
+  call assert_equal(0, bufloaded(buf))
+  call bufload(buf)
+  call assert_equal(1, bufloaded(buf))
+  call assert_equal([''], getbufline(buf, 1, '$'))
+
+  let curbuf = bufnr('')
+  call writefile(['some', 'text'], 'otherName')
+  let buf = bufadd('otherName')
+  call assert_notequal(0, buf)
+  call assert_equal(1, bufexists('otherName'))
+  call assert_equal(0, getbufvar(buf, '&buflisted'))
+  call assert_equal(0, bufloaded(buf))
+  call bufload(buf)
+  call assert_equal(1, bufloaded(buf))
+  call assert_equal(['some', 'text'], getbufline(buf, 1, '$'))
+  call assert_equal(curbuf, bufnr(''))
+
+  bwipe someName
+  bwipe otherName
+  call assert_equal(0, bufexists('someName'))
+endfunc