Merge PR #3603 'Implement dictionary notifications'

1 files changed, 40 insertions, 0 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 5ed2ca6016..7b12d2082f 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1763,6 +1763,8 @@ cursor( {lnum}, {col} [, {off}])
 cursor( {list})			Number	move cursor to position in {list}
 deepcopy( {expr} [, {noref}])	any	make a full copy of {expr}
 delete( {fname})		Number	delete file {fname}
+dictwatcheradd({dict}, {pattern}, {callback})	Start watching a dictionary
+dictwatcherdel({dict}, {pattern}, {callback})	Stop watching a dictionary
 did_filetype()			Number	TRUE if FileType autocommand event used
 diff_filler( {lnum})		Number	diff filler lines about {lnum}
 diff_hlID( {lnum}, {col})	Number	diff highlighting at {lnum}/{col}
@@ -2664,6 +2666,44 @@ delete({fname})							*delete()*
 		To delete a line from the buffer use |:delete|.  Use |:exe|
 		when the line number is in a variable.
 
+dictwatcheradd({dict}, {pattern}, {callback})		      *dictwatcheradd()*
+		Adds a watcher to a dictionary. A dictionary watcher is
+		identified by three components:
+
+		- A dictionary({dict});
+		- A key pattern({pattern}).
+		- A function({callback}).
+
+		After this is called, every change on {dict} and on keys
+		matching {pattern} will result in {callback} being invoked.
+
+		For now {pattern} only accepts very simple patterns that can
+		contain a '*' at the end of the string, in which case it will
+		match every key that begins with the substring before the '*'.
+		That means if '*' is not the last character of {pattern}, only
+		keys that are exactly equal as {pattern} will be matched.
+
+		The {callback} receives three arguments:
+
+		- The dictionary being watched.
+		- The key which changed.
+		- A dictionary containg the new and old values for the key.
+
+		The type of change can be determined by examining the keys
+		present on the third argument:
+
+		- If contains both `old` and `new`, the key was updated.
+		- If it contains only `new`, the key was added.
+		- If it contains only `old`, the key was deleted.
+
+		This function can be used by plugins to implement options with
+		validation and parsing logic.
+
+dictwatcherdel({dict}, {pattern}, {callback})		      *dictwatcherdel()*
+		Removes a watcher added  with |dictwatcheradd()|. All three
+		arguments must match the ones passed to |dictwatcheradd()| in
+		order for the watcher to be successfully deleted.
+
 							*did_filetype()*
 did_filetype()	Returns non-zero when autocommands are being executed and the
 		FileType event has been triggered at least once.  Can be used