From c8223007d0e0a1d5dbcda31f364d1d1baee9d772 Mon Sep 17 00:00:00 2001 From: dundargoc Date: Wed, 13 Dec 2023 11:11:49 +0100 Subject: [PATCH] docs: add code-overview from wiki to src/nvim/README.md --- src/nvim/README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/src/nvim/README.md b/src/nvim/README.md index b484d59cb3..b264c918b6 100644 --- a/src/nvim/README.md +++ b/src/nvim/README.md @@ -392,6 +392,68 @@ modes managed by the `state_enter` loop: - insert mode: `insert_{enter,check,execute}()`(`edit.c`) - terminal mode: `terminal_{enter,execute}()`(`terminal.c`) +## Important variables + +The current mode is stored in `State`. The values it can have are `MODE_NORMAL`, +`MODE_INSERT`, `MODE_CMDLINE`, and a few others. + +The current window is `curwin`. The current buffer is `curbuf`. These point +to structures with the cursor position in the window, option values, the file +name, etc. + +All the global variables are declared in `globals.h`. + +### The main loop + +The main loop is implemented in state_enter. The basic idea is that Vim waits +for the user to type a character and processes it until another character is +needed. Thus there are several places where Vim waits for a character to be +typed. The `vgetc()` function is used for this. It also handles mapping. + +Updating the screen is mostly postponed until a command or a sequence of +commands has finished. The work is done by `update_screen()`, which calls +`win_update()` for every window, which calls `win_line()` for every line. +See the start of [drawscreen.c](drawscreen.c) for more explanations. + +### Command-line mode + +When typing a `:`, `normal_cmd()` will call `getcmdline()` to obtain a line with +an Ex command. `getcmdline()` calls a loop that will handle each typed +character. It returns when hitting `` or `` or some other character that +ends the command line mode. + +### Ex commands + +Ex commands are handled by the function `do_cmdline()`. It does the generic +parsing of the `:` command line and calls `do_one_cmd()` for each separate +command. It also takes care of while loops. + +`do_one_cmd()` parses the range and generic arguments and puts them in the +exarg_t and passes it to the function that handles the command. + +The `:` commands are listed in [ex_cmds.lua](ex_cmds.lua). + +### Normal mode commands + +The Normal mode commands are handled by the `normal_cmd()` function. It also +handles the optional count and an extra character for some commands. These +are passed in a `cmdarg_T` to the function that handles the command. + +There is a table `nv_cmds` in [normal.c](normal.c) which +lists the first character of every +command. The second entry of each item is the name of the function that +handles the command. + +### Insert mode commands + +When doing an `i` or `a` command, `normal_cmd()` will call the `edit()` function. +It contains a loop that waits for the next character and handles it. It +returns when leaving Insert mode. + +### Options + +There is a list with all option names in [options.lua](options.lua). + Async event support -------------------