patch 8.1.1807: more functions can be used as a method

Problem:    More functions can be used as a method.
Solution:   Add append(), appendbufline(), assert_equal(), etc.
            Also add the :eval command.

runtime/doc/eval.txt

@@ -1,4 +1,4 @@
-*eval.txt*	For Vim version 8.1.  Last change: 2019 Jul 30
+*eval.txt*	For Vim version 8.1.  Last change: 2019 Aug 04
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -840,12 +840,14 @@ Expression syntax summary, from least to most significant:
 	expr8[expr1 : expr1]	substring of a String or sublist of a |List|
 	expr8.name		entry in a |Dictionary|
 	expr8(expr1, ...)	function call with |Funcref| variable
+	expr8->name(expr1, ...)	|method| call
 
 |expr9|	number			number constant
 	"string"		string constant, backslash is special
 	'string'		string constant, ' is doubled
 	[expr1, ...]		|List|
 	{expr1: expr1, ...}	|Dictionary|
+	#{key: expr1, ...}	|Dictionary|
 	&option			option value
 	(expr1)			nested expression
 	variable		internal variable
@@ -1111,10 +1113,10 @@ expr8							*expr8*
 -----
 This expression is either |expr9| or a sequence of the alternatives below,
 in any order.  E.g., these are all possible:
-	expr9[expr1].name
+	expr8[expr1].name
-	expr9.name[expr1]
+	expr8.name[expr1]
-	expr9(expr1, ...)[expr1].name
+	expr8(expr1, ...)[expr1].name
-	expr9->(expr1, ...)[expr1]
+	expr8->(expr1, ...)[expr1]
 Evaluation is always from left to right.
 
 
@@ -1217,10 +1219,17 @@ When expr8 is a |Funcref| type variable, invoke the function it refers to.
 
 expr8->name([args])	method call			*method*
 
-For global methods this is the same as: >
+For methods that are also available as global functions this is the same as: >
 	name(expr8 [, args])
 There can also be methods specifically for the type of "expr8".
 
+"->name(" must not contain white space.  There can be white space before "->"
+and after the "(".
+
+This allows for chaining, using the type that the method returns: >
+	mylist->filter(filterexpr)->map(mapexpr)->sort()->join()
+<
+
 							*expr9*
 number
 ------
@@ -2906,6 +2915,10 @@ append({lnum}, {text})					*append()*
 			:let failed = append(line('$'), "# THE END")
 			:let failed = append(0, ["Chapter 1", "the beginning"])
 
+<		Can also be used as a |method| after a List: >
+			mylist->append(lnum)
+
+
 appendbufline({expr}, {lnum}, {text})			*appendbufline()*
 		Like |append()| but append the text in buffer {expr}.
 
@@ -2921,8 +2934,11 @@ appendbufline({expr}, {lnum}, {text})			*appendbufline()*
 		error message is given. Example: >
 			:let failed = appendbufline(13, 0, "# THE START")
 <
-							*argc()*
+		Can also be used as a |method| after a List: >
-argc([{winid}])
+			mylist->appendbufline(buf, lnum)
+
+
+argc([{winid}])					*argc()*
 		The result is the number of files in the argument list.  See
 		|arglist|.
 		If {winid} is not supplied, the argument list of the current
@@ -3762,6 +3778,9 @@ eval({string})	Evaluate {string} and return the result.  Especially useful to
 		of them.  Also works for |Funcref|s that refer to existing
 		functions.
 
+		Can also be used as a |method|: >
+			argv->join()->eval()
+
 eventhandler()						*eventhandler()*
 		Returns 1 when inside an event handler.  That is that Vim got
 		interrupted while waiting for the user to type a character,
@@ -4115,7 +4134,12 @@ filereadable({file})					*filereadable()*
 		expression, which is used as a String.
 		If you don't care about the file being readable you can use
 		|glob()|.
-							*file_readable()*
+		{file} is used as-is, you may want to expand wildcards first: >
+			echo filereadable('~/.vimrc')
+			0
+			echo filereadable(expand('~/.vimrc'))
+			1
+<							*file_readable()*
 		Obsolete name: file_readable().
 
 
@@ -7998,9 +8022,9 @@ sha256({string})						*sha256()*
 
 shellescape({string} [, {special}])			*shellescape()*
 		Escape {string} for use as a shell command argument.
-		On MS-Windows and MS-DOS, when 'shellslash' is not set, it
+		On MS-Windows, when 'shellslash' is not set, it will enclose
-		will enclose {string} in double quotes and double all double
+		{string} in double quotes and double all double quotes within
-		quotes within {string}.
+		{string}.
 		Otherwise it will enclose {string} in single quotes and
 		replace all "'" with "'\''".
 
@@ -10047,6 +10071,10 @@ This function can then be called with: >
 The recursiveness of user functions is restricted with the |'maxfuncdepth'|
 option.
 
