wyj/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-09-17 20:58:20 -04:00
Code Issues Packages Projects Releases Wiki Activity

doc

Browse Source 
closes #7622
This commit is contained in:
Justin M. Keyes 2017-11-14 10:47:49 +01:00
parent 9ada97a810
commit ad9c2d3cb9
11 changed files with 118 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
CONTRIBUTING.md
View File

@ -14,7 +14,7 @@ low-risk/isolated tasks:
Developer guidelines
--------------------
- Nvim developers should read `:help dev-help`.
- Nvim developers should read `:help dev`.
- External UI developers should read `:help dev-ui`.
Reporting problems
@ -24,7 +24,7 @@ Reporting problems
- Search [existing issues][github-issues] (including closed!)
- Update Neovim to the latest version to see if your problem persists.
- Disable plugins incrementally, to narrow down the cause of the issue.
- When reporting a crash, include a stacktrace.
- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/Development-tips#backtrace-linux).
- [Bisect][git-bisect] to the cause of a regression, if you are able. This is _extremely_ helpful.
- Check `$NVIM_LOG_FILE`, if it exists.
- Include `cmake --system-information` for **build** issues.
@ -92,7 +92,7 @@ and [AppVeyor].
- CI builds are compiled with [`-Werror`][gcc-warnings], so compiler warnings
will fail the build.
- If any tests fail, the build will fail.
See [Building Neovim#running-tests][wiki-run-tests] to run tests locally.
See [test/README.md#running-tests][run-tests] to run tests locally.
Passing locally doesn't guarantee passing the CI build, because of the
different compilers and platforms tested against.
- CI runs [ASan] and other analyzers.
@ -168,7 +168,7 @@ as context, use the `-W` argument as well.
[hygiene]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[style-guide]: http://neovim.io/develop/style-guide.xml
[ASan]: http://clang.llvm.org/docs/AddressSanitizer.html
[wiki-run-tests]: https://github.com/neovim/neovim/wiki/Building-Neovim#running-tests
[run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
[wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
[review-checklist]: https://github.com/neovim/neovim/wiki/Code-review-checklist
[3174]: https://github.com/neovim/neovim/issues/3174

2
README.md
View File

@ -14,7 +14,7 @@
[![PVS-studio Check](https://neovim.io/doc/reports/pvs/badge.svg)](https://neovim.io/doc/reports/pvs)
[![Debian CI](https://badges.debian.net/badges/debian/testing/neovim/version.svg)](https://buildd.debian.org/neovim)
[![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592000)](https://github.com/neovim/neovim/releases/)
[![Downloads](https://img.shields.io/github/downloads/neovim/neovim/total.svg?maxAge=2592001)](https://github.com/neovim/neovim/releases/)
Neovim is a project that seeks to aggressively refactor Vim in order to:

91
runtime/doc/api.txt
View File

@ -60,8 +60,7 @@ External programs ("clients") can use the metadata to discover the |rpc-api|.
API contract *api-contract*
The API is made of functions and events. Clients call functions like those
described at |api-global|, and may "attach" in order to receive rich events,
described at |rpc-remote-ui|.
described at |api-global|, and may "attach" to receive rich |ui-events|.
As Nvim develops, its API may change only according the following "contract":
@ -481,6 +480,84 @@ nvim_call_atomic({calls}) *nvim_call_atomic()*
error ocurred, the values from all preceding calls will
still be returned.
*nvim_parse_expression()*
nvim_parse_expression({expr}, {flags}, {highlight})
Parse a VimL expression
Attributes:~
{async}
Parameters:~
{expr} Expression to parse. Is always treated as a
single line.
{flags} Flags: - "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".
{highlight} If 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)).
Return:~
AST: top-level dictionary holds 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.
@note: “Sucessfully 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.
nvim__id({obj}) *nvim__id()*
Returns object given as argument
@ -721,9 +798,10 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
or -1 for ungrouped highlight
{hl_group} Name of the highlight group to use
{line} Line to highlight (zero-indexed)
{col_start} Start of range of columns to highlight
{col_end} End of range of columns to highlight, or -1
to highlight to end of line
{col_start} Start of (byte-indexed) column range to
highlight
{col_end} End of (byte-indexed) column range to
highlight, or -1 to highlight to end of line
Return:~
The src_id that was used
@ -957,9 +1035,6 @@ nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()*
==============================================================================
UI Functions *api-ui*
remote_ui_disconnect() *remote_ui_disconnect()*
TODO: Documentation
nvim_ui_attach({width}, {height}, {options}) *nvim_ui_attach()*
TODO: Documentation

27
runtime/doc/autocmd.txt
View File

@ -259,13 +259,12 @@ Name triggered by ~
|BufNew| just after creating a new buffer
|SwapExists| detected an existing swap file
|TermOpen| when a terminal buffer is starting
|TermClose| when a terminal buffer ends
|TermOpen| when a terminal job starts
|TermClose| when a terminal job ends
Options
|FileType| when the 'filetype' option has been set
|Syntax| when the 'syntax' option has been set
|TermChanged| after the value of 'term' has changed
|OptionSet| after setting any option
Startup and exit
@ -933,26 +932,20 @@ TabEnter Just after entering a tab page. |tab-page|
TabLeave Just before leaving a tab page. |tab-page|
A WinLeave event will have been triggered
first.
{Nvim} *TabNew*
*TabNew*
TabNew When creating a new tab page. |tab-page|
After WinEnter and before TabEnter.
{Nvim} *TabNewEntered*
*TabNewEntered*
TabNewEntered After entering a new tab page. |tab-page|
After BufEnter.
{Nvim} *TabClosed*
*TabClosed*
TabClosed After closing a tab page. <afile> can be used
for the tab page number.
*TermChanged*
TermChanged After the value of 'term' has changed. Useful
for re-loading the syntax file to update the
colors, fonts and other terminal-dependent
settings. Executed for all loaded buffers.
{Nvim} *TermClose*
TermClose When a terminal buffer ends.
{Nvim} *TermOpen*
TermOpen When a terminal buffer is starting. This can
be used to configure the terminal emulator by
setting buffer variables. |terminal|
*TermClose*
TermClose When a |terminal| job ends.
*TermOpen*
TermOpen When a |terminal| job is starting. Can be
used to configure the terminal buffer.
*TermResponse*
TermResponse After the response to |t_RV| is received from
the terminal. The value of |v:termresponse|

12
runtime/doc/syntax.txt
View File

@ -4709,17 +4709,7 @@ ctermbg={color-nr} *highlight-ctermbg*
"cterm". For example, on some systems "cterm=bold ctermfg=3" gives
another color, on others you just get color 3.
For an xterm this depends on your resources, and is a bit
unpredictable. See your xterm documentation for the defaults. The
colors for a color-xterm can be changed from the .Xdefaults file.
Unfortunately this means that it's not possible to get the same colors
for each user.
The MSDOS standard colors are fixed (in a console window), so these
have been used for the names. But the meaning of color names in X11
are fixed, so these color settings have been used, to make the
highlighting settings portable (complicated, isn't it?). The
following names are recognized, with the color number used:
The following names are recognized, with the color number used:
*cterm-colors*
NR-16 NR-8 COLOR NAME ~

2
runtime/doc/ui.txt
View File

@ -9,7 +9,7 @@ Nvim UI protocol *ui*
Type |gO| to see the table of contents.
==============================================================================
Introduction *ui-intro*
UI Events *ui-events*
GUIs can be implemented as external processes communicating with Nvim over the
RPC API. The UI model consists of a terminal-like grid with a single,

19
runtime/doc/various.txt
View File

@ -207,21 +207,18 @@ g8 Print the hex values of the bytes used in the
:sh[ell] Removed. |vim-differences| {Nvim}
*:terminal* *:te*
:te[rminal][!] [{cmd}] Execute {cmd} with 'shell' in a new |terminal| buffer.
Equivalent to: >
:enew
:call termopen('{cmd}')
<
See |termopen()|.
:te[rminal][!] [{cmd}] Execute {cmd} with 'shell' in a new |terminal-emulator|
buffer. Without {cmd}, start an interactive 'shell'.
Without {cmd}, start an interactive shell.
Type |i| to enter |Terminal-mode|, then keys are sent to
the job running in the terminal. Type <C-\><C-N> to
leave Terminal-mode. |CTRL-\_CTRL-N|
Creating the terminal buffer fails when changes have been
made to the current buffer, unless 'hidden' is set.
Fails if changes have been made to the current buffer,
unless 'hidden' is set.
To enter |Terminal-mode| automatically: >
autocmd BufEnter term://* startinsert
autocmd BufLeave term://* stopinsert
autocmd TermOpen * startinsert
<
*:!cmd* *:!* *E34*
:!{cmd} Execute {cmd} with 'shell'. See also |:terminal|.

3
runtime/doc/vim_diff.txt
View File

@ -302,7 +302,8 @@ Highlight groups:
|hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other
groups
The variable name "count" is no fallback for |v:count| anymore.
VimL (Vim script) compatibility:
`count` does not alias to |v:count|
==============================================================================
5. Missing legacy features *nvim-features-missing*

4
src/nvim/api/buffer.c
View File

@ -763,8 +763,8 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
/// or -1 for ungrouped highlight
/// @param hl_group Name of the highlight group to use
/// @param line Line to highlight (zero-indexed)
/// @param col_start Start of range of columns to highlight
/// @param col_end End of range of columns to highlight,
/// @param col_start Start of (byte-indexed) column range to highlight
/// @param col_end End of (byte-indexed) column range to highlight,
/// or -1 to highlight to end of line
/// @param[out] err Error details, if any
/// @return The src_id that was used

2
src/nvim/tui/tui.c
View File

@ -1529,7 +1529,7 @@ static void patch_terminfo_bugs(TUIData *data, const char *term,
|| iterm || iterm_pretending_xterm
|| teraterm // per TeraTerm "Supported Control Functions" doco
// Some linux-type terminals (such as console-terminal-emulator
// from the nosh toolset) implement implement the xterm extension.
// from the nosh toolset) implement the xterm extension.
|| (linuxvt && (xterm_version || (vte_version > 0) || colorterm)))) {
data->unibi_ext.set_cursor_style =
(int)unibi_add_ext_str(ut, "Ss", "\x1b[%p1%d q");

13
test/README.md
View File

@ -168,16 +168,13 @@ minutes](http://learnxinyminutes.com/docs/lua/).
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.
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
[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()`
[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)).
- Use `make testlint` for using the shipped luacheck program ([supported by
syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546))
- Use `make testlint` for using the shipped luacheck program ([supported by syntastic](https://github.com/scrooloose/syntastic/blob/d6b96c079be137c83009827b543a83aa113cc011/doc/syntastic-checkers.txt#L3546))
to lint all tests.
### Where tests go