Skip to content
Permalink
Browse files

Merge #11500 from justinmk/api-deprecate

API: rename nvim_execute_lua, deprecate nvim_command_output
  • Loading branch information
justinmk committed Dec 3, 2019
2 parents 22b52dd + a3b6c2a commit b1e4ec1c2a08981683b2355715a421c0bfb64644
@@ -479,6 +479,29 @@ created for extmark changes.
==============================================================================
Global Functions *api-global*

nvim_exec({src}, {output}) *nvim_exec()*
Executes Vimscript (multiline block of Ex-commands), like
anonymous |:source|.

Unlike |nvim_command()| this function supports heredocs,
script-scope (s:), etc.

On execution error: fails with VimL error, does not update
v:errmsg.

Parameters: ~
{src} Vimscript code
{output} Capture and return all (non-error, non-shell
|:!|) output

Return: ~
Output (non-error, non-shell |:!|) if `output` is true,
else empty string.

See also: ~
|execute()|
|nvim_command()|

nvim_command({command}) *nvim_command()*
Executes an ex-command.

@@ -488,6 +511,9 @@ nvim_command({command}) *nvim_command()*
Parameters: ~
{command} Ex-command string

See also: ~
|nvim_exec()|

nvim_get_hl_by_name({name}, {rgb}) *nvim_get_hl_by_name()*
Gets a highlight definition by name.

@@ -609,19 +635,9 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
replace_termcodes
cpoptions

nvim_command_output({command}) *nvim_command_output()*
Executes an ex-command and returns its (non-error) output.
Shell |:!| output is not captured.

On execution error: fails with VimL error, does not update
v:errmsg.

Parameters: ~
{command} Ex-command string

nvim_eval({expr}) *nvim_eval()*
Evaluates a VimL expression (:help expression). Dictionaries
and Lists are recursively expanded.
Evaluates a VimL |expression|. Dictionaries and Lists are
recursively expanded.

On execution error: fails with VimL error, does not update
v:errmsg.
@@ -632,7 +648,7 @@ nvim_eval({expr}) *nvim_eval()*
Return: ~
Evaluation result or expanded object

nvim_execute_lua({code}, {args}) *nvim_execute_lua()*
nvim_exec_lua({code}, {args}) *nvim_exec_lua()*
Execute Lua code. Parameters (if any) are available as `...`
inside the chunk. The chunk can return a value.

@@ -14,6 +14,8 @@ updated.

API ~
*nvim_buf_clear_highlight()* Use |nvim_buf_clear_namespace()| instead.
*nvim_command_output()* Use |nvim_exec()| instead.
*nvim_execute_lua()* Use |nvim_exec_lua()| instead.

Commands ~
*:rv*
@@ -236,10 +236,11 @@ with a {thing} that groups functions under a common concept).

Use existing common {action} names if possible:
add Append to, or insert into, a collection
get Get a thing (or group of things by query)
set Set a thing (or group of things)
del Delete a thing (or group of things)
exec Execute code
get Get a thing (or group of things by query)
list Get all things
set Set a thing (or group of things)

Use consistent names for {thing} in all API functions. E.g. a buffer is called
"buf" everywhere, not "buffer" in some places and "buf" in others.
@@ -76,7 +76,8 @@ void api_vim_free_all_mem(void)
/// Executes Vimscript (multiline block of Ex-commands), like anonymous
/// |:source|.
///
/// Optionally returns (non-error, non-shell |:!|) output.
/// Unlike |nvim_command()| this function supports heredocs, script-scope (s:),
/// etc.
///
/// On execution error: fails with VimL error, does not update v:errmsg.
///
@@ -86,24 +87,21 @@ void api_vim_free_all_mem(void)
/// @param src Vimscript code
/// @param output Capture and return all (non-error, non-shell |:!|) output
/// @param[out] err Error details (Vim error), if any
/// @return Output (non-error, non-shell |:!|) if `output` is true,
/// else empty string.
String nvim_exec(String src, Boolean output, Error *err)
FUNC_API_SINCE(7)
{
if (!output) {
try_start();
do_source_str(src.data, "nvim_exec()");
try_end(err);
return (String)STRING_INIT;
}

const int save_msg_silent = msg_silent;
garray_T *const save_capture_ga = capture_ga;
garray_T capture_local;
ga_init(&capture_local, 1, 80);
if (output) {
ga_init(&capture_local, 1, 80);
capture_ga = &capture_local;
}

try_start();
msg_silent++;
capture_ga = &capture_local;
do_source_str(src.data, "nvim_exec()");
capture_ga = save_capture_ga;
msg_silent = save_msg_silent;
@@ -113,10 +111,10 @@ String nvim_exec(String src, Boolean output, Error *err)
goto theend;
}

if (capture_local.ga_len > 1) {
if (output && capture_local.ga_len > 1) {
String s = (String){
.data = capture_local.ga_data,
.size = (size_t)capture_local.ga_len,
.data = capture_local.ga_data,
.size = (size_t)capture_local.ga_len,
};
// redir usually (except :echon) prepends a newline.
if (s.data[0] == '\n') {
@@ -127,7 +125,9 @@ String nvim_exec(String src, Boolean output, Error *err)
return s; // Caller will free the memory.
}
theend:
ga_clear(&capture_local);
if (output) {
ga_clear(&capture_local);
}
return (String)STRING_INIT;
}

@@ -393,50 +393,13 @@ String nvim_replace_termcodes(String str, Boolean from_part, Boolean do_lt,
return cstr_as_string(ptr);
}

/// Executes an ex-command and returns its (non-error) output.
/// Shell |:!| output is not captured.
///
/// On execution error: fails with VimL error, does not update v:errmsg.
///
/// @param command Ex-command string
/// @param[out] err Error details (Vim error), if any
/// @deprecated
/// @see nvim_exec
String nvim_command_output(String command, Error *err)
FUNC_API_SINCE(1)
FUNC_API_DEPRECATED_SINCE(7)
{
const int save_msg_silent = msg_silent;
garray_T *const save_capture_ga = capture_ga;
garray_T capture_local;
ga_init(&capture_local, 1, 80);

try_start();
msg_silent++;
capture_ga = &capture_local;
do_cmdline_cmd(command.data);
capture_ga = save_capture_ga;
msg_silent = save_msg_silent;
try_end(err);

if (ERROR_SET(err)) {
goto theend;
}

if (capture_local.ga_len > 1) {
String s = (String){
.data = capture_local.ga_data,
.size = (size_t)capture_local.ga_len,
};
// redir usually (except :echon) prepends a newline.
if (s.data[0] == '\n') {
memmove(s.data, s.data + 1, s.size - 1);
s.data[s.size - 1] = '\0';
s.size = s.size - 1;
}
return s; // Caller will free the memory.
}

theend:
ga_clear(&capture_local);
return (String)STRING_INIT;
return nvim_exec(command, true, err);
}

/// Evaluates a VimL |expression|.
@@ -484,6 +447,15 @@ Object nvim_eval(String expr, Error *err)
return rv;
}

/// @deprecated Use nvim_exec_lua() instead.
Object nvim_execute_lua(String code, Array args, Error *err)
FUNC_API_SINCE(3)
FUNC_API_DEPRECATED_SINCE(7)
FUNC_API_REMOTE_ONLY
{
return executor_exec_lua_api(code, args, err);
}

/// Execute Lua code. Parameters (if any) are available as `...` inside the
/// chunk. The chunk can return a value.
///
@@ -496,8 +468,9 @@ Object nvim_eval(String expr, Error *err)
/// or executing the Lua code.
///
/// @return Return value of Lua code if present or NIL.
Object nvim_execute_lua(String code, Array args, Error *err)
FUNC_API_SINCE(3) FUNC_API_REMOTE_ONLY
Object nvim_exec_lua(String code, Array args, Error *err)
FUNC_API_SINCE(7)
FUNC_API_REMOTE_ONLY
{
return executor_exec_lua_api(code, args, err);
}
@@ -1312,8 +1285,8 @@ Boolean nvim_paste(String data, Boolean crlf, Integer phase, Error *err)
Array lines = string_to_array(data, crlf);
ADD(args, ARRAY_OBJ(lines));
ADD(args, INTEGER_OBJ(phase));
rv = nvim_execute_lua(STATIC_CSTR_AS_STRING("return vim.paste(...)"), args,
err);
rv = nvim_exec_lua(STATIC_CSTR_AS_STRING("return vim.paste(...)"), args,
err);
if (ERROR_SET(err)) {
draining = true;
goto theend;
@@ -2447,7 +2420,7 @@ Array nvim_get_proc_children(Integer pid, Error *err)
Array a = ARRAY_DICT_INIT;
ADD(a, INTEGER_OBJ(pid));
String s = cstr_to_string("return vim._os_proc_children(select(1, ...))");
Object o = nvim_execute_lua(s, a, err);
Object o = nvim_exec_lua(s, a, err);
api_free_string(s);
api_free_array(a);
if (o.type == kObjectTypeArray) {
@@ -2493,7 +2466,7 @@ Object nvim_get_proc(Integer pid, Error *err)
Array a = ARRAY_DICT_INIT;
ADD(a, INTEGER_OBJ(pid));
String s = cstr_to_string("return vim._os_proc_info(select(1, ...))");
Object o = nvim_execute_lua(s, a, err);
Object o = nvim_exec_lua(s, a, err);
api_free_string(s);
api_free_array(a);
if (o.type == kObjectTypeArray && o.data.array.size == 0) {
@@ -254,7 +254,7 @@ static inline void ctx_save_funcs(Context *ctx, bool scriptonly)
size_t cmd_len = sizeof("func! ") + STRLEN(name);
char *cmd = xmalloc(cmd_len);
snprintf(cmd, cmd_len, "func! %s", name);
String func_body = nvim_command_output(cstr_as_string(cmd), &err);
String func_body = nvim_exec(cstr_as_string(cmd), true, &err);
xfree(cmd);
if (!ERROR_SET(&err)) {
ADD(ctx->funcs, STRING_OBJ(func_body));
@@ -20527,7 +20527,7 @@ static hashtab_T *get_funccal_local_ht(void)
return &get_funccal()->l_vars.dv_hashtab;
}

/// Find the dict and hashtable used for a variable
/// Finds the dict (g:, l:, s:, …) and hashtable used for a variable.
///
/// @param[in] name Variable name, possibly with scope prefix.
/// @param[in] name_len Variable name length.
@@ -3428,7 +3428,7 @@ char_u *get_scriptname(LastSet last_set, bool *should_free)
last_set.channel_id);
return IObuff;
case SID_STR:
return (char_u *)_(":source (no file)");
return (char_u *)_("anonymous :source");
default:
*should_free = true;
return home_replace_save(NULL,
@@ -296,25 +296,23 @@ int do_cmdline_cmd(const char *cmd)
DOCMD_NOWAIT|DOCMD_KEYTYPED);
}

/*
* do_cmdline(): execute one Ex command line
*
* 1. Execute "cmdline" when it is not NULL.
* If "cmdline" is NULL, or more lines are needed, fgetline() is used.
* 2. Split up in parts separated with '|'.
*
* This function can be called recursively!
*
* flags:
* DOCMD_VERBOSE - The command will be included in the error message.
* DOCMD_NOWAIT - Don't call wait_return() and friends.
* DOCMD_REPEAT - Repeat execution until fgetline() returns NULL.
* DOCMD_KEYTYPED - Don't reset KeyTyped.
* DOCMD_EXCRESET - Reset the exception environment (used for debugging).
* DOCMD_KEEPLINE - Store first typed line (for repeating with ".").
*
* return FAIL if cmdline could not be executed, OK otherwise
*/
/// do_cmdline(): execute one Ex command line
///
/// 1. Execute "cmdline" when it is not NULL.
/// If "cmdline" is NULL, or more lines are needed, fgetline() is used.
/// 2. Split up in parts separated with '|'.
///
/// This function can be called recursively!
///
/// flags:
/// DOCMD_VERBOSE - The command will be included in the error message.
/// DOCMD_NOWAIT - Don't call wait_return() and friends.
/// DOCMD_REPEAT - Repeat execution until fgetline() returns NULL.
/// DOCMD_KEYTYPED - Don't reset KeyTyped.
/// DOCMD_EXCRESET - Reset the exception environment (used for debugging).
/// DOCMD_KEEPLINE - Store first typed line (for repeating with ".").
///
/// @return FAIL if cmdline could not be executed, OK otherwise
int do_cmdline(char_u *cmdline, LineGetter fgetline,
void *cookie, /* argument for fgetline() */
int flags)
@@ -798,9 +798,9 @@ static void typval_exec_lua(const char *lcmd, size_t lcmd_len, const char *name,
}
}

/// Execute lua string
/// Execute Lua string
///
/// Used for nvim_execute_lua().
/// Used for nvim_exec_lua().
///
/// @param[in] str String to execute.
/// @param[in] args array of ... args
@@ -585,13 +585,13 @@ describe('nvim_set_keymap, nvim_del_keymap', function()
end)

it('can set <expr> mappings whose RHS change dynamically', function()
meths.command_output([[
meths.exec([[
function! FlipFlop() abort
if !exists('g:flip') | let g:flip = 0 | endif
let g:flip = !g:flip
return g:flip
endfunction
]])
]], true)
eq(1, meths.call_function('FlipFlop', {}))
eq(0, meths.call_function('FlipFlop', {}))
eq(1, meths.call_function('FlipFlop', {}))

0 comments on commit b1e4ec1

Please sign in to comment.
You can’t perform that action at this time.