+It is also possible to use `:eval`.  It does not support a range, but does
+allow for method chaining, e.g.: >
+	eval GetList()->Filter()->append('$')
+
 
 AUTOMATICALLY LOADING FUNCTIONS ~
 							*autoload-functions*
@@ -10498,6 +10526,20 @@ text...
 			Unlock the internal variable {name}.  Does the
 			opposite of |:lockvar|.
 
+							*:eval*
+:eval {expr}		Evaluate {expr} and discard the result.  Example: >
+				:eval Getlist()->Filter()->append('$')
+
+<			The expression is supposed to have a side effect,
+			since the resulting value is not used.  In the example
+			the `append()` call appends the List with text to the
+			buffer.  This is similar to `:call` but works with any
+			expression.
+
+			The command can be shortened to `:ev` or `:eva`, but
+			these are hard to recognize and therefore not to be
+			used.
+
 
 :if {expr1}			*:if* *:end* *:endif* *:en* *E171* *E579* *E580*
 :en[dif]		Execute the commands until the next matching ":else"

runtime/doc/testing.txt

@@ -1,4 +1,4 @@
-*testing.txt*	For Vim version 8.1.  Last change: 2019 Jul 28
+*testing.txt*	For Vim version 8.1.  Last change: 2019 Aug 04
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -222,7 +222,11 @@ assert_equal({expected}, {actual} [, {msg}])
 <		Will result in a string to be added to |v:errors|:
 	test.vim line 12: Expected 'foo' but got 'bar' ~
 
-							*assert_equalfile()*
+		Can also be used as a |method|: >
+			mylist->assert_equal([1, 2, 3])
+
+
+<							*assert_equalfile()*
 assert_equalfile({fname-one}, {fname-two})
 		When the files {fname-one} and {fname-two} do not contain
 		exactly the same text an error message is added to |v:errors|.
@@ -294,7 +298,10 @@ assert_notequal({expected}, {actual} [, {msg}])
 		|v:errors| when {expected} and {actual} are equal.
 		Also see |assert-return|.
 
-							*assert_notmatch()*
+		Can also be used as a |method|: >
+			mylist->assert_notequal([1, 2, 3])
+
+<							*assert_notmatch()*
 assert_notmatch({pattern}, {actual} [, {msg}])
 		The opposite of `assert_match()`: add an error message to
 		|v:errors| when {pattern} matches {actual}.

src/ex_cmdidxs.h

@@ -10,27 +10,27 @@ static const unsigned short cmdidxs1[26] =
   /* c */ 42,
   /* d */ 108,
   /* e */ 130,
-  /* f */ 150,
+  /* f */ 151,
-  /* g */ 166,
+  /* g */ 167,
-  /* h */ 172,
+  /* h */ 173,
-  /* i */ 181,
+  /* i */ 182,
-  /* j */ 199,
+  /* j */ 200,
-  /* k */ 201,
+  /* k */ 202,
-  /* l */ 206,
+  /* l */ 207,
-  /* m */ 268,
+  /* m */ 269,
-  /* n */ 286,
+  /* n */ 287,
-  /* o */ 306,
+  /* o */ 307,
-  /* p */ 318,
+  /* p */ 319,
-  /* q */ 357,
+  /* q */ 358,
-  /* r */ 360,
+  /* r */ 361,
-  /* s */ 380,
+  /* s */ 381,
-  /* t */ 448,
+  /* t */ 449,
-  /* u */ 493,
+  /* u */ 494,
-  /* v */ 504,
+  /* v */ 505,
-  /* w */ 522,
+  /* w */ 523,
-  /* x */ 536,
+  /* x */ 537,
-  /* y */ 546,
+  /* y */ 547,
-  /* z */ 547
+  /* z */ 548
 };
 
 /*
@@ -45,7 +45,7 @@ static const unsigned char cmdidxs2[26][26] =
   /* b */ {  2,  0,  0,  4,  5,  7,  0,  0,  0,  0,  0,  8,  9, 10, 11, 12,  0, 13,  0,  0,  0,  0, 22,  0,  0,  0 },
   /* c */ {  3, 12, 16, 18, 20, 22, 25,  0,  0,  0,  0, 33, 37, 40, 46, 56, 58, 59, 60,  0, 62,  0, 65,  0,  0,  0 },
   /* d */ {  0,  0,  0,  0,  0,  0,  0,  0,  6, 15,  0, 16,  0,  0, 17,  0,  0, 19, 20,  0,  0,  0,  0,  0,  0,  0 },
-  /* e */ {  1,  0,  2,  0,  0,  0,  0,  0,  0,  0,  0,  7,  9, 10,  0,  0,  0,  0,  0,  0,  0,  0,  0, 16,  0,  0 },
+  /* e */ {  1,  0,  2,  0,  0,  0,  0,  0,  0,  0,  0,  7,  9, 10,  0,  0,  0,  0,  0,  0,  0, 16,  0, 17,  0,  0 },
   /* f */ {  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  9,  0,  0,  0,  0,  0, 15,  0,  0,  0,  0,  0 },
   /* g */ {  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  1,  0,  0,  2,  0,  0,  4,  5,  0,  0,  0,  0 },
   /* h */ {  5,  0,  0,  0,  0,  0,  0,  0,  6,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0 },
