Add exists_info() for the definition of a builtin function or v: variable by h-east · Pull Request #21293 · vim/vim · GitHub
Skip to content

Add exists_info() for the definition of a builtin function or v: variable - #21293

Open
h-east wants to merge 8 commits into
vim:masterfrom
h-east:add-exists-info
Open

h-east wants to merge 8 commits into
vim:masterfrom
h-east:add-exists-info

Conversation

@h-east

@h-east h-east commented Sep 12, 2026

Copy link
Copy Markdown
Member
Problem:  There is no way to get the definition of a builtin function
    (the number of arguments, their types, the return type) or of a v:
    variable (its type, whether it is read-only) from Vim script.  A
    language server has to parse the help text for it.
Solution: Add exists_info({expr}) which takes the notation of exists()
    and returns a Dict with the definition: "*funcname" or "?funcname"
    for a builtin function, "v:name" for a predefined Vim variable.
    The other notations are not supported yet and return an empty Dict.

Action list, one commit per notation:

  • *funcname / ?funcname: builtin function; the names of the arguments in "args", and Test_function_arguments() checks the table against the help
  • v:name: predefined Vim variable
  • {opts} second argument: "argtypes" for the return type of a function, "vim9" for the context of an Ex command
  • :cmd: Ex command, builtin and user defined
  • +opt / &opt: option
  • *Funcname: user defined function

Not planned: g:var etc. (the declared type of a Vim9 script variable is not known before the assignment runs, which :source ++dryrun does not), #event (autocmd_get() has it), $ENV.

@h-east
h-east marked this pull request as draft September 12, 2026 19:37
@h-east
h-east marked this pull request as ready for review September 13, 2026 00:13
…able

Problem:  There is no way to get the definition of a builtin function
    (the number of arguments, their types, the return type) or of a v:
    variable (its type, whether it is read-only) from Vim script.  A
    language server has to parse the help text for it.
Solution: Add exists_info({expr}) which takes the notation of exists()
    and returns a Dict with the definition: "*funcname" or "?funcname"
    for a builtin function, "v:name" for a predefined Vim variable.
    The other notations are not supported yet and return an empty Dict.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
h-east and others added 7 commits September 15, 2026 06:39
Problem:  The "returns" item of exists_info() is the type for arguments
    of type "any".  For a builtin function whose return type depends on
    the argument types, like sort() or remove(), the type a :def
    function is compiled with cannot be obtained.
Solution: Add the optional {argtypes} argument, a List of type names for
    the arguments of a function.  "returns" is then computed for
    arguments of those types.  Required arguments that are not given
    are "any".  More types than the maximum number of arguments, a type
    that is not recognized, or {argtypes} with a notation that is not a
    function is an error.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Problem:  exists_info() cannot give the definition of an Ex command: its
    full name, whether it takes a range, a count, a "!" or a register,
    and for a user defined command the completion and the replacement
    text.  Only ":command" lists that, as text.
Solution: Support ":cmd" in exists_info(): a Dict with the attributes in
    the terms of ":command" for a builtin command, a command modifier
    and a user defined command, the latter also with "buffer",
    "complete", "definition", "sid" and "lnum".  An abbreviation gives
    the full name, an ambiguous one an empty Dict.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Problem:  exists_info() cannot give the definition of an option: its
    full name and abbreviation, whether it is a Boolean, a Number or a
    String, whether it is local to a window or a buffer and what its
    default value is.
Solution: Support "+opt" and "&opt" in exists_info(), the latter also
    for a hidden option with an "available" item, like "?funcname" for
    a function that is not implemented.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Problem:  The second argument of exists_info() is the List of argument
    types for a function, there is no room for what another notation
    needs: an Ex command is found differently in Vim9 script, where an
    abbreviation is not accepted and a few commands do not exist, while
    a script that uses the function may inspect a script of the other
    kind.
Solution: Take a Dict {opts} with the "argtypes" item for a function
    and the "vim9" item for an Ex command, like fullcommand() has.  An
    item for another notation is an error.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Problem:  exists_info() only gives the definition of a builtin function.
    For a user defined function the names of the arguments, their types
    and default values, the return type and where it was defined can
    only be read from the output of ":function".
Solution: When "*funcname" is not a builtin function, look for a user
    defined function, like exists() does: "function" or "def" as the
    kind, the arguments with name, type and default value, "varargs",
    "returns", the attributes "abort", "range", "dict" and "closure",
    and "sid" and "lnum".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Problem:  The table of builtin functions has the number and the types of
    the arguments but not their names, so exists_info() cannot report
    them.
Solution: Add the names of the arguments to every entry of the table as
    they are in the help, and report them as the "name" item of each
    Dict in "args".  An argument the help does not name has no "name":
    the second one of getreg(), the list of prop_add_list() and the
    values of printf() after the first.  Two arguments the help names
    the same, as in and(), are numbered.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Problem:  The arguments in the table of builtin functions and their
    signatures in the help can drift apart, and the overview of
    builtin.txt lacks some arguments and has misplaced brackets.
Solution: Document the "name" item of exists_info() and check it in
    Test_exists_info() for cursor(), and(), getreg() and printf().  Add
    Test_function_arguments() to test_function_lists.vim: it reads the
    signatures in the overview of builtin.txt and in the entry of every
    function, found through the tags file, and compares them with
    exists_info(): the required and the maximum number of arguments with
    both, the names of the arguments with the entry, and reports
    unbalanced brackets.  Correct the help where it found the overview
    lacking an argument or a form, the brackets of an optional argument
    misplaced or unbalanced, and instanceof() and printf() without their
    "...".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant