vim-patch:8.2.4455: accepting one and zero for second sort() argument is strange

Problem:    Accepting one and zero for the second sort() argument is strange.
Solution:   Disallow using one and zero in Vim9 script.

https://github.com/vim/vim/commit/2007dd49f5cb36f944cab1cfbceb0f864e625f74

Co-authored-by: Bram Moolenaar <Bram@vim.org>

4 files changed, 43 insertions, 30 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 4b617763da..8e92ca4e1c 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -7177,21 +7177,22 @@ sockconnect({mode}, {address} [, {opts}])                        *sockconnect()*
 		  - The channel ID on success (greater than zero)
 		  - 0 on invalid arguments or connection failure.
 
-sort({list} [, {func} [, {dict}]])                                 *sort()* *E702*
+sort({list} [, {how} [, {dict}]])                                  *sort()* *E702*
 		Sort the items in {list} in-place.  Returns {list}.
 
 		If you want a list to remain unmodified make a copy first: >vim
 			let sortedlist = sort(copy(mylist))
 
-<		When {func} is omitted, is empty or zero, then sort() uses the
+<		When {how} is omitted or is a string, then sort() uses the
 		string representation of each item to sort on.  Numbers sort
 		after Strings, |Lists| after Numbers.  For sorting text in the
 		current buffer use |:sort|.
 
-		When {func} is given and it is '1' or 'i' then case is
-		ignored.
+		When {how} is given and it is 'i' then case is ignored.
+		For backwards compatibility, the value one can be used to
+		ignore case.  Zero means to not ignore case.
 
-		When {func} is given and it is 'l' then the current collation
+		When {how} is given and it is 'l' then the current collation
 		locale is used for ordering. Implementation details: strcoll()
 		is used to compare strings. See |:language| check or set the
 		collation locale. |v:collate| can also be used to check the
@@ -7208,19 +7209,19 @@ sort({list} [, {func} [, {dict}]])                                 *sort()* *E70
 <			['n', 'o', 'O', 'p', 'z', 'ö'] ~
 		This does not work properly on Mac.
 
-		When {func} is given and it is 'n' then all items will be
+		When {how} is given and it is 'n' then all items will be
 		sorted numerical (Implementation detail: this uses the
 		strtod() function to parse numbers, Strings, Lists, Dicts and
 		Funcrefs will be considered as being 0).
 
-		When {func} is given and it is 'N' then all items will be
+		When {how} is given and it is 'N' then all items will be
 		sorted numerical. This is like 'n' but a string containing
 		digits will be used as the number they represent.
 
-		When {func} is given and it is 'f' then all items will be
+		When {how} is given and it is 'f' then all items will be
 		sorted numerical. All values must be a Number or a Float.
 
-		When {func} is a |Funcref| or a function name, this function
+		When {how} is a |Funcref| or a function name, this function
 		is called to compare items.  The function is invoked with two
 		items as argument and must return zero if they are equal, 1 or
 		bigger if the first one sorts after the second one, -1 or
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 17eda634e0..d1c90249ed 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -8531,15 +8531,16 @@ function vim.fn.sockconnect(mode, address, opts) end
 --- If you want a list to remain unmodified make a copy first: >vim
 ---   let sortedlist = sort(copy(mylist))
 ---
---- <When {func} is omitted, is empty or zero, then sort() uses the
+--- <When {how} is omitted or is a string, then sort() uses the
 --- string representation of each item to sort on.  Numbers sort
 --- after Strings, |Lists| after Numbers.  For sorting text in the
 --- current buffer use |:sort|.
 ---
---- When {func} is given and it is '1' or 'i' then case is
---- ignored.
+--- When {how} is given and it is 'i' then case is ignored.
+--- For backwards compatibility, the value one can be used to
+--- ignore case.  Zero means to not ignore case.
 ---
---- When {func} is given and it is 'l' then the current collation
+--- When {how} is given and it is 'l' then the current collation
 --- locale is used for ordering. Implementation details: strcoll()
 --- is used to compare strings. See |:language| check or set the
 --- collation locale. |v:collate| can also be used to check the
@@ -8556,19 +8557,19 @@ function vim.fn.sockconnect(mode, address, opts) end
 --- <  ['n', 'o', 'O', 'p', 'z', 'ö'] ~
 --- This does not work properly on Mac.
 ---
---- When {func} is given and it is 'n' then all items will be
+--- When {how} is given and it is 'n' then all items will be
 --- sorted numerical (Implementation detail: this uses the
 --- strtod() function to parse numbers, Strings, Lists, Dicts and
 --- Funcrefs will be considered as being 0).
 ---
---- When {func} is given and it is 'N' then all items will be
+--- When {how} is given and it is 'N' then all items will be
 --- sorted numerical. This is like 'n' but a string containing
 --- digits will be used as the number they represent.
 ---
---- When {func} is given and it is 'f' then all items will be
+--- When {how} is given and it is 'f' then all items will be
 --- sorted numerical. All values must be a Number or a Float.
 ---
---- When {func} is a |Funcref| or a function name, this function
+--- When {how} is a |Funcref| or a function name, this function
 --- is called to compare items.  The function is invoked with two
 --- items as argument and must return zero if they are equal, 1 or
 --- bigger if the first one sorts after the second one, -1 or
@@ -8598,10 +8599,10 @@ function vim.fn.sockconnect(mode, address, opts) end
 --- <
 ---
 --- @param list any