@@ -69,4 +69,4 @@ static const unsigned char cmdidxs2[26][26] =
   /* z */ {  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0 }
 };
 
-static const int command_count = 560;
+static const int command_count = 561;

src/ex_cmds.h

@@ -544,6 +544,9 @@ EXCMD(CMD_endwhile,	"endwhile",	ex_endwhile,
 EXCMD(CMD_enew,		"enew",		ex_edit,
 	EX_BANG|EX_TRLBAR,
 	ADDR_NONE),
+EXCMD(CMD_eval,		"eval",		ex_eval,
+	EX_EXTRA|EX_NOTRLCOM|EX_SBOXOK|EX_CMDWIN,
+	ADDR_NONE),
 EXCMD(CMD_ex,		"ex",		ex_edit,
 	EX_BANG|EX_FILE1|EX_CMDARG|EX_ARGOPT|EX_TRLBAR,
 	ADDR_NONE),

src/ex_eval.c

@@ -870,6 +870,18 @@ report_discard_pending(int pending, void *value)
 }
 
 
+/*
+ * ":eval".
+ */
+    void
+ex_eval(exarg_T *eap)
+{
+    typval_T	tv;
+
+    if (eval0(eap->arg, &tv, &eap->nextcmd, !eap->skip) == OK)
+	clear_tv(&tv);
+}
+
 /*
  * ":if".
  */

src/proto/ex_eval.pro

@@ -12,6 +12,7 @@ void discard_current_exception(void);
 void report_make_pending(int pending, void *value);
 void report_resume_pending(int pending, void *value);
 void report_discard_pending(int pending, void *value);
+void ex_eval(exarg_T *eap);
 void ex_if(exarg_T *eap);
 void ex_endif(exarg_T *eap);
 void ex_else(exarg_T *eap);

src/testdir/test_method.vim

@@ -3,18 +3,23 @@
 func Test_list()
   let l = [1, 2, 3]
   call assert_equal([1, 2, 3, 4], [1, 2, 3]->add(4))
+  eval l->assert_equal(l)
+  eval l->assert_equal(l, 'wrong')
+  eval l->assert_notequal([3, 2, 1])
+  eval l->assert_notequal([3, 2, 1], 'wrong')
   call assert_equal(l, l->copy())
   call assert_equal(1, l->count(2))
   call assert_false(l->empty())
   call assert_true([]->empty())
+  call assert_equal(579, ['123', '+', '456']->join()->eval())
   call assert_equal([1, 2, 3, 4, 5], [1, 2, 3]->extend([4, 5]))
   call assert_equal([1, 3], [1, 2, 3]->filter('v:val != 2'))
   call assert_equal(2, l->get(1))
   call assert_equal(1, l->index(2))
   call assert_equal([0, 1, 2, 3], [1, 2, 3]->insert(0))
-  call assert_fails('let x = l->items()', 'E715:')
+  call assert_fails('eval l->items()', 'E715:')
   call assert_equal('1 2 3', l->join())
-  call assert_fails('let x = l->keys()', 'E715:')
+  call assert_fails('eval l->keys()', 'E715:')
   call assert_equal(3, l->len())
   call assert_equal([2, 3, 4], [1, 2, 3]->map('v:val + 1'))
   call assert_equal(3, l->max())
@@ -26,7 +31,7 @@ func Test_list()
   call assert_equal('[1, 2, 3]', l->string())
   call assert_equal(v:t_list, l->type())
   call assert_equal([1, 2, 3], [1, 1, 2, 3, 3]->uniq())
-  call assert_fails('let x = l->values()', 'E715:')
+  call assert_fails('eval l->values()', 'E715:')
 endfunc
 
 func Test_dict()
@@ -59,3 +64,17 @@ func Test_dict()
   call assert_fails('let x = d->uniq()', 'E686:')
   call assert_equal([1, 2, 3], d->values())
 endfunc
+
+func Test_append()
+  new
+  eval ['one', 'two', 'three']->append(1)
+  call assert_equal(['', 'one', 'two', 'three'], getline(1, '$'))
+
+  %del
+  let bnr = bufnr('')
+  wincmd w
+  eval ['one', 'two', 'three']->appendbufline(bnr, 1)
+  call assert_equal(['', 'one', 'two', 'three'], getbufline(bnr, 1, '$'))
+
+  exe 'bwipe! ' .. bnr
+endfunc

src/version.c

@@ -773,6 +773,8 @@ static char *(features[]) =
 
 static int included_patches[] =
 {   /* Add new patch number below this line */
+/**/
+    1807,
 /**/
     1806,
 /**/