diff options
| -rw-r--r-- | README.md | 5 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 44 | ||||
| -rw-r--r-- | runtime/doc/if_lua.txt | 22 | ||||
| -rw-r--r-- | runtime/doc/intro.txt | 3 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/provider.txt | 14 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 26 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 5 | ||||
| -rw-r--r-- | src/nvim/lua/executor.c | 4 | ||||
| -rw-r--r-- | src/nvim/ops.c | 2 | ||||
| -rw-r--r-- | test/README.md | 53 |
13 files changed, 121 insertions, 63 deletions
@@ -34,6 +34,11 @@ Install from source make CMAKE_BUILD_TYPE=RelWithDebInfo sudo make install +To install to a non-default location, specify `CMAKE_INSTALL_PREFIX`: + + make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=/full/path/" + make install + See [the wiki](https://github.com/neovim/neovim/wiki/Building-Neovim) for details. Install from package diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 159dd93c5e..876adf0d72 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -7,7 +7,7 @@ Nvim API *API* *api* Nvim exposes a powerful API that can be used by plugins and external processes -via |msgpack-rpc|, Lua and VimL (|eval-api|). +via |RPC|, |Lua| and VimL (|eval-api|). Applications can also embed libnvim to work with the C API directly. diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 298f64bbee..36826e2479 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -142,6 +142,8 @@ shell The Vim application. This can cover the whole screen (e.g., window View on a buffer. There can be several windows in Vim, together with the command line, menubar, toolbar, etc. they fit in the shell. +frame Windows are kept in a tree of frames. Each frame contains + a column, row, or window ("leaf" frame). PROVIDERS *dev-provider* @@ -230,23 +232,47 @@ _not_ a Buffer). The common {action} "list" indicates that it lists all bufs (plural) in the global context. +API-CLIENT *dev-api-client* + +Package Naming ~ +API client packages should NOT be named something ambiguous like "neovim" or +"python-client". Use "nvim" as a prefix/suffix to some other identifier +following ecosystem conventions. + +For example, Python packages tend to have "py" in the name, so "pynvim" is +a good name: it's idiomatic and unambiguous. If the package is named "neovim", +it confuses users, and complicates documentation and discussions. + +Examples of API-client package names: + GOOD: nvim-racket + GOOD: pynvim + BAD: python-client + BAD: neovim + +Implementation ~ +Consider using libmpack instead of the msgpack.org C/C++ library. libmpack is +small, efficient, and C89-compatible. It can be easily inlined in your +C project source, too. https://github.com/libmpack/libmpack/ + + EXTERNAL UI *dev-ui* +Compatibility ~ External UIs should be aware of the |api-contract|. In particular, future -versions of Nvim may add optional, new items to existing events. The API is -strongly backwards-compatible, but clients must not break if new fields are -added to existing events. +versions of Nvim may add new items to existing events. The API is strongly +backwards-compatible, but clients must not break if new fields are added to +existing events. -External UIs are expected to implement some common features. +Common Features ~ +External UIs are expected to implement these common features: +- Cursor style (shape, color) should respond to the 'guicursor' properties + delivered with the mode_info_set UI event. +- Send the "super" key (Windows key, Apple key) as a |<D-| chord. -- Users may want to configure UI-specific options. The UI should publish the - |GUIEnter| autocmd after attaching to Nvim: > - doautocmd GUIEnter +Implementation ~ - Options can be monitored for changes by the |OptionSet| autocmd. E.g. if the user sets the 'guifont' option, this autocmd notifies channel 42: > autocmd OptionSet guifont call rpcnotify(42, 'option-changed', 'guifont', &guifont) -- cursor-shape change: 'guicursor' properties are sent in the mode_info_set UI - event. vim:tw=78:ts=8:ft=help:norl: diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt index a123041866..968d882a22 100644 --- a/runtime/doc/if_lua.txt +++ b/runtime/doc/if_lua.txt @@ -24,7 +24,7 @@ the existing `package.cpath` are used. Example: 1. Given that - 'runtimepath' contains `/foo/bar,/xxx;yyy/baz,/abc`; - - initial (defined at compile time or derived from + - initial (defined at compile-time or derived from `$LUA_CPATH`/`$LUA_INIT`) `package.cpath` contains `./?.so;/def/ghi/a?d/j/g.elf;/def/?.so`. 2. It finds `?`-containing suffixes `/?.so`, `/a?d/j/g.elf` and `/?.so`, in @@ -159,14 +159,17 @@ Examples: > :lua vim.api.nvim_command('echo "Hello, Nvim!"') < +To see the Lua version: > + :lua print(_VERSION) + +To see the LuaJIT version: > + :lua print(jit.version) +< :[range]lua << {endmarker} {script} {endmarker} Execute Lua script {script}. - Note: This command doesn't work when the Lua - feature wasn't compiled in. To avoid errors, see - |script-here|. {endmarker} must NOT be preceded by any white space. If {endmarker} is omitted from after the "<<", a dot '.' must be used after {script}, like @@ -186,15 +189,8 @@ Example: EOF endfunction -Note that the variables are prefixed with `local`: they will disappear when -block finishes. This is not the case for globals. - -To see what version of Lua you have: > - :lua print(_VERSION) - -If you use LuaJIT you can also use this: > - :lua print(jit.version) -< +Note that the `local` variables will disappear when block finishes. This is +not the case for globals. *:luado* :[range]luado {body} Execute Lua function "function (line, linenr) {body} diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt index 90b0ff7da3..30524fb6aa 100644 --- a/runtime/doc/intro.txt +++ b/runtime/doc/intro.txt @@ -373,8 +373,7 @@ CTRL-{char} {char} typed as a control character; that is, typing {char} *key-notation* *key-codes* *keycodes* These names for keys are used in the documentation. They can also be used -with the ":map" command (insert the key name by pressing CTRL-K and then the -key you want the name for). +with the ":map" command. notation meaning equivalent decimal value(s) ~ ----------------------------------------------------------------------- diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index 7af6e401da..a1453a6cc6 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -175,7 +175,7 @@ contains information that makes this task easier (see also |rpc-types|): even more strongly-typed APIs. - Functions that are considered to be methods that operate on instances of Nvim special types (msgpack EXT) will have the `"method"` attribute set to - `true`. The reciever type is the type of the first argument. The method + `true`. The receiver type is the type of the first argument. The method names are prefixed with `nvim_` plus a shortened type name, e.g. `nvim_buf_get_lines` represents the `get_lines` method of a Buffer instance. - Global functions have `"method"` set to `false` and are prefixed with just diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 4df08ca5fb..c2018fc511 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -6759,7 +6759,7 @@ A jump table for the options with a short description can be found at |Q_op|. Highlights of vertical separators are determined by the window to the left of the separator. The highlight of a tabpage in |tabline| is - determine by the last-focused window of the tabpage. Highlights of + determined by the last-focused window of the tabpage. Highlights of the popupmenu are determined by the current window. Highlights in the message area cannot be overridden. diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index 02f3fcab6c..b806b08f95 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -133,8 +133,8 @@ registers. Nvim looks for these clipboard tools, in order of priority: - |g:clipboard| - pbcopy/pbpaste (macOS) - - xclip - - xsel (newer alternative to xclip) + - xsel (if $DISPLAY is set) + - xclip (if $DISPLAY is set) - lemonade (for SSH) https://github.com/pocke/lemonade - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/ - win32yank (Windows) @@ -162,13 +162,11 @@ process has not died, the cached selection is applied. ============================================================================== X11 selection mechanism *clipboard-x11* *x11-selection* -The clipboard providers for X11 store text in what is known as "selections". -Selections are "owned" by an application, so when the application is closed, -the selection text is lost. - +X11 clipboard providers store text in "selections". Selections are owned by an +application, so when the application gets closed, the selection text is lost. The contents of selections are held by the originating application (e.g., upon -a copy), and only passed on to another application when that other application -asks for them (e.g., upon a paste). +a copy), and only passed to another application when that other application +requests them (e.g., upon a paste). *quoteplus* *quote+* diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index c92fcd8994..6959d64989 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -60,14 +60,17 @@ a complete and centralized reference of those differences. MAJOR COMPONENTS ~ -Embedded terminal emulator |terminal| -RPC API |RPC| -Shared data |shada| -XDG base directories |xdg| +API |API| +Lua scripting |lua| Job control |job-control| Remote plugins |remote-plugin| -Python plugins |provider-python| -Clipboard integration |provider-clipboard| +Providers + Clipboard |provider-clipboard| + Python plugins |provider-python| + Ruby plugins |provider-ruby| +Shared data |shada| +Embedded terminal |terminal| +XDG base directories |xdg| USER EXPERIENCE ~ @@ -87,6 +90,16 @@ Working intuitively and consistently is a major goal of Nvim. - Vim's internal test functions (test_autochdir(), test_settime(), etc.) are not exposed (nor implemented); instead Nvim has a robust API. +- Behaviors, options, documentation are removed if they cost users more time + than they save. + +Usability details have been improved where the benefit outweighs any +backwards-compatibility cost. Some examples: + +- |K| in help documents can be used like |CTRL-]|. +- Directories for 'directory' and 'undodir' are auto-created. +- Terminal features such as 'guicursor' are enabled where possible. + ARCHITECTURE ~ External plugins run in separate processes. |remote-plugin| This improves @@ -130,6 +143,7 @@ Commands: |:checkhealth| |:drop| is available on all platforms |:Man| is available by default, with many improvements such as completion + |:tchdir| tab-local |current-directory| Functions: |dictwatcheradd()| notifies a callback whenever a |Dict| is modified diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 98f4410347..86f4a9d008 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -166,7 +166,10 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi) /// On VimL error: Does not fail, but updates v:errmsg. /// /// Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call -/// is not deferred. This is the most reliable way to emulate real user input. +/// is not deferred. This is the most reliable way to send real user input. +/// +/// @note |keycodes| like <CR> are translated, so `<` is special. +/// To input a literal `<`, send `<LT>`. /// /// @param keys to be typed /// @return Number of bytes actually written (can be fewer than diff --git a/src/nvim/lua/executor.c b/src/nvim/lua/executor.c index 16bb4169c4..8e7b8a1824 100644 --- a/src/nvim/lua/executor.c +++ b/src/nvim/lua/executor.c @@ -336,8 +336,8 @@ static lua_State *nlua_init(void) /// Calls nlua_init() if needed. Is responsible for pre-lua call initalization /// like updating `package.[c]path` with directories derived from &runtimepath. /// -/// @return Interprter instance to use. Will either be initialized now or taken -/// from previous initalization. +/// @return Interpreter instance to use. Will either be initialized now or +/// taken from previous initialization. static lua_State *nlua_enter(void) FUNC_ATTR_NONNULL_RET FUNC_ATTR_WARN_UNUSED_RESULT { diff --git a/src/nvim/ops.c b/src/nvim/ops.c index c6df71ea46..432c9a8b47 100644 --- a/src/nvim/ops.c +++ b/src/nvim/ops.c @@ -2735,7 +2735,7 @@ void do_put(int regname, yankreg_T *reg, int dir, long count, int flags) // Autocommands may be executed when saving lines for undo, which may make // y_array invalid. Start undo now to avoid that. if (u_save(curwin->w_cursor.lnum, curwin->w_cursor.lnum + 1) == FAIL) { - ELOG(_("Failed to save undo information")); + ELOG("Failed to save undo information"); return; } } diff --git a/test/README.md b/test/README.md index 01db5960cd..44558f0981 100644 --- a/test/README.md +++ b/test/README.md @@ -1,31 +1,48 @@ -# Tests +Tests +===== Tests are run by `/cmake/RunTests.cmake` file, using busted. For some failures, `.nvimlog` (or `$NVIM_LOG_FILE`) may provide insight. -## Directory structure +Lint +---- -Directories with tests: `/test/benchmark` for benchmarks, `/test/functional` for -functional tests, `/test/unit` for unit tests. `/test/config` contains `*.in` -files (currently a single one) which are transformed into `*.lua` files using -`configure_file` CMake command: this is for acessing CMake variables in lua -tests. `/test/includes` contains include files for use by luajit `ffi.cdef` -C definitions parser: normally used to make macros not accessible via this -mechanism accessible the other way. +`make lint` (and `make testlint`) runs [luacheck](https://github.com/mpeterv/luacheck) +on the test code. -Files `/test/*/preload.lua` contain modules which will be preloaded by busted, -via `--helper` option. `/test/**/helpers.lua` contain various “library” -functions, (intended to be) used by a number of tests and not just a single one. +If a luacheck warning must be ignored, specify the warning code. Example: -`/test/*/**/*_spec.lua` are files containing actual tests. Files that do not end -with a `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they -have some common topic. + -- luacheck: ignore 621 -Tests inside `/test/unit` and `/test/functional` are normally divided into -groups by the semantic component they are testing. +http://luacheck.readthedocs.io/en/stable/warnings.html -## Environment variables +Ignore the smallest applicable scope (e.g. inside a function, not at the top of +the file). + +Layout +------ + +- `/test/benchmark` : benchmarks +- `/test/functional` : functional tests +- `/test/unit` : unit tests +- `/test/config` : contains `*.in` files which are transformed into `*.lua` + files using `configure_file` CMake command: this is for acessing CMake + variables in lua tests. +- `/test/includes` : include-files for use by luajit `ffi.cdef` C definitions + parser: normally used to make macros not accessible via this mechanism + accessible the other way. +- `/test/*/preload.lua` : modules preloaded by busted `--helper` option +- `/test/**/helpers.lua` : common utility functions for test code +- `/test/*/**/*_spec.lua` : actual tests. Files that do not end with + `_spec.lua` are libraries like `/test/**/helpers.lua`, except that they have + some common topic. + +Tests in `/test/unit` and `/test/functional` are normally divided into groups +by the semantic component they are testing. + +Environment variables +--------------------- Test behaviour is affected by environment variables. Currently supported (Functional, Unit, Benchmarks) (when Defined; when set to _1_; when defined, |