---- @param func? any
+--- @param how? any
 --- @param dict? any
 --- @return any
-function vim.fn.sort(list, func, dict) end
+function vim.fn.sort(list, how, dict) end
 
 --- Return the sound-folded equivalent of {word}.  Uses the first
 --- language in 'spelllang' for the current window that supports
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index f8ba16365a..1ce6b0b247 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -10157,15 +10157,16 @@ M.funcs = {
       If you want a list to remain unmodified make a copy first: >vim
       	let sortedlist = sort(copy(mylist))
 
-      <When {func} is omitted, is empty or zero, then sort() uses the
+      <When {how} is omitted or is a string, then sort() uses the
       string representation of each item to sort on.  Numbers sort
       after Strings, |Lists| after Numbers.  For sorting text in the
       current buffer use |:sort|.
 
-      When {func} is given and it is '1' or 'i' then case is
-      ignored.
+      When {how} is given and it is 'i' then case is ignored.
+      For backwards compatibility, the value one can be used to
+      ignore case.  Zero means to not ignore case.
 
-      When {func} is given and it is 'l' then the current collation
+      When {how} is given and it is 'l' then the current collation
       locale is used for ordering. Implementation details: strcoll()
       is used to compare strings. See |:language| check or set the
       collation locale. |v:collate| can also be used to check the
@@ -10182,19 +10183,19 @@ M.funcs = {
       <	['n', 'o', 'O', 'p', 'z', 'ö'] ~
       This does not work properly on Mac.
 
-      When {func} is given and it is 'n' then all items will be
+      When {how} is given and it is 'n' then all items will be
       sorted numerical (Implementation detail: this uses the
       strtod() function to parse numbers, Strings, Lists, Dicts and
       Funcrefs will be considered as being 0).
 
-      When {func} is given and it is 'N' then all items will be
+      When {how} is given and it is 'N' then all items will be
       sorted numerical. This is like 'n' but a string containing
       digits will be used as the number they represent.
 
-      When {func} is given and it is 'f' then all items will be
+      When {how} is given and it is 'f' then all items will be
       sorted numerical. All values must be a Number or a Float.
 
-      When {func} is a |Funcref| or a function name, this function
+      When {how} is a |Funcref| or a function name, this function
       is called to compare items.  The function is invoked with two
       items as argument and must return zero if they are equal, 1 or
       bigger if the first one sorts after the second one, -1 or
@@ -10224,8 +10225,8 @@ M.funcs = {
       <
     ]=],
     name = 'sort',
-    params = { { 'list', 'any' }, { 'func', 'any' }, { 'dict', 'any' } },
-    signature = 'sort({list} [, {func} [, {dict}]])',
+    params = { { 'list', 'any' }, { 'how', 'any' }, { 'dict', 'any' } },
+    signature = 'sort({list} [, {how} [, {dict}]])',
   },
   soundfold = {
     args = 1,
diff --git a/test/old/testdir/test_listdict.vim b/test/old/testdir/test_listdict.vim
index 593fd12c1e..f2b4747ff2 100644
--- a/test/old/testdir/test_listdict.vim
+++ b/test/old/testdir/test_listdict.vim
@@ -887,7 +887,7 @@ func Test_reverse_sort_uniq()
         call assert_equal([-1, 'one', 'two', 'three', 'four', 1.0e-15, 0.22, 7, 9, 12, 18, 22, 255], sort(copy(l), 'n'))
 
         LET l = [7, 9, 18, 12, 22, 10.0e-16, -1, 0xff, 0, -0, 0.22, 'bar', 'BAR', 'Bar', 'Foo', 'FOO', 'foo', 'FOOBAR', {}, []]
-        call assert_equal(['bar', 'BAR', 'Bar', 'Foo', 'FOO', 'foo', 'FOOBAR', -1, 0, 0, 0.22, 1.0e-15, 12, 18, 22, 255, 7, 9, [], {}], sort(copy(l), 1))
+        call assert_equal(['bar', 'BAR', 'Bar', 'Foo', 'FOO', 'foo', 'FOOBAR', -1, 0, 0, 0.22, 1.0e-15, 12, 18, 22, 255, 7, 9, [], {}], sort(copy(l), 'i'))
         call assert_equal(['bar', 'BAR', 'Bar', 'Foo', 'FOO', 'foo', 'FOOBAR', -1, 0, 0, 0.22, 1.0e-15, 12, 18, 22, 255, 7, 9, [], {}], sort(copy(l), 'i'))
         call assert_equal(['BAR', 'Bar', 'FOO', 'FOOBAR', 'Foo', 'bar', 'foo', -1, 0, 0, 0.22, 1.0e-15, 12, 18, 22, 255, 7, 9, [], {}], sort(copy(l)))
       endif
@@ -899,6 +899,16 @@ func Test_reverse_sort_uniq()
   call assert_fails("call sort([1, 2], function('min'), 1)", "E1206:")
   call assert_fails("call sort([1, 2], function('invalid_func'))", "E700:")
   call assert_fails("call sort([1, 2], function('min'))", "E118:")
+
+  let lines =<< trim END
+    call sort(['a', 'b'], 0)
+  END
+  call CheckDefAndScriptFailure(lines, 'E1256: String or function required for argument 2')
+
+  let lines =<< trim END
+    call sort(['a', 'b'], 1)
+  END
+  call CheckDefAndScriptFailure(lines, 'E1256: String or function required for argument 2')
 endfunc
 
 " reduce a list, blob or string