diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/autoload/msgpack.vim | 3 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 99 | ||||
| -rw-r--r-- | runtime/doc/autocmd.txt | 14 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 82 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 20 | ||||
| -rw-r--r-- | runtime/doc/options.txt | 1 | ||||
| -rw-r--r-- | runtime/doc/repeat.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/tabpage.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/vim_diff.txt | 2 |
9 files changed, 195 insertions, 36 deletions
diff --git a/runtime/autoload/msgpack.vim b/runtime/autoload/msgpack.vim index e6022922fe..2bb7ec5b02 100644 --- a/runtime/autoload/msgpack.vim +++ b/runtime/autoload/msgpack.vim @@ -395,7 +395,8 @@ endfunction "" " Dump floating-point value. function s:msgpack_dump_float(v) abort - return string(type(a:v) == type({}) ? a:v._VAL : a:v) + return substitute(string(type(a:v) == type({}) ? a:v._VAL : a:v), + \'\V\^\(-\)\?str2float(''\(inf\|nan\)'')\$', '\1\2', '') endfunction "" diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt new file mode 100644 index 0000000000..ca79465e0d --- /dev/null +++ b/runtime/doc/api.txt @@ -0,0 +1,99 @@ +*api.txt* For Nvim. {Nvim} + + + NVIM REFERENCE MANUAL by Thiago de Arruda + +The C API of Nvim *nvim-api* + +1. Introduction |nvim-api-intro| +2. API Types |nvim-api-types| +3. API metadata |nvim-api-metadata| +4. Buffer highlighting |nvim-api-highlights| + +============================================================================== +1. Introduction *nvim-api-intro* + +Nvim defines a C API as the primary way for external code to interact with +the NVim core. In the present version of Nvim the API is primarily used by +external processes to interact with Nvim using the msgpack-rpc protocol, see +|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core +features, but this is not implemented yet. Later on, Nvim might be embeddable +in C applications as libnvim, and the application will then control the +embedded instance by calling the C API directly. + +============================================================================== +2. API Types *nvim-api-types* + +Nvim's C API uses custom types for all functions. Some are just typedefs +around C99 standard types, and some are Nvim defined data structures. + +Boolean -> bool +Integer (signed 64-bit integer) -> int64_t +Float (IEEE 754 double precision) -> double +String -> {char* data, size_t size} struct + +Additionally, the following data structures are defined: + +Array +Dictionary +Object + +The following handle types are defined as integer typedefs, but are +discriminated as separate types in an Object: + +Buffer -> enum value kObjectTypeBuffer +Window -> enum value kObjectTypeWindow +Tabpage -> enum value kObjectTypeTabpage + +============================================================================== +3. API metadata *nvim-api-metadata* + +Nvim exposes metadata about the API as a Dictionary with the following keys: + +functions calling signature of the API functions +types The custom handle types defined by Nvim +error_types The possible kinds of errors an API function can exit with. + +This metadata is mostly useful for external programs accessing the api over +msgpack-api, see |msgpack-rpc-api|. + +============================================================================== +4. Buffer highlighting *nvim-api-highlights* + +Nvim allows plugins to add position-based highlights to buffers. This is +similar to |matchaddpos()| but with some key differences. The added highlights +are associated with a buffer and adapts to line insertions and deletions, +similar to signs. It is also possible to manage a set of highlights as a group +and delete or replace all at once. + +The intended use case are linter or semantic highlighter plugins that monitor +a buffer for changes, and in the background compute highlights to the buffer. +Another use case are plugins that show output in an append-only buffer, and +want to add highlights to the outputs. Highlight data cannot be preserved +on writing and loading a buffer to file, nor in undo/redo cycles. + +Highlights are registered using the |buffer_add_highlight| function, see the +generated API documentation for details. If an external highlighter plugin is +adding a large number of highlights in a batch, performance can be improved by +calling |buffer_add_highlight| as an asynchronous notification, after first +(synchronously) reqesting a source id. Here is an example using wrapper +functions in the python client: +> + src = vim.new_highlight_source() + + buf = vim.current.buffer + for i in range(5): + buf.add_highlight("String",i,0,-1,src_id=src) + + # some time later + + buf.clear_highlight(src) +< +If the highlights don't need to be deleted or updated, just pass -1 as +src_id (this is the default in python). |buffer_clear_highlight| can be used +to clear highligts from a specific source, in a specific line range or the +entire buffer by passing in the line range 0, -1 (the later is the default +in python as used above). + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index e17281821c..ec5818e16f 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -308,6 +308,8 @@ Name triggered by ~ |InsertCharPre| when a character was typed in Insert mode, before inserting it +|TextYankPost| when some text is yanked or deleted + |TextChanged| after a change was made to the text in Normal mode |TextChangedI| after a change was made to the text in Insert mode @@ -722,6 +724,18 @@ InsertCharPre When a character is typed in Insert mode, It is not allowed to change the text |textlock|. The event is not triggered when 'paste' is set. + *TextYankPost* +TextYankPost Just after a |yank| or |deleting| command, but not + if the black hole register |quote_| is used nor + for |setreg()|. Pattern must be * because its + meaning may change in the future. + Sets these |v:event| keys: + operator + regcontents + regname + regtype + Recursion is ignored. + It is not allowed to change the text |textlock|. *InsertEnter* InsertEnter Just before starting Insert mode. Also for Replace mode and Virtual Replace mode. The diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 45980f5d94..0b2880ef03 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1386,6 +1386,22 @@ v:errors Errors found by assert functions, such as |assert_true()|. < If v:errors is set to anything but a list it is made an empty list by the assert function. + *v:event* *event-variable* +v:event Dictionary of event data for the current |autocommand|. The + available keys differ per event type and are specified at the + documentation for each |event|. The possible keys are: + operator The operation performed. Unlike + |v:operator|, it is set also for an Ex + mode command. For instance, |:yank| is + translated to "|y|". + regcontents Text stored in the register as a + |readfile()|-style list of lines. + regname Requested register (e.g "x" for "xyy) + or the empty string for an unnamed + operation. + regtype Type of register as returned by + |getregtype()|. + *v:exception* *exception-variable* v:exception The value of the exception most recently caught and not finished. See also |v:throwpoint| and |throw-variables|. @@ -1786,8 +1802,10 @@ cursor( {lnum}, {col} [, {off}]) cursor( {list}) Number move cursor to position in {list} deepcopy( {expr} [, {noref}]) any make a full copy of {expr} delete( {fname}) Number delete file {fname} -dictwatcheradd({dict}, {pattern}, {callback}) Start watching a dictionary -dictwatcherdel({dict}, {pattern}, {callback}) Stop watching a dictionary +dictwatcheradd( {dict}, {pattern}, {callback}) + Start watching a dictionary +dictwatcherdel( {dict}, {pattern}, {callback}) + Stop watching a dictionary did_filetype() Number TRUE if FileType autocommand event used diff_filler( {lnum}) Number diff filler lines about {lnum} diff_hlID( {lnum}, {col}) Number diff highlighting at {lnum}/{col} @@ -1807,7 +1825,7 @@ feedkeys( {string} [, {mode}]) Number add key sequence to typeahead buffer filereadable( {file}) Number TRUE if {file} is a readable file filewritable( {file}) Number TRUE if {file} is a writable file filter( {expr}, {string}) List/Dict remove items from {expr} where - {string} is 0 + {string} is 0 finddir( {name}[, {path}[, {count}]]) String find directory {name} in {path} findfile( {name}[, {path}[, {count}]]) @@ -1889,20 +1907,22 @@ inputdialog( {p} [, {t} [, {c}]]) String like input() but in a GUI dialog inputlist( {textlist}) Number let the user pick from a choice list inputrestore() Number restore typeahead inputsave() Number save and clear typeahead -inputsecret( {prompt} [, {text}]) String like input() but hiding the text -insert( {list}, {item} [, {idx}]) List insert {item} in {list} [before {idx}] +inputsecret( {prompt} [, {text}]) + String like input() but hiding the text +insert( {list}, {item} [, {idx}]) + List insert {item} in {list} [before {idx}] invert( {expr}) Number bitwise invert isdirectory( {directory}) Number TRUE if {directory} is a directory islocked( {expr}) Number TRUE if {expr} is locked items( {dict}) List key-value pairs in {dict} -jobclose({job}[, {stream}]) Number Closes a job stream(s) -jobpid({job}) Number Returns pid of a job. -jobresize({job}, {width}, {height}) +jobclose( {job}[, {stream}]) Number Closes a job stream(s) +jobpid( {job}) Number Returns pid of a job. +jobresize( {job}, {width}, {height}) Number Resize {job}'s pseudo terminal window -jobsend({job}, {data}) Number Writes {data} to {job}'s stdin -jobstart({cmd}[, {opts}]) Number Spawns {cmd} as a job -jobstop({job}) Number Stops a job -jobwait({ids}[, {timeout}]) Number Wait for a set of jobs +jobsend( {job}, {data}) Number Writes {data} to {job}'s stdin +jobstart( {cmd}[, {opts}]) Number Spawns {cmd} as a job +jobstop( {job}) Number Stops a job +jobwait( {ids}[, {timeout}]) Number Wait for a set of jobs join( {list} [, {sep}]) String join {list} items into one String keys( {dict}) List keys in {dict} len( {expr}) Number the length of {expr} @@ -1972,12 +1992,12 @@ repeat( {expr}, {count}) String repeat {expr} {count} times resolve( {filename}) String get filename a shortcut points to reverse( {list}) List reverse {list} in-place round( {expr}) Float round off {expr} -rpcnotify({channel}, {event}[, {args}...]) +rpcnotify( {channel}, {event}[, {args}...]) Sends a |msgpack-rpc| notification to {channel} -rpcrequest({channel}, {method}[, {args}...]) +rpcrequest( {channel}, {method}[, {args}...]) Sends a |msgpack-rpc| request to {channel} -rpcstart({prog}[, {argv}]) Spawns {prog} and opens a |msgpack-rpc| channel -rpcstop({channel}) Closes a |msgpack-rpc| {channel} +rpcstart( {prog}[, {argv}]) Spawns {prog} and opens a |msgpack-rpc| channel +rpcstop( {channel}) Closes a |msgpack-rpc| {channel} screenattr( {row}, {col}) Number attribute at screen position screenchar( {row}, {col}) Number character at screen position screencol() Number current cursor column @@ -1999,11 +2019,12 @@ setbufvar( {expr}, {varname}, {val}) set {varname} in buffer {expr} to {val} setcharsearch( {dict}) Dict set character search from {dict} setcmdpos( {pos}) Number set cursor position in command-line setline( {lnum}, {line}) Number set line {lnum} to {line} -setloclist( {nr}, {list}[, {action}]) +setloclist( {nr}, {list}[, {action}[, {title}]]) Number modify location list using {list} setmatches( {list}) Number restore a list of matches setpos( {expr}, {list}) Number set the {expr} position to {list} -setqflist( {list}[, {action}]) Number modify quickfix list using {list} +setqflist( {list}[, {action}[, {title}]] + Number modify quickfix list using {list} setreg( {n}, {v}[, {opt}]) Number set register to value and type settabvar( {nr}, {varname}, {val}) set {varname} in tab page {nr} to {val} settabwinvar( {tabnr}, {winnr}, {varname}, {val}) set {varname} in window @@ -5732,11 +5753,13 @@ setline({lnum}, {text}) *setline()* :endfor < Note: The '[ and '] marks are not set. -setloclist({nr}, {list} [, {action}]) *setloclist()* +setloclist({nr}, {list} [, {action}[, {title}]]) *setloclist()* Create or replace or add to the location list for window {nr}. When {nr} is zero the current window is used. For a location list window, the displayed location list is modified. For an - invalid window number {nr}, -1 is returned. + invalid window number {nr}, -1 is returned. If {title} is + given, it will be used to set |w:quickfix_title| after opening + the location window. Otherwise, same as |setqflist()|. Also see |location-list|. @@ -5793,7 +5816,7 @@ setpos({expr}, {list}) |winrestview()|. -setqflist({list} [, {action}]) *setqflist()* +setqflist({list} [, {action}[, {title}]]) *setqflist()* Create or replace or add to the quickfix list using the items in {list}. Each item in {list} is a dictionary. Non-dictionary items in {list} are ignored. Each dictionary @@ -5832,6 +5855,9 @@ setqflist({list} [, {action}]) *setqflist()* with the items from {list}. If {action} is not present or is set to ' ', then a new list is created. + If {title} is given, it will be used to set |w:quickfix_title| + after opening the quickfix window. + Returns zero for success, -1 for failure. This function can be used to create a quickfix list @@ -6232,12 +6258,22 @@ string({expr}) Return {expr} converted to a String. If {expr} is a Number, {expr} type result ~ String 'string' Number 123 - Float 123.123456 or 1.123456e8 - Funcref function('name') + Float 123.123456 or 1.123456e8 or + `str2float('inf')` + Funcref `function('name')` List [item, item] Dictionary {key: value, key: value} Note that in String values the ' character is doubled. Also see |strtrans()|. + Note 2: Output format is mostly compatible with YAML, except + for infinite and NaN floating-point values representations + which use |str2float()|. Strings are also dumped literally, + only single quote is escaped, which does not allow using YAML + for parsing back binary strings (including text when + 'encoding' is not UTF-8). |eval()| should always work for + strings and floats though and this is the only official + method, use |msgpackdump()| or |json_encode()| if you need to + share data with other application. *strlen()* strlen({expr}) The result is a Number, which is the length of the String diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt index d732e7f818..bafb9dfc2c 100644 --- a/runtime/doc/msgpack_rpc.txt +++ b/runtime/doc/msgpack_rpc.txt @@ -7,7 +7,7 @@ The Msgpack-RPC Interface to Nvim *msgpack-rpc* 1. Introduction |msgpack-rpc-intro| -2. API |msgpack-rpc-api| +2. API mapping |msgpack-rpc-api| 3. Connecting |msgpack-rpc-connecting| 4. Clients |msgpack-rpc-clients| 5. Types |msgpack-rpc-types| @@ -36,13 +36,13 @@ Nvim's msgpack-rpc interface is like a more powerful version of Vim's `clientserver` feature. ============================================================================== -2. API *msgpack-rpc-api* +2. API mapping *msgpack-rpc-api* -The Nvim C API is automatically exposed to the msgpack-rpc interface by the -build system, which parses headers at src/nvim/api from the project root. A -dispatch function is generated, which matches msgpack-rpc method names with -non-static API functions, converting/validating arguments and return values -back to msgpack. +The Nvim C API, see |nvim-api|, is automatically exposed to the msgpack-rpc +interface by the build system, which parses headers at src/nvim/api from the +project root. A dispatch function is generated, which matches msgpack-rpc method +names with non-static API functions, converting/validating arguments and return +values back to msgpack. Client libraries will normally provide wrappers that hide msgpack-rpc details from programmers. The wrappers can be automatically generated by reading @@ -63,7 +63,7 @@ Here's a simple way to get human-readable description of the API (requires Python and the `pyyaml`/`msgpack-python` pip packages): > nvim --api-info | python -c 'import msgpack, sys, yaml; print yaml.dump(msgpack.unpackb(sys.stdin.read()))' > api.yaml - +< ============================================================================== 3. Connecting *msgpack-rpc-connecting* @@ -162,8 +162,8 @@ https://github.com/msgpack-rpc/msgpack-rpc-ruby/blob/master/lib/msgpack/rpc/tran ============================================================================== 5. Types *msgpack-rpc-types* -Nvim's C API uses custom types for all functions (some are just typedefs -around C99 standard types). The types can be split into two groups: +Nvim's C API uses custom types for all functions, se |nvim-api-types|. +For the purpose of mapping to msgpack, he types can be split into two groups: - Basic types that map natively to msgpack (and probably have a default representation in msgpack-supported programming languages) diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index ced303947b..44696d10bb 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -5538,6 +5538,7 @@ A jump table for the options with a short description can be found at |Q_op|. c don't give |ins-completion-menu| messages. For example, "-- XXX completion (YYY)", "match 1 of 2", "The only match", "Pattern not found", "Back at original", etc. + q use "recording" instead of "recording @a" This gives you the opportunity to avoid that a change between buffers requires you to hit <Enter>, but still gives as useful a message as diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt index 21b5eef811..b2e935eb3f 100644 --- a/runtime/doc/repeat.txt +++ b/runtime/doc/repeat.txt @@ -109,6 +109,12 @@ q{0-9a-zA-Z"} Record typed characters into register {0-9a-zA-Z"} while executing a register, and it doesn't work inside a mapping and |:normal|. + Note: If the register being used for recording is also + used for |y| and |p| the result is most likely not + what is expected, because the put will paste the + recorded macro and the yank will overwrite the + recorded macro. + q Stops recording. Implementation note: The 'q' that stops recording is not stored in the register, unless it was the result diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index 59c4a28ff2..70e6953211 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -273,8 +273,8 @@ window on the same buffer and then edit another buffer. Thus ":tabnew" triggers: WinLeave leave current window TabLeave leave current tab page - TabEnter enter new tab page WinEnter enter window in new tab page + TabEnter enter new tab page BufLeave leave current buffer BufEnter enter new empty buffer @@ -282,8 +282,8 @@ When switching to another tab page the order is: BufLeave WinLeave TabLeave - TabEnter WinEnter + TabEnter BufEnter When entering a new tab page (|:tabnew|), TabNew is triggered before TabEnter diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt index d3768409f5..8722fced26 100644 --- a/runtime/doc/vim_diff.txt +++ b/runtime/doc/vim_diff.txt @@ -99,6 +99,8 @@ are always available and may be used simultaneously in separate plugins. The Same thing applies to |string()| (though it uses construct like "{E724@level}"), but this is not reliable because |string()| continues to error out. +4. Stringifyed infinite and NaN values now use |str2float()| and can be evaled + back. Viminfo text files were replaced with binary (messagepack) ShaDa files. Additional differences: |