patch 8.2.3184: cannot add a digraph with a leading spacev8.2.3184

Problem:    Cannot add a digraph with a leading space.  It is not easy to list
            existing digraphs.
Solution:   Add setdigraph(), setdigraphlist(), getdigraph() and
            getdigraphlist(). (closes #8580)

3 files changed, 114 insertions, 0 deletions

diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt
index 79c7cf042d..9715a88469 100644
--- a/runtime/doc/digraph.txt
+++ b/runtime/doc/digraph.txt
@@ -38,6 +38,9 @@ An alternative is using the 'keymap' option.
 <			Avoid defining a digraph with '_' (underscore) as the
 			first character, it has a special meaning in the
 			future.
+			NOTE: This command cannot add a digraph that starts
+			with a white space.  If you want to add such digraph,
+			you can use |setdigraph()| instead.
 
 Vim is normally compiled with the |+digraphs| feature.  If the feature is
 disabled, the ":digraph" command will display an error message.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index e5f9b46517..f4ab159a78 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2620,6 +2620,8 @@ getcompletion({pat}, {type} [, {filtered}])
 getcurpos([{winnr}])		List	position of the cursor
 getcursorcharpos([{winnr}])	List	character position of the cursor
 getcwd([{winnr} [, {tabnr}]])	String	get the current working directory
+getdigraph({chars})		String	get the digraph of {chars}
+getdigraphlist([{listall}])	List	get all |digraph|s
 getenv({name})			String	return environment variable
 getfontname([{name}])		String	name of font being used
 getfperm({fname})		String	file permissions of file {fname}
@@ -2886,6 +2888,8 @@ setcharpos({expr}, {list})	Number	set the {expr} position to {list}
 setcharsearch({dict})		Dict	set character search from {dict}
 setcmdpos({pos})		Number	set cursor position in command-line
 setcursorcharpos({list})	Number	move cursor to position in {list}
+setdigraph({chars}, {digraph})	Boolean  register |digraph|
+setdigraphlist({digraphlist})	Boolean  register multiple |digraph|s
 setenv({name}, {val})		none	set environment variable
 setfperm({fname}, {mode})	Number	set {fname} file permissions to {mode}
 setline({lnum}, {line})		Number	set line {lnum} to {line}
@@ -5572,6 +5576,61 @@ getcwd([{winnr} [, {tabnr}]])
 <		Can also be used as a |method|: >
 			GetWinnr()->getcwd()
 <
+					      *getdigraph()* *E1214*
+getdigraph({chars})
+		Return the digraph of {chars}.  This should be a string with
+		exactly two characters.  If {chars} are not just two
+		characters, or the digraph of {chars} does not exist, an error
+		is given and an empty string is returned.
+
+		The character will be converted from Unicode to 'encoding'
+		when needed.  This does require the conversion to be
+		available, it might fail.
+
+		Also see |getdigraphlist()|.
+
+		Examples: >
+		" Get a built-in digraph
+		:echo getdigraph('00')		" Returns '∞'
+
+		" Get a user-defined digraph
+		:call setdigraph('aa', 'あ')
+		:echo getdigraph('aa')		" Returns 'あ'
+<
+		Can also be used as a |method|: >
+			GetChars()->getdigraph()
+<
+		This function works only when compiled with the |+digraphs|
+		feature.  If this feature is disabled, this function will
+		display an error message.
+
+
+getdigraphlist([{listall}])			*getdigraphlist()*
+		Return a list of digraphs.  If the {listall} argument is given
+		and it is TRUE, return all digraphs, including the default
+		digraphs.  Otherwise, return only user-defined digraphs.
+
+		The characters will be converted from Unicode to 'encoding'
+		when needed.  This does require the conservation to be
+		available, it might fail.
+
+		Also see |getdigraph()|.
+
+		Examples: >
+		" Get user-defined digraphs
+		:echo getdigraphlist()
+
+		" Get all the digraphs, including default digraphs
+		:echo digraphlist(1)
+<
+		Can also be used as a |method|: >
+			GetNumber()->getdigraphlist()
+<
+		This function works only when compiled with the |+digraphs|
+		feature.  If this feature is disabled, this function will
+		display an error message.
+
+
 getenv({name})						*getenv()*
 		Return the value of environment variable {name}.
 		When the variable does not exist |v:null| is returned.  That
@@ -9490,6 +9549,54 @@ setcursorcharpos({list})
 		Can also be used as a |method|: >
 			GetCursorPos()->setcursorcharpos()
 
+
+setdigraph({chars}, {digraph})		*setdigraph()* *E1205*
+		Add digraph {chars} to the list.  {chars} must be a string
+		with two characters.  {digraph} is a string with one utf-8
+		encoded character. Be careful, composing characters are NOT
+		ignored.  This function is similar to |:digraphs| command, but
+		useful to add digraphs start with a white space.
+
+		The function result is v:true if |digraph| is registered.  If
+		this fails an error message is given and v:false is returned.
+
+		If you want to define multiple digraphs at once, you can use
+		|setdigraphlist()|.
+
+		Example: >
+			call setdigraph('  ', 'あ')
+<
+		Can be used as a |method|: >
+			GetString()->setdigraph('あ')
+<
+		This function works only when compiled with the |+digraphs|
+		feature.  If this feature is disabled, this function will
+		display an error message.
+
+
+setdigraphlist({digraphlist})			*setdigraphlist()*
+		Similar to |setdigraph()| but this function can add multiple
+		digraphs at once.  {digraphlist} is a list composed of lists,
+		where each list contains two strings with {chars} and
+		{digraph} as in |setdigraph()|.
+		Example: >
+		    call setdigraphlist([['aa', 'あ'], ['ii', 'い']])
+<
+		It is similar to the following: >
+		    for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']]
+			  call setdigraph(chars, digraph)
+		    endfor
+<		Except that the function returns after the first error,
+		following digraphs will not be added.
+
+		Can be used as a |method|: >
+		    GetList()->setdigraphlist()
+<
+		This function works only when compiled with the |+digraphs|
+		feature.  If this feature is disabled, this function will
+		display an error message.
+
+
 setenv({name}, {val})						*setenv()*
 		Set environment variable {name} to {val}.
 		When {val} is |v:null| the environment variable is deleted.
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 54e5e2930d..df9ebe639d 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -1000,6 +1000,10 @@ Mappings and Menus:			    *mapping-functions*
 	mapset()		restore a mapping
 	menu_info()		get information about a menu item
 	wildmenumode()		check if the wildmode is active
+	getdigraph()		get |digraph|
+	getdigraphlist()	get all |digraph|s
+	setdigraph()		register |digraph|
+	setdigraphlist()	register multiple |digraph|s
 
 Testing:				    *test-functions*
 	assert_equal()		assert that two expressions values are equal