vim-patch:8.2.4607: sourcing buffer lines may lead to errors for conflicts

Problem:    Sourcing buffer lines may lead to errors for conflicts.
Solution:   Add the ++clear argument. (Yegappan Lakshmanan, closes vim/vim#9991)

35dc17634d

Documentation changes only. Vim9script is N/A.
Cherry-pick another documentation change for :source from latest Vim.

Co-authored-by: Yegappan Lakshmanan <yegappan@yahoo.com>

runtime/doc/repeat.txt

@@ -197,13 +197,15 @@ For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
 			Triggers the |SourcePre| autocommand.
 
 :[range]so[urce]	Read Ex commands or Lua code from the [range] of lines
-			in the current buffer.  The buffer is treated as Lua
+			in the current buffer.  When [range] is omitted read
-			code if 'filetype' is "lua" or its filename ends with
+			all lines.  The buffer is treated as Lua code if its
-			".lua".  When sourcing commands or Lua code from the
+			'filetype' is "lua" or its filename ends with ".lua".
-			current buffer, the same script-ID |<SID>| is used
+
-			even if the buffer is sourced multiple times. If a
+			When sourcing commands or Lua code from the current
-			buffer is sourced more than once, then the functions
+			buffer, the same script-ID |<SID>| is used even if the
-			in the buffer are redefined again.
+			buffer is sourced multiple times. If a buffer is
+			sourced more than once, then the functions in the
+			buffer are defined again.
 
 							*:source!*
 :so[urce]! {file}

test/old/testdir/test_source.vim

@@ -607,6 +607,34 @@ func Test_source_buffer_vim9()
   source
   call assert_equal('red', g:Color)
 
+  " test for ++clear argument to clear all the functions/variables
+  %d _
+  let lines =<< trim END
+     g:ScriptVarFound = exists("color")
+     g:MyFuncFound = exists('*Myfunc')
+     if g:MyFuncFound
+       finish
+     endif
+     var color = 'blue'
+     def Myfunc()
+     enddef
+  END
+  call setline(1, lines)
+  vim9cmd source
+  call assert_false(g:MyFuncFound)
+  call assert_false(g:ScriptVarFound)
+  vim9cmd source
+  call assert_true(g:MyFuncFound)
+  call assert_true(g:ScriptVarFound)
+  vim9cmd source ++clear
+  call assert_false(g:MyFuncFound)
+  call assert_false(g:ScriptVarFound)
+  vim9cmd source ++clear
+  call assert_false(g:MyFuncFound)
+  call assert_false(g:ScriptVarFound)
+  call assert_fails('vim9cmd source ++clearx', 'E475:')
+  call assert_fails('vim9cmd source ++abcde', 'E484:')
+
   %bw!
 endfunc