API: nvim_create_buf: add scratch parameter

Creating a scratch buffer is a chore/ritual, and would be more
useful/common if formally exposed.

runtime/doc/windows.txt

@@ -1256,6 +1256,7 @@ directory	Displays directory contents.  Can be used by a file explorer
 <		The buffer name is the name of the directory and is adjusted
 		when using the |:cd| command.
 
+						*scratch-buffer*
 scratch		Contains text that can be discarded at any time.  It is kept
 		when closing the window, it must be deleted explicitly.
 		Settings: >

src/nvim/api/vim.c

@@ -955,23 +955,36 @@ void nvim_set_current_win(Window window, Error *err)
   }
 }
 
-/// Create new empty buffer
+/// Creates a new, empty, unnamed buffer.
 ///
-/// @param listed whether the buffer should be listed
+/// @param listed Controls 'buflisted'
+/// @param scratch Creates a "throwaway" |scratch-buffer| for temporary work
+///                (always 'nomodified')
 /// @param[out] err Error details, if any
-/// @return the buffer handle or 0 when error
-Buffer nvim_create_buf(Boolean listed, Error *err)
+/// @return Buffer handle, or 0 on error
+///
+/// @see buf_open_scratch
+Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
   FUNC_API_SINCE(6)
 {
   try_start();
-  Buffer buffer = buflist_add(NULL,
-                              BLN_NOOPT | BLN_NEW | (listed ? BLN_LISTED : 0));
-  if (!try_end(err) && buffer == 0) {
-    api_set_error(err,
-                  kErrorTypeException,
-                  "Failed to create buffer");
+  buf_T *buf = buflist_new(NULL, NULL, (linenr_T)0,
+                           BLN_NOOPT | BLN_NEW | (listed ? BLN_LISTED : 0));
+  try_end(err);
+  if (buf == NULL) {
+    if (!ERROR_SET(err)) {
+      api_set_error(err, kErrorTypeException, "Failed to create buffer");
+    }
+    return 0;
   }
-  return buffer;
+  if (scratch) {
+    WITH_BUFFER(buf, {
+      set_option_value("bh", 0L, "hide", OPT_LOCAL);
+      set_option_value("bt", 0L, "nofile", OPT_LOCAL);
+      set_option_value("swf", 0L, NULL, OPT_LOCAL);
+    });
+  }
+  return buf->b_fnum;
 }
 
 /// Gets the current list of tabpage handles.

test/functional/api/vim_spec.lua

@@ -1312,8 +1312,8 @@ describe('API', function()
 
   describe('nvim_create_buf', function()
     it('works', function()
-      eq({id=2}, meths.create_buf(true))
-      eq({id=3}, meths.create_buf(false))
+      eq({id=2}, meths.create_buf(true, false))
+      eq({id=3}, meths.create_buf(false, false))
       eq('  1 %a   "[No Name]"                    line 1\n'..
          '  2      "[No Name]"                    line 0',
          meths.command_output("ls"))
@@ -1336,7 +1336,7 @@ describe('API', function()
 
     it('can change buftype before visiting', function()
       meths.set_option("hidden", false)
-      eq({id=2}, meths.create_buf(true))
+      eq({id=2}, meths.create_buf(true, false))
       meths.buf_set_option(2, "buftype", "nofile")
       meths.buf_set_lines(2, 0, -1, true, {"test text"})
       command("split | buffer 2")
@@ -1345,5 +1345,48 @@ describe('API', function()
       command("close")
       eq({id=1}, meths.get_current_buf())
     end)
+
+    it('|scratch-buffer|', function()
+      eq({id=2}, meths.create_buf(false, true))
+      eq({id=3}, meths.create_buf(true, true))
+      eq({id=4}, meths.create_buf(true, true))
+      local scratch_bufs = { 2, 3, 4 }
+      eq('  1 %a   "[No Name]"                    line 1\n'..
+         '  3      "[Scratch]"                    line 0\n'..
+         '  4      "[Scratch]"                    line 0',
+         meths.command_output("ls"))
+      -- current buffer didn't change
+      eq({id=1}, meths.get_current_buf())
+
+      local screen = Screen.new(20, 4)
+      screen:attach()
+
+      --
+      -- Editing a scratch-buffer does NOT change its properties.
+      --
+      local edited_buf = 2
+      meths.buf_set_lines(edited_buf, 0, -1, true, {"some text"})
+      for _,b in ipairs(scratch_bufs) do
+        eq('nofile', meths.buf_get_option(b, 'buftype'))
+        eq('hide', meths.buf_get_option(b, 'bufhidden'))
+        eq(false, meths.buf_get_option(b, 'swapfile'))
+      end
+
+      --
+      -- Visiting a scratch-buffer DOES change its properties.
+      --
+      meths.set_current_buf(edited_buf)
+      screen:expect([[
+        ^some text           |
+        {1:~                   }|
+        {1:~                   }|
+                            |
+      ]], {
+        [1] = {bold = true, foreground = Screen.colors.Blue1},
+      })
+      eq('', meths.buf_get_option(edited_buf, 'buftype'))
+      eq('', meths.buf_get_option(edited_buf, 'bufhidden'))
+      eq(false, meths.buf_get_option(edited_buf, 'swapfile'))
+    end)
   end)
 end)