kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-19 10:45:16 -07:00
Code Issues Packages Projects Releases Wiki Activity

doc

Browse Source
This commit is contained in:
Justin M. Keyes 2019-08-26 01:00:52 +02:00
parent 05c668f684
commit 81c3fa6c9d
14 changed files with 168 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
MAINTAIN.md
View File

@ -3,8 +3,6 @@ Maintaining the Neovim project
Notes on maintaining the Neovim project.
See also: https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt
General guidelines
------------------
@ -14,7 +12,7 @@ General guidelines
* Use automation to solve problems
* Never break the API
Ticket Triage
Ticket triage
-------------
In practice we haven't found a meaningful way to forecast more precisely than
@ -38,14 +36,14 @@ just not something you care very much about, by construction. Post-release you
can review open issues, but chances are your next milestone is already getting
full :)
Release Policy
Release policy
--------------
Release "often", but not "early".
The (unreleased) `master` branch is the "early" channel; it should not be
released if it's not stable. High-risk changes may be merged to `master` if
the next feature-release is not imminent.
the next release is not imminent.
For maintenance releases, create a `release-x.y` branch. If the current release
has a major bug:
@ -55,5 +53,11 @@ has a major bug:
3. Cut a release from `release-x.y`.
- Run `./scripts/release.sh`
- Update (force-push) the remote `stable` tag.
- The [nightly job](https://github.com/neovim/bot-ci/blob/master/ci/nightly.sh)
will update the release assets based on the `stable` tag.
See also: https://github.com/neovim/neovim/issues/862
See also
--------
- https://github.com/neovim/neovim/issues/862
- https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt

8
man/nvim.1
View File

@ -89,10 +89,14 @@ Ex mode, reading stdin as Ex commands.
Ex mode, reading stdin as text.
.Ic :help Ex-mode
.It Fl es
Silent/batch mode, reading stdin as Ex commands.
Silent (non-interactive) Ex mode, reading stdin as Ex commands.
Useful for scripting because it does NOT start a UI, unlike
.Fl e .
.Ic :help silent-mode
.It Fl \&Es
Silent/batch mode, reading stdin as text.
Silent (non-interactive) Ex mode, reading stdin as text.
Useful for scripting because it does NOT start a UI, unlike
.Fl E .
.Ic :help silent-mode
.It Fl d
Diff mode.

51
runtime/doc/api.txt
View File

@ -310,6 +310,7 @@ Here is an example for creating a float with scratch buffer: >
call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
>
To close the float, |nvim_win_close()| can be used.
==============================================================================
Global Functions *api-global*
@ -748,6 +749,21 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
an external top-level window. Currently
accepts no other positioning configuration
together with this.
• `style` : Configure the apparance of the window.
Currently only takes one non-empty value:
• "minimal" Nvim will display the window with
many UI options disabled. This is useful
when displaing a temporary float where the
text should not be edited. Disables
'number', 'relativenumber', 'cursorline',
'cursorcolumn', 'spell' and 'list' options.
'signcolumn' is changed to `auto` . The
end-of-buffer region is hidden by setting
`eob` flag of 'fillchars' to a space char,
and clearing the |EndOfBuffer| region in
'winhighlight'.
• top-level window. Currently accepts no other
positioning configuration together with this.
Return: ~
Window handle, or 0 on error
@ -875,6 +891,23 @@ nvim_get_color_map() *nvim_get_color_map()*
Return: ~
Map of color names and RGB values.
nvim_get_context({types}) *nvim_get_context()*
Gets a map of the current editor state.
Parameters: ~
{types} Context types ("regs", "jumps", "buflist",
"gvars", ...) to gather, or NIL for all (see
|context-types|).
Return: ~
map of global |context|.
nvim_load_context({dict}) *nvim_load_context()*
Sets the current editor state from the given |context| map.
Parameters: ~
{dict} |Context| map.
nvim_get_mode() *nvim_get_mode()*
Gets the current mode. |mode()| "blocking" is true if Nvim is
waiting for input.
@ -1276,7 +1309,7 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
Implies `insert` .
{opts} Optional parameters. Reserved for future use.
nvim__inspect_cell({row}, {col}) *nvim__inspect_cell()*
nvim__inspect_cell({grid}, {row}, {col}) *nvim__inspect_cell()*
TODO: Documentation
@ -1306,7 +1339,8 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Line count, or 0 for unloaded buffer. |api-buffer|
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Activates buffer-update events on the channel.
Activates buffer-update events on a channel, or as lua
callbacks.
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
@ -1315,14 +1349,19 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
first notification will be a
`nvim_buf_lines_event` . Otherwise, the
first notification will be a
`nvim_buf_changedtick_event`
{opts} Optional parameters. Reserved for future
use.
`nvim_buf_changedtick_event` . Not used for
lua callbacks.
{opts} Optional parameters. `on_lines` : lua
callback received on change.
`on_changedtick` : lua callback received on
changedtick increment without text change.
See |api-buffer-updates-lua| for more
information
Return: ~
False when updates couldn't be enabled because the buffer
isn't loaded or `opts` contained an invalid key; otherwise
True.
True. TODO: LUA_API_NO_EVAL
nvim_buf_detach({buffer}) *nvim_buf_detach()*
Deactivates buffer-update events on the channel.

47
runtime/doc/eval.txt
View File

@ -2062,6 +2062,13 @@ count({list}, {expr} [, {ic} [, {start}]])
Number count how many {expr} are in {list}
cscope_connection([{num}, {dbpath} [, {prepend}]])
Number checks existence of cscope connection
ctxget([{index}]) Dict return the |context| dict at {index}
ctxpop() none pop and restore |context| from the
|context-stack|
ctxpush([{types}]) none push the current |context| to the
|context-stack|
ctxset({context}[, {index}]) none set |context| at {index}
ctxsize() Number return |context-stack| size
cursor({lnum}, {col} [, {off}])
Number move cursor to {lnum}, {col}, {off}
cursor({list}) Number move cursor to position in {list}
@ -3232,6 +3239,32 @@ cscope_connection([{num} , {dbpath} [, {prepend}]])
cscope_connection(4, "out", "local") 0
cscope_connection(4, "cscope.out", "/usr/local") 1
<
ctxget([{index}]) *ctxget()*
Returns a |Dictionary| representing the |context| at {index}
from the top of the |context-stack| (see |context-dict|).
If {index} is not given, it is assumed to be 0 (i.e.: top).
ctxpop() *ctxpop()*
Pops and restores the |context| at the top of the
|context-stack|.
ctxpush([{types}]) *ctxpush()*
Pushes the current editor state (|context|) on the
|context-stack|.
If {types} is given and is a |List| of |String|s, it specifies
which |context-types| to include in the pushed context.
Otherwise, all context types are included.
ctxset({context}[, {index}]) *ctxset()*
Sets the |context| at {index} from the top of the
|context-stack| to that represented by {context}.
{context} is a Dictionary with context data (|context-dict|).
If {index} is not given, it is assumed to be 0 (i.e.: top).
ctxsize() *ctxsize()*
Returns the size of the |context-stack|.
cursor({lnum}, {col} [, {off}]) *cursor()*
cursor({list})
Positions the cursor at the column (byte count) {col} in the
@ -5416,24 +5449,22 @@ jobstop({id}) *jobstop()*
(if any) will be invoked.
See |job-control|.
jobwait({ids}[, {timeout}]) *jobwait()*
Wait for a set of jobs and their |on_exit| handlers to
complete.
jobwait({jobs}[, {timeout}]) *jobwait()*
Waits for jobs and their |on_exit| handlers to complete.
{ids} is a list of |job-id|s to wait for.
{jobs} is a List of |job-id|s to wait for.
{timeout} is the maximum waiting time in milliseconds, -1
means forever.
Timeout of 0 can be used to check the status of a job: >
let running = jobwait([{job-id}], 0)[0] == -1
<
During jobwait() callbacks for jobs not in the {ids} list may
During jobwait() callbacks for jobs not in the {jobs} list may
be invoked. The screen will not redraw unless |:redraw| is
invoked by a callback.
Returns a list of len({ids}) integers, where each integer is
the wait-result of the corresponding job. Each wait-result is
one of the following:
Returns a list of len({jobs}) integers, where each integer is
the status of the corresponding job:
Exit-code, if the job exited
-1 if the timeout was exceeded
-2 if the job was interrupted (by |CTRL-C|)

5
runtime/doc/intro.txt
View File

@ -43,9 +43,8 @@ There are many books on Vi and Vim. We recommend these books:
"Modern Vim" by Drew Neil
https://vimcasts.org/publications/
"Practical Vim" is a popular because of its focus on quickly learning common
editing tasks with Vim. "Modern Vim" explores new features introduced by Nvim
and Vim 8.
"Practical Vim" is acclaimed for its focus on quickly learning common editing
tasks with Vim. "Modern Vim" explores new features in Nvim and Vim 8.
"Vim - Vi Improved" by Steve Oualline

2
runtime/doc/job_control.txt
View File

@ -4,7 +4,7 @@
NVIM REFERENCE MANUAL by Thiago de Arruda
Nvim job control *job-control*
Nvim job control *job* *job-control*
Job control is a way to perform multitasking in Nvim, so scripts can spawn and
control multiple processes without blocking the current Nvim instance.

43
runtime/doc/repeat.txt
View File

@ -11,7 +11,7 @@ Chapter 26 of the user manual introduces repeating |usr_26.txt|.
Type |gO| to see the table of contents.
==============================================================================
1. Single repeats *single-repeat*
Single repeats *single-repeat*
*.*
. Repeat last change, with count replaced with [count].
@ -35,7 +35,7 @@ of area is used, see |visual-repeat|.
==============================================================================
2. Multiple repeats *multi-repeat*
Multiple repeats *multi-repeat*
*:g* *:global* *E148*
:[range]g[lobal]/{pattern}/[cmd]
@ -103,7 +103,7 @@ repeated for each matching line. While doing this you cannot use ":global".
To abort this type CTRL-C twice.
==============================================================================
3. Complex repeats *complex-repeat*
Complex repeats *complex-repeat*
*q* *recording*
q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"}
@ -157,7 +157,7 @@ q Stops recording.
line [addr] (default is current line).
==============================================================================
4. Using Vim scripts *using-scripts*
Using Vim scripts *using-scripts*
For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
@ -470,7 +470,7 @@ Rationale:
backslash is to make it very unlikely this is a normal comment line.
==============================================================================
5. Using Vim packages *packages*
Using Vim packages *packages*
A Vim package is a directory that contains one or more plugins. The
advantages over normal plugins:
@ -586,7 +586,7 @@ The "after" directory is most likely not useful in a package. It's not
disallowed though.
==============================================================================
6. Creating Vim packages *package-create*
Creating Vim packages *package-create*
This assumes you write one or more plugins that you distribute as a package.
@ -652,7 +652,7 @@ This works, because loading packages will first add all found directories to
'runtimepath' before sourcing the plugins.
==============================================================================
7. Debugging scripts *debug-scripts*
Debugging scripts *debug-scripts*
Besides the obvious messages that you can add to your scripts to find out what
they are doing, Vim offers a debug mode. This allows you to step through a
@ -876,7 +876,7 @@ OBSCURE
user, don't use typeahead for debug commands.
==============================================================================
8. Profiling *profile* *profiling*
Profiling *profile* *profiling*
Profiling means that Vim measures the time that is spent on executing
functions and/or scripts. The |+profile| feature is required for this.
@ -993,5 +993,32 @@ mind there are various things that may clobber the results:
- The "self" time is wrong when a function is used recursively.
==============================================================================
Context *Context* *context*
The editor state is represented by the Context concept. This includes things
like the current |jumplist|, values of |registers|, and more, described below.
*context-types*
The following Context items are supported:
"jumps" |jumplist|
"regs" |registers|
"buflist" |buffer-list|
"gvars" |global-variable|s
"sfuncs" |script-local| functions
"funcs" global and |script-local| functions
*context-dict*
Context objects are dictionaries with the following key-value pairs:
- "jumps", "regs", "buflist", "gvars":
|readfile()|-style |List| representation of corresponding msgpack
objects (see |msgpackdump()| and |msgpackparse()|).
- "funcs" (includes |script-local| functions as well):
|List| of |:function| definitions.
*context-stack*
An initially-empty internal Context stack is maintained by the ctx-family
functions (see |ctx-functions|).
vim:tw=78:ts=8:noet:ft=help:norl:

5
runtime/doc/starting.txt
View File

@ -199,9 +199,8 @@ argument.
-E reads stdin as text (into buffer 1).
-es *-es* *-Es* *-s-ex* *silent-mode*
-Es Silent or batch mode. Special case of |-s| (which takes an
argument while "-es" doesn't). Disables most prompts,
messages, warnings and errors.
-Es Silent mode (no UI), for scripting. Unrelated to |-s|.
Disables most prompts, messages, warnings and errors.
-es reads/executes stdin as Ex commands. >
printf "put ='foo'\n%%print\n" | nvim -es

7
runtime/doc/usr_41.txt
View File

@ -972,6 +972,13 @@ Prompt Buffer: *promptbuffer-functions*
prompt_setinterrupt() set interrupt callback for a buffer
prompt_setprompt() set the prompt text for a buffer
Context Stack: *ctx-functions*
ctxget() return context at given index from top
ctxpop() pop and restore top context
ctxpush() push given context
ctxset() set context at given index from top
ctxsize() return context stack size
Various: *various-functions*
mode() get current editing mode
visualmode() last visual mode used

1
runtime/doc/vim_diff.txt
View File

@ -169,6 +169,7 @@ Highlight groups:
|expr-highlight| highlight groups (prefixed with "Nvim")
|hl-NormalFloat| highlights floating window
|hl-NormalNC| highlights non-current windows
|hl-MsgArea| highlights messages/cmdline area
|hl-MsgSeparator| highlights separator for scrolled messages
|hl-QuickFixLine|
|hl-Substitute|

3
runtime/nvim.appdata.xml
View File

@ -26,6 +26,7 @@
</screenshots>
<releases>
<release date="2019-07-03" version="0.3.8"/>
<release date="2019-04-29" version="0.3.5"/>
<release date="2019-01-13" version="0.3.4"/>
<release date="2019-01-05" version="0.3.3"/>
@ -33,7 +34,7 @@
<release date="2018-07-19" version="0.3.1"/>
<release date="2018-07-11" version="0.3.0"/>
</releases>
<content_rating type="oars-1.1"/>
<launchable type="desktop-id">nvim.desktop</launchable>
<url type="homepage">https://neovim.io/</url>

2
src/nvim/README.md
View File

@ -62,6 +62,8 @@ Configure the sanitizer(s) via these environment variables:
# Change to detect_leaks=1 to detect memory leaks (slower).
export ASAN_OPTIONS="detect_leaks=0:log_path=$HOME/logs/asan"
# Show backtraces in the logs.
export UBSAN_OPTIONS=print_stacktrace=1
export MSAN_OPTIONS="log_path=${HOME}/logs/tsan"
export TSAN_OPTIONS="log_path=${HOME}/logs/tsan"

10
src/nvim/api/vim.c
View File

@ -1019,7 +1019,7 @@ fail:
///
/// Currently this is used to open floating and external windows.
/// Floats are windows that are drawn above the split layout, at some anchor
/// position in some other window. Floats can be draw internally or by external
/// position in some other window. Floats can be drawn internally or by external
/// GUI with the |ui-multigrid| extension. External windows are only supported
/// with multigrid GUIs, and are displayed as separate top-level windows.
///
@ -1416,9 +1416,9 @@ Dictionary nvim_get_color_map(void)
/// Gets a map of the current editor state.
///
/// @param types Context types ("regs", "jumps", "buflist", "gvars", ...)
/// to gather, or NIL for all.
/// to gather, or NIL for all (see |context-types|).
///
/// @return map of global context
/// @return map of global |context|.
Dictionary nvim_get_context(Array types)
FUNC_API_SINCE(6)
{
@ -1453,9 +1453,9 @@ Dictionary nvim_get_context(Array types)
return dict;
}
/// Sets the current editor state to that in given context dictionary.
/// Sets the current editor state from the given |context| map.
///
/// @param ctx_dict Context dictionary.
/// @param dict |Context| map.
Object nvim_load_context(Dictionary dict)
FUNC_API_SINCE(6)
{

36
test/README.md
View File

@ -140,7 +140,7 @@ To run a *specific* functional test:
To *repeat* a test:
.deps/usr/bin/busted --lpath='build/?.lua' --filter 'foo' --repeat 1000 test/functional/ui/foo_spec.lua
BUSTED_ARGS="--repeat=100 --no-keep-going" TEST_FILE=test/functional/foo_spec.lua make functionaltest
### Filter by tag
@ -173,43 +173,27 @@ Writing tests
Guidelines
----------
- Consider [BDD](http://en.wikipedia.org/wiki/Behavior-driven_development)
guidelines for organization and readability of tests. Describe what you're
testing (and the environment if applicable) and create specs that assert its
behavior.
- For testing static functions or functions that have side effects visible only
in module-global variables, create accessors for the modified variables. For
example, say you are testing a function in misc1.c that modifies a static
variable, create a file `test/c-helpers/misc1.c` and add a function that
retrieves the value after the function call. Files under `test/c-helpers` will
only be compiled when building the test shared library.
- Luajit needs to know about type and constant declarations used in function
prototypes. The
[helpers.lua](https://github.com/neovim/neovim/blob/master/test/unit/helpers.lua)
file automatically parses `types.h`, so types used in the tested functions
must be moved to it to avoid having to rewrite the declarations in the test
files (even though this is how it's currently done currently in the misc1/fs
modules, but contributors are encouraged to refactor the declarations).
- Macro constants must be rewritten as enums so they can be "visible" to the
tests automatically.
- Busted supports various "output providers". The
**[gtest](https://github.com/Olivine-Labs/busted/pull/394) output provider**
shows verbose details that can be useful to diagnose hung tests. Either modify
the Makefile or compile with `make
CMAKE_EXTRA_FLAGS=-DBUSTED_OUTPUT_TYPE=gtest` to enable it.
- **Use busted's `pending()` feature** to skip tests
could be moved to it to avoid having to rewrite the declarations in the test
files.
- `#define` constants must be rewritten `const` or `enum` so they can be
"visible" to the tests.
- Use **pending()** to skip tests
([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
Do not silently skip the test with `if-else`. If a functional test depends on
some external factor (e.g. the existence of `md5sum` on `$PATH`), *and* you
can't mock or fake the dependency, then skip the test via `pending()` if the
external factor is missing. This ensures that the *total* test-count
(success + fail + error + pending) is the same in all environments.
- *Note:* `pending()` is ignored if it is missing an argument _unless_ it is
- *Note:* `pending()` is ignored if it is missing an argument, unless it is
[contained in an `it()` block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
Provide empty function argument if the `pending()` call is outside of `it()`
([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
- Really long `source([=[...]=])` blocks may break syntax highlighting. Try
`:syntax sync fromstart` to fix it.
- Really long `source([=[...]=])` blocks may break Vim's Lua syntax
highlighting. Try `:syntax sync fromstart` to fix it.
Where tests go
--------------
@ -254,6 +238,8 @@ Test behaviour is affected by environment variables. Currently supported
treated as Integer; when defined, treated as String; when defined, treated as
Number; !must be defined to function properly):
- `BUSTED_ARGS` (F) (U): arguments forwarded to `busted`.
- `GDB` (F) (D): makes nvim instances to be run under `gdbserver`. It will be
accessible on `localhost:7777`: use `gdb build/bin/nvim`, type `target remote
:7777` inside.