Merge #6945 from justinmk/cpoptions

8 files changed, 124 insertions, 65 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ebc2a40561..7c6b8a3c1a 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -165,7 +165,16 @@ nvim_input({keys})                                              *nvim_input()*
 
                                                     *nvim_replace_termcodes()*
 nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
-                Replaces any terminal codes with the internal representation
+                Replaces terminal codes and |keycodes| (<CR>, <Esc>, ...) in a
+                string with the internal representation.
+
+                Parameters:~
+                    {str}        String to be converted.
+                    {from_part}  Legacy Vim parameter. Usually true.
+                    {do_lt}      Also translate <lt>. Does nothing if
+                                 `special` is false.
+                    {special}    Replace |keycodes|, e.g. <CR> becomes a "\n"
+                                 char.
 
 nvim_command_output({str})                             *nvim_command_output()*
                 TODO: Documentation
@@ -182,8 +191,10 @@ nvim_eval({expr})                                                *nvim_eval()*
                     Evaluation result or expanded object
 
 nvim_call_function({fname}, {args})                     *nvim_call_function()*
-                Calls a VimL function with the given arguments. On VimL error:
-                Returns a generic error; v:errmsg is not updated.
+                Calls a VimL function with the given arguments
+
+                On VimL error: Returns a generic error; v:errmsg is not
+                updated.
 
                 Parameters:~
                     {fname}  Function to call
@@ -192,6 +203,23 @@ nvim_call_function({fname}, {args})                     *nvim_call_function()*
                 Return:~
                     Result of the function call
 
+nvim_execute_lua({code}, {args})                          *nvim_execute_lua()*
+                Execute lua code. Parameters might be passed, they are
+                available inside the chunk as `...`. The chunk can return a
+                value.
+
+                To evaluate an expression, it must be prefixed with "return ".
+                For instance, to call a lua function with arguments sent in
+                and get its return value back, use the code "return
+                my_function(...)".
+
+                Parameters:~
+                    {code}  lua code to execute
+                    {args}  Arguments to the code
+
+                Return:~
+                    Return value of lua code if present or NIL.
+
 nvim_strwidth({str})                                         *nvim_strwidth()*
                 Calculates the number of display cells occupied by `text`.
                 <Tab> counts as one cell.
@@ -382,6 +410,17 @@ nvim_get_mode()                                              *nvim_get_mode()*
                 Return:~
                     Dictionary { "mode": String, "blocking": Boolean }
 
+nvim_get_keymap({mode})                                    *nvim_get_keymap()*
+                Get a list of dictionaries describing global (i.e. non-buffer)
+                mappings Note that the "buffer" key will be 0 to represent
+                false.
+
+                Parameters:~
+                    {mode}  The abbreviation for the mode
+
+                Return:~
+                    An array of maparg() like dictionaries describing mappings
+
 nvim_get_api_info()                                      *nvim_get_api_info()*
                 TODO: Documentation
 
@@ -414,6 +453,54 @@ nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                     error ocurred, the values from all preceding calls will
                     still be returned.
 
+nvim__id({obj})                                                   *nvim__id()*
+                Returns object given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {obj}  Object to return.
+
+                Return:~
+                    its argument.
+
+nvim__id_array({arr})                                       *nvim__id_array()*
+                Returns array given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {arr}  Array to return.
+
+                Return:~
+                    its argument.
+
+nvim__id_dictionary({dct})                             *nvim__id_dictionary()*
+                Returns dictionary given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {dct}  Dictionary to return.
+
+                Return:~
+                    its argument.
+
+nvim__id_float({flt})                                       *nvim__id_float()*
+                Returns floating-point value given as argument
+
+                This API function is used for testing. One should not rely on
+                its presence in plugins.
+
+                Parameters:~
+                    {flt}  Value to return.
+
+                Return:~
+                    its argument.
+
 
 ==============================================================================
 Buffer Functions                                                  *api-buffer*
@@ -492,6 +579,18 @@ nvim_buf_get_changedtick({buffer})                *nvim_buf_get_changedtick()*
                 Return:~
                     b:changedtickvalue.
 
+nvim_buf_get_keymap({buffer}, {mode})                  *nvim_buf_get_keymap()*
+                Get a list of dictionaries describing buffer-local mappings
+                Note that the buffer key in the dictionary will represent the
+                buffer handle where the mapping is present
+
+                Parameters:~
+                    {mode}       The abbreviation for the mode
+                    {buffer_id}  Buffer handle
+
+                Return:~
+                    An array of maparg() like dictionaries describing mappings
+
 nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
                 Sets a buffer-scoped (b:) variable
 
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 26cd5b24cc..b3e2f7a92f 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -39,10 +39,16 @@ Functions ~
 *highlightID()*		Obsolete name for |hlID()|.
 *last_buffer_nr()*	Obsolete name for bufnr("$").
 
+Modifiers ~
+*:menu-<special>*
+*:menu-special*		<> notation is always enabled. |cpo-<|
+*:map-<special>*
+*:map-special*		<> notation is always enabled. |cpo-<|
+
 Options ~
 *'fe'*			'fenc'+'enc' before Vim 6.0; no longer used.
 *'langnoremap'*		Deprecated alias to 'nolangremap'.
 *'vi'*
 *'viminfo'*		Deprecated alias to 'shada' option.
 
- vim:tw=78:ts=8:ft=help:norl:
+ vim:noet:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 0bd3a40a7c..b66a60c860 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -490,9 +490,6 @@ expression register: >
 
    :amenu Insert.foobar   "='foobar'<CR>P
 
-Note that the '<' and 'k' flags in 'cpoptions' also apply here (when
-included they make the <> form and raw key codes not being recognized).
-
 Note that <Esc> in Cmdline mode executes the command, like in a mapping.  This
 is Vi compatible.  Use CTRL-C to quit Cmdline mode.
 
@@ -504,21 +501,13 @@ The ":set ic" will not be echoed when using this menu.  Messages from the
 executed command are still given though.  To shut them up too, add a ":silent"
 in the executed command: >
 	:menu <silent> Search.Header :exe ":silent normal /Header\r"<CR>
-"<silent>" may also appear just after "<special>" or "<script>".
-
-					*:menu-<special>* *:menu-special*
-Define a menu with <> notation for special keys, even though the "<" flag
-may appear in 'cpoptions'.  This is useful if the side effect of setting
-'cpoptions' is not desired.  Example: >
-	:menu <special> Search.Header /Header<CR>
-"<special>" must appear as the very first argument to the ":menu" command or
-just after "<silent>" or "<script>".
+"<silent>" may also appear just after "<script>".
 
 						*:menu-<script>* *:menu-script*
 The "to" part of the menu will be inspected for mappings.  If you don't want
 this, use the ":noremenu" command (or the similar one for a specific mode).
 If you do want to use script-local mappings, add "<script>" as the very first
-argument to the ":menu" command or just after "<silent>" or "<special>".
+argument to the ":menu" command or just after "<silent>".
 
 							*menu-priority*
 You can give a priority to a menu.  Menus with a higher priority go more to
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index f5b0233e6c..bfcf621cb8 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -149,7 +149,7 @@ type "a", then "bar" will get inserted.
 
 1.2 SPECIAL ARGUMENTS					*:map-arguments*
 
-"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and
+"<buffer>", "<nowait>", "<silent>", "<script>", "<expr>" and
 "<unique>" can be used in any order.  They must appear right after the
 command, before any other arguments.
 
@@ -189,12 +189,6 @@ Prompts will still be given, e.g., for inputdialog().
 Using "<silent>" for an abbreviation is possible, but will cause redrawing of
 the command line to fail.
 
-						*:map-<special>* *:map-special*
-Define a mapping with <> notation for special keys, even though the "<" flag
-may appear in 'cpoptions'.  This is useful if the side effect of setting
-'cpoptions' is not desired.  Example: >
-	:map <special> <F12> /Header<CR>
-<
 						*:map-<script>* *:map-script*
 If the first argument to one of these commands is "<script>" and it is used to
 define a new mapping or abbreviation, the mapping will only remap characters
@@ -444,16 +438,14 @@ There are two ways to map a special key:
    starts with <Esc>.  To enter a mapping like this you type ":map " and then
    you have to type CTRL-V before hitting the function key.  Note that when
    the key code for the key is in the |terminfo| entry, it will automatically
-   be translated into the internal code and become the second way of mapping
-   (unless the 'k' flag is included in 'cpoptions').
+   be translated into the internal code and become the second way of mapping.
 2. The second method is to use the internal code for the function key.  To
    enter such a mapping type CTRL-K and then hit the function key, or use
    the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc.
    (see table of keys |key-notation|, all keys from <Up> can be used).  The
    first ten function keys can be defined in two ways: Just the number, like
    "#2", and with "<F>", like "<F2>".  Both stand for function key 2.  "#0"
-   refers to function key 10.  The <> form cannot be used when 'cpoptions'
-   includes the '<' flag.
+   refers to function key 10.
 
 DETAIL: Vim first checks if a sequence from the keyboard is mapped.  If it
 isn't the terminal key codes are tried.  If a terminal code is found it is
@@ -571,9 +563,9 @@ Since the '|' character is used to separate a map command from the next
 command, you will have to do something special to include  a '|' in {rhs}.
 There are three methods:
    use	     works when			   example	~
-   <Bar>     '<' is not in 'cpoptions'	   :map _l :!ls <Bar> more^M
+   <Bar>     always			   :map _l :!ls <Bar> more^M
    \|	     'b' is not in 'cpoptions'	   :map _l :!ls \| more^M
-   ^V|	     always, in Vim and Vi	   :map _l :!ls ^V| more^M
+   ^V|	     always			   :map _l :!ls ^V| more^M
 
 (here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you
 cannot use the <> notation "<C-V>" here).
@@ -628,8 +620,7 @@ out about, ^D is CTRL-D).
 
 1.8 EXAMPLES						*map-examples*
 
-A few examples (given as you type them, for "<CR>" you type four characters;
-the '<' flag must not be present in 'cpoptions' for this to work). >
+A few examples (as you type them: for "<CR>" you type four characters). >
 
    :map <F3>  o#include
    :map <M-g> /foo<CR>cwbar<Esc>
@@ -881,7 +872,6 @@ character is mostly ignored otherwise.
 
 It is possible to move the cursor after an abbreviation: >
    :iab if if ()<Left>
-This does not work if 'cpoptions' includes the '<' flag. |<>|
 
 You can even do more complicated things.  For example, to consume the space
 typed after an abbreviation: >
@@ -1029,8 +1019,7 @@ functions used in one script use the same name as in other scripts.  To avoid
 this, they can be made local to the script.
 
 						*<SID>* *<SNR>* *E81*
-The string "<SID>" can be used in a mapping or menu.  This requires that the
-'<' flag is not present in 'cpoptions'.
+The string "<SID>" can be used in a mapping or menu.
    When executing the map command, Vim will replace "<SID>" with the special
 key code <SNR>, followed by a number that's unique for the script, and an
 underscore.  Example: >
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index ca126f5a79..dc968cd666 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -1568,7 +1568,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 			results in X being mapped to:
 				'B' included:	"\^["	 (^[ is a real <Esc>)
 				'B' excluded:	"<Esc>"  (5 characters)
-				('<' excluded in both cases)
 								*cpo-c*
 		c	Searching continues at the end of any match at the
 			cursor position, but not further than the start of the
@@ -1618,15 +1617,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 		J	A |sentence| has to be followed by two spaces after
 			the '.', '!' or '?'.  A <Tab> is not recognized as
 			white space.
-								*cpo-k*
-		k	Disable the recognition of raw key codes in
-			mappings, abbreviations, and the "to" part of menu
-			commands.  For example, if <Key> sends ^[OA (where ^[
-			is <Esc>), the command ":map X ^[OA" results in X
-			being mapped to:
-				'k' included:	"^[OA"	 (3 characters)
-				'k' excluded:	"<Key>"  (one key code)
-			Also see the '<' flag below.
 								*cpo-K*
 		K	Don't wait for a key code to complete when it is
 			halfway through a mapping.  This breaks mapping
@@ -1760,14 +1750,6 @@ A jump table for the options with a short description can be found at |Q_op|.
 		+	When included, a ":write file" command will reset the
 			'modified' flag of the buffer, even though the buffer
 			itself may still be different from its file.
-								*cpo-<*
-		<	Disable the recognition of special key codes in |<>|
-			form in mappings, abbreviations, and the "to" part of
-			menu commands.  For example, the command
-			":map X <Tab>" results in X being mapped to:
-				'<' included:	"<Tab>"  (5 characters)
-				'<' excluded:	"^I"	 (^I is a real <Tab>)
-			Also see the 'k' flag above.
 								*cpo->*
 		>	When appending to a register, put a line break before
 			the appended text.
diff --git a/runtime/doc/tips.txt b/runtime/doc/tips.txt
index 9b34cd7599..0ac9a8303d 100644
--- a/runtime/doc/tips.txt
+++ b/runtime/doc/tips.txt
@@ -113,7 +113,6 @@ screen, you can use CTRL-X CTRL-E and CTRL-X CTRL-Y to scroll the screen.
 To make this easier, you could use these mappings: >
 	:inoremap <C-E> <C-X><C-E>
 	:inoremap <C-Y> <C-X><C-Y>
-(Type this literally, make sure the '<' flag is not in 'cpoptions').
 You then lose the ability to copy text from the line above/below the cursor
 |i_CTRL-E|.
 
@@ -129,8 +128,6 @@ If you like the scrolling to go a bit smoother, you can use these mappings: >
 	:map <C-U> <C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y><C-Y>
 	:map <C-D> <C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E><C-E>
 
-(Type this literally, make sure the '<' flag is not in 'cpoptions').
-
 ==============================================================================
 Correcting common typing mistakes			*type-mistakes*
 
@@ -282,9 +279,7 @@ For Emacs-style editing on the command-line: >
 	:cnoremap <Esc><C-B>	<S-Left>
 	" forward one word
 	:cnoremap <Esc><C-F>	<S-Right>
-
-NOTE: This requires that the '<' flag is excluded from 'cpoptions'. |<>|
-
+<
 							*format-bullet-list*
 This mapping will format any bullet list.  It requires that there is an empty
 line above and below each list entry.  The expression commands are used to
@@ -300,8 +295,7 @@ be able to give comments to the parts of the mapping. >
 	:execute m			      |" define the mapping
 
 (<> notation |<>|.  Note that this is all typed literally.  ^W is "^" "W", not
-CTRL-W.  You can copy/paste this into Vim if '<' is not included in
-'cpoptions'.)
+CTRL-W.)
 
 Note that the last comment starts with |", because the ":execute" command
 doesn't accept a comment directly.
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index ca07e613ed..d906b874f0 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -332,7 +332,7 @@ Test functions:
 
 Other options:
   'antialias'
-  'cpoptions' ("g", "w", "H", "*", "-", "j", and all POSIX flags were removed)
+  'cpoptions' (g j k H w < * - and all POSIX flags were removed)
   'encoding' ("utf-8" is always used)
   'esckeys'
   'guioptions' "t" flag was removed
diff --git a/runtime/doc/visual.txt b/runtime/doc/visual.txt
index e9f5bf91f8..cf804444e5 100644
--- a/runtime/doc/visual.txt
+++ b/runtime/doc/visual.txt
@@ -271,7 +271,7 @@ mode.  For example, if you would like the "/" command not to extend the Visual
 area, but instead take the highlighted text and search for that: >
 	:vmap / y/<C-R>"<CR>
 (In the <> notation |<>|, when typing it you should type it literally; you
-need to remove the 'B' and '<' flags from 'cpoptions'.)
+need to remove the 'B' flag from 'cpoptions'.)
 
 If you want to give a register name using the """ command, do this just before
 typing the operator character: "v{move-around}"xd".
@@ -375,7 +375,7 @@ Here is an example, to replace the selected text with the output of "date": >
 	:vmap _a <Esc>`>a<CR><Esc>`<i<CR><Esc>!!date<CR>kJJ
 
 (In the <> notation |<>|, when typing it you should type it literally; you
-need to remove the 'B' and '<' flags from 'cpoptions')
+need to remove the 'B' flag from 'cpoptions')
 
 What this does is:
 <Esc>		stop Visual mode
@@ -392,7 +392,7 @@ selected text: >
 	:vmap X y/<C-R>"<CR>
 
 (In the <> notation |<>|, when typing it you should type it literally; you
-need to remove the 'B' and '<' flags from 'cpoptions')
+need to remove the 'B' flag from 'cpoptions')
 
 Note that special characters (like '.' and '*') will cause problems.