Data Structures | Macros | Functions
vimscript.c File Reference
#include <assert.h>
#include <limits.h>
#include <stdlib.h>
#include "nvim/api/private/converter.h"
#include "nvim/api/private/defs.h"
#include "nvim/api/private/helpers.h"
#include "nvim/api/vimscript.h"
#include "nvim/ascii.h"
#include "nvim/autocmd.h"
#include "nvim/eval.h"
#include "nvim/eval/typval.h"
#include "nvim/eval/userfunc.h"
#include "nvim/ex_cmds2.h"
#include "nvim/ops.h"
#include "nvim/strings.h"
#include "nvim/vim.h"
#include "nvim/viml/parser/expressions.h"
#include "nvim/viml/parser/parser.h"
#include "nvim/window.h"

Data Structures

struct  ExprASTConvStackItem
 

Macros

#define IS_USER_CMDIDX(idx)   ((int)(idx) < 0)
 
#define OBJ_TO_BOOL(var, value, default, varname)
 
#define VALIDATION_ERROR(...)
 

Functions

String nvim_exec (uint64_t channel_id, String src, Boolean output, Error *err) FUNC_API_SINCE(7)
 
void nvim_command (String command, Error *err) FUNC_API_SINCE(1)
 
Object nvim_eval (String expr, Error *err) FUNC_API_SINCE(1)
 
Object nvim_call_function (String fn, Array args, Error *err) FUNC_API_SINCE(1)
 
Object nvim_call_dict_function (Object dict, String fn, Array args, Error *err) FUNC_API_SINCE(4)
 
Dictionary nvim_parse_expression (String expr, String flags, Boolean highlight, Error *err) FUNC_API_SINCE(4) FUNC_API_FAST
 
Dictionary nvim_parse_cmd (String str, Dictionary opts, Error *err) FUNC_API_SINCE(10) FUNC_API_FAST
 
String nvim_cmd (uint64_t channel_id, Dict(cmd) *cmd, Dict(cmd_opts) *opts, Error *err) FUNC_API_SINCE(10)
 

Macro Definition Documentation

◆ IS_USER_CMDIDX

#define IS_USER_CMDIDX (   idx)    ((int)(idx) < 0)

◆ OBJ_TO_BOOL

#define OBJ_TO_BOOL (   var,
  value,
  default,
  varname 
)
Value:
do { \
var = api_object_to_bool(value, varname, default, err); \
if (ERROR_SET(err)) { \
goto end; \
} \
} while (0)

◆ VALIDATION_ERROR

#define VALIDATION_ERROR (   ...)
Value:
do { \
api_set_error(err, kErrorTypeValidation, __VA_ARGS__); \
goto end; \
} while (0)

Function Documentation

◆ nvim_call_dict_function()

Object nvim_call_dict_function ( Object  dict,
String  fn,
Array  args,
Error err 
)

Calls a VimL |Dictionary-function| with the given arguments.

On execution error: fails with VimL error, updates v:errmsg.

Parameters
dictDictionary, or String evaluating to a VimL |self| dict
fnName of the function defined on the VimL dict
argsFunction arguments packed in an Array
[out]errError details, if any
Returns
Result of the function call

◆ nvim_call_function()

Object nvim_call_function ( String  fn,
Array  args,
Error err 
)

Calls a VimL function with the given arguments.

On execution error: fails with VimL error, updates v:errmsg.

Parameters
fnFunction to call
argsFunction arguments packed in an Array
[out]errError details, if any
Returns
Result of the function call

◆ nvim_cmd()

String nvim_cmd ( uint64_t  channel_id,
Dict(cmd) *  cmd,
Dict(cmd_opts) *  opts,
Error err 
)

Executes an Ex command.

Unlike |nvim_command()| this command takes a structured Dictionary instead of a String. This allows for easier construction and manipulation of an Ex command. This also allows for things such as having spaces inside a command argument, expanding filenames in a command that otherwise doesn't expand filenames, etc.

On execution error: fails with VimL error, updates v:errmsg.

See also
|nvim_exec()|
|nvim_command()|
Parameters
cmdCommand to execute. Must be a Dictionary that can contain the same values as the return value of |nvim_parse_cmd()| except "addr", "nargs" and "nextcmd" which are ignored if provided. All values except for "cmd" are optional.
optsOptional parameters.
  • output: (boolean, default false) Whether to return command output.
[out]errError details, if any.
Returns
Command output (non-error, non-shell |:!|) if output is true, else empty string.

◆ nvim_command()

void nvim_command ( String  command,
Error err 
)

Executes an Ex command.

On execution error: fails with VimL error, updates v:errmsg.

Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple lines of Vim script or an Ex command directly, use |nvim_exec()|. To construct an Ex command using a structured format and then execute it, use |nvim_cmd()|. To modify an Ex command before evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|.

Parameters
commandEx command string
[out]errError details (Vim error), if any

◆ nvim_eval()

Object nvim_eval ( String  expr,
Error err 
)

Evaluates a VimL |expression|. Dictionaries and Lists are recursively expanded.

On execution error: fails with VimL error, updates v:errmsg.

Parameters
exprVimL expression string
[out]errError details, if any
Returns
Evaluation result or expanded object

◆ nvim_exec()

String nvim_exec ( uint64_t  channel_id,
String  src,
Boolean  output,
Error err 
)

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, updates v:errmsg.

See also
|execute()|
|nvim_command()|
|nvim_cmd()|
Parameters
srcVimscript code
outputCapture and return all (non-error, non-shell |:!|) output
[out]errError details (Vim error), if any
Returns
Output (non-error, non-shell |:!|) if output is true, else empty string.

◆ nvim_parse_cmd()

Dictionary nvim_parse_cmd ( String  str,
Dictionary  opts,
Error err 
)

Parse command line.

Doesn't check the validity of command arguments.

Parameters
strCommand line string to parse. Cannot contain "\n".
optsOptional parameters. Reserved for future use.
[out]errError details, if any.
Returns
Dictionary containing command information, with these keys:
  • cmd: (string) Command name.
  • range: (array) Command <range>. Can have 0-2 elements depending on how many items the range contains. Has no elements if command doesn't accept a range or if no range was specified, one element if only a single range item was specified and two elements if both range items were specified.
  • count: (number) Any |<count>| that was supplied to the command. -1 if command cannot take a count.
  • reg: (number) The optional command |<register>|, if specified. Empty string if not specified or if command cannot take a register.
  • bang: (boolean) Whether command contains a |<bang>| (!) modifier.
  • args: (array) Command arguments.
  • addr: (string) Value of |:command-addr|. Uses short name.
  • nargs: (string) Value of |:command-nargs|.
  • nextcmd: (string) Next command if there are multiple commands separated by a |:bar|. Empty if there isn't a next command.
  • magic: (dictionary) Which characters have special meaning in the command arguments.
    • file: (boolean) The command expands filenames. Which means characters such as "%", "#" and wildcards are expanded.
    • bar: (boolean) The "|" character is treated as a command separator and the double quote character (") is treated as the start of a comment.
  • mods: (dictionary) |:command-modifiers|.
    • silent: (boolean) |:silent|.
    • emsg_silent: (boolean) |:silent!|.
    • sandbox: (boolean) |:sandbox|.
    • noautocmd: (boolean) |:noautocmd|.
    • browse: (boolean) |:browse|.
    • confirm: (boolean) |:confirm|.
    • hide: (boolean) |:hide|.
    • keepalt: (boolean) |:keepalt|.
    • keepjumps: (boolean) |:keepjumps|.
    • keepmarks: (boolean) |:keepmarks|.
    • keeppatterns: (boolean) |:keeppatterns|.
    • lockmarks: (boolean) |:lockmarks|.
    • noswapfile: (boolean) |:noswapfile|.
    • tab: (integer) |:tab|.
    • verbose: (integer) |:verbose|. -1 when omitted.
    • vertical: (boolean) |:vertical|.
    • split: (string) Split modifier string, is an empty string when there's no split modifier. If there is a split modifier it can be one of:
      • "aboveleft": |:aboveleft|.
      • "belowright": |:belowright|.
      • "topleft": |:topleft|.
      • "botright": |:botright|.

◆ nvim_parse_expression()

Dictionary nvim_parse_expression ( String  expr,
String  flags,
Boolean  highlight,
Error err 
)

Parse a VimL expression.

Parameters
[in]exprExpression to parse. Always treated as a single line.
[in]flagsFlags:
  • "m" if multiple expressions in a row are allowed (only the first one will be parsed),
  • "E" if EOC tokens are not allowed (determines whether they will stop parsing process or be recognized as an operator/space, though also yielding an error).
  • "l" when needing to start parsing with lvalues for ":let" or ":for". Common flag sets:
  • "m" to parse like for ":echo".
  • "E" to parse like for "<C-r>=".
  • empty string for ":call".
  • "lm" to parse for ":let".
[in]highlightIf true, return value will also include "highlight" key containing array of 4-tuples (arrays) (Integer, Integer, Integer, String), where first three numbers define the highlighted region and represent line, starting column and ending column (latter exclusive: one should highlight region [start_col, end_col)).
Returns
  • AST: top-level dictionary with these keys:
    • "error": Dictionary with error, present only if parser saw some error. Contains the following keys:
      • "message": String, error message in printf format, translated. Must contain exactly one "%.*s".
      • "arg": String, error message argument.
    • "len": Amount of bytes successfully parsed. With flags equal to "" that should be equal to the length of expr string. (“Successfully parsed” here means “participated in AST creation”, not “till the first error”.)
    • "ast": AST, either nil or a dictionary with these keys:
      • "type": node type, one of the value names from ExprASTNodeType stringified without "kExprNode" prefix.
      • "start": a pair [line, column] describing where node is "started" where "line" is always 0 (will not be 0 if you will be using nvim_parse_viml() on e.g. ":let", but that is not present yet). Both elements are Integers.
      • "len": “length” of the node. This and "start" are there for debugging purposes primary (debugging parser and providing debug information).
      • "children": a list of nodes described in top/"ast". There always is zero, one or two children, key will not be present if node has no children. Maximum number of children may be found in node_maxchildren array.
  • Local values (present only for certain nodes):
    • "scope": a single Integer, specifies scope for "Option" and "PlainIdentifier" nodes. For "Option" it is one of ExprOptScope values, for "PlainIdentifier" it is one of ExprVarScope values.
    • "ident": identifier (without scope, if any), present for "Option", "PlainIdentifier", "PlainKey" and "Environment" nodes.
    • "name": Integer, register name (one character) or -1. Only present for "Register" nodes.
    • "cmp_type": String, comparison type, one of the value names from ExprComparisonType, stringified without "kExprCmp" prefix. Only present for "Comparison" nodes.
    • "ccs_strategy": String, case comparison strategy, one of the value names from ExprCaseCompareStrategy, stringified without "kCCStrategy" prefix. Only present for "Comparison" nodes.
    • "augmentation": String, augmentation type for "Assignment" nodes. Is either an empty string, "Add", "Subtract" or "Concat" for "=", "+=", "-=" or ".=" respectively.
    • "invert": Boolean, true if result of comparison needs to be inverted. Only present for "Comparison" nodes.
    • "ivalue": Integer, integer value for "Integer" nodes.
    • "fvalue": Float, floating-point value for "Float" nodes.
    • "svalue": String, value for "SingleQuotedString" and "DoubleQuotedString" nodes.
Parameters
[out]errError details, if any
api_object_to_bool
bool api_object_to_bool(Object obj, const char *what, bool nil_value, Error *err)
Definition: helpers.c:1291
kErrorTypeValidation
@ kErrorTypeValidation
Definition: defs.h:29
ERROR_SET
#define ERROR_SET(e)
Definition: defs.h:17
end
const char_u *const end
Definition: keycodes.c:627