aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Clason <c.clason@uni-graz.at>2022-11-22 18:41:00 +0100
committerChristian Clason <c.clason@uni-graz.at>2022-12-02 16:05:00 +0100
commit952f19ba38a3c826c268c4f744a332cf90021800 (patch)
tree4c78e4968d03c41ad1bd47b6610de5908de20c32
parent5093f38c9fed9fae04234035ea253862ba8375ef (diff)
downloadrneovim-952f19ba38a3c826c268c4f744a332cf90021800.tar.gz
rneovim-952f19ba38a3c826c268c4f744a332cf90021800.tar.bz2
rneovim-952f19ba38a3c826c268c4f744a332cf90021800.zip
docs: add language annotation to Nvim manual
-rw-r--r--runtime/doc/api.txt38
-rw-r--r--runtime/doc/channel.txt14
-rw-r--r--runtime/doc/deprecated.txt2
-rw-r--r--runtime/doc/dev_style.txt87
-rw-r--r--runtime/doc/develop.txt2
-rw-r--r--runtime/doc/diagnostic.txt14
-rw-r--r--runtime/doc/if_pyth.txt62
-rw-r--r--runtime/doc/intro.txt4
-rw-r--r--runtime/doc/job_control.txt16
-rw-r--r--runtime/doc/lsp-extension.txt4
-rw-r--r--runtime/doc/lsp.txt47
-rw-r--r--runtime/doc/lua.txt126
-rw-r--r--runtime/doc/luaref.txt410
-rw-r--r--runtime/doc/luvref.txt40
-rw-r--r--runtime/doc/nvim.txt14
-rw-r--r--runtime/doc/nvim_terminal_emulator.txt78
-rw-r--r--runtime/doc/provider.txt43
-rw-r--r--runtime/doc/term.txt18
-rw-r--r--runtime/doc/treesitter.txt10
-rw-r--r--runtime/doc/ui.txt6
-rw-r--r--runtime/doc/vim_diff.txt18
21 files changed, 528 insertions, 525 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 90dca81953..0eccb64517 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -51,7 +51,7 @@ Connecting to the socket is the easiest way a programmer can test the API,
which can be done through any msgpack-rpc client library or full-featured
|api-client|. Here's a Ruby script that prints "hello world!" in the current
Nvim instance:
->
+>ruby
#!/usr/bin/env ruby
# Requires msgpack-rpc: gem install msgpack-rpc
#
@@ -79,7 +79,7 @@ functions can be called interactively:
<
You can also embed Nvim via |jobstart()|, and communicate using |rpcrequest()|
and |rpcnotify()|:
->
+>vim
let nvim = jobstart(['nvim', '--embed'], {'rpc': v:true})
echo rpcrequest(nvim, 'nvim_eval', '"Hello " . "world!"')
call jobstop(nvim)
@@ -201,9 +201,9 @@ any of these approaches:
Example (requires Python "pyyaml" and "msgpack-python" modules): >
nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
<
- 3. Use the |api_info()| Vimscript function. >
+ 3. Use the |api_info()| Vimscript function. >vim
:lua print(vim.inspect(vim.fn.api_info()))
-< Example using |filter()| to exclude non-deprecated API functions: >
+< Example using |filter()| to exclude non-deprecated API functions: >vim
:new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
==============================================================================
@@ -361,10 +361,10 @@ callbacks. These callbacks are called frequently in various contexts;
receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline},
{new_lastline}, {old_byte_size} [, {old_utf32_size}, {old_utf16_size}]).
Unlike remote channel events the text contents are not passed. The new text can
-be accessed inside the callback as
-
- `vim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true)`
+be accessed inside the callback as >lua
+ vim.api.nvim_buf_get_lines(buf, firstline, new_lastline, true)
+<
{old_byte_size} is the total size of the replaced region {firstline} to
{lastline} in bytes, including the final newline after {lastline}. if
`utf_sizes` is set to true in |nvim_buf_attach()| keyword args, then the
@@ -400,7 +400,7 @@ performance can be improved by calling |nvim_buf_add_highlight()| as an
asynchronous notification, after first (synchronously) requesting a source id.
Example using the Python API client (|pynvim|):
->
+>python
src = vim.new_highlight_source()
buf = vim.current.buffer
for i in range(5):
@@ -414,7 +414,7 @@ clear highlights from a specific source, in a specific line range or the
entire buffer by passing in the line range 0, -1 (the latter is the default in
python as used above).
-Example using the API from Vimscript: >
+Example using the API from Vimscript: >vim
call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
@@ -438,7 +438,7 @@ Two ways to create a floating window:
To close it use |nvim_win_close()| or a command such as |:close|.
To check whether a window is floating, check whether the `relative` option in
-its config is non-empty: >
+its config is non-empty: >lua
if vim.api.nvim_win_get_config(window_id).relative ~= '' then
-- window with this window_id is floating
@@ -456,7 +456,7 @@ Currently, floating windows don't support some widgets like scrollbar.
The output of |:mksession| does not include commands for restoring floating
windows.
-Example: create a float with scratch buffer: >
+Example: create a float with scratch buffer: >vim
let buf = nvim_create_buf(v:false, v:true)
call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
@@ -510,19 +510,20 @@ Let's set an extmark at the first row (row=0) and third column (column=2).
01 2345678
0 ex|ample..
^ extmark position
-
+<
+>vim
let g:mark_ns = nvim_create_namespace('myplugin')
let g:mark_id = nvim_buf_set_extmark(0, g:mark_ns, 0, 2, {})
<
-We can get the mark by its id: >
+We can get the mark by its id: >vim
echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
- => [0, 2]
+ " => [0, 2]
-We can get all marks in a buffer by |namespace| (or by a range): >
+We can get all marks in a buffer by |namespace| (or by a range): >vim
echo nvim_buf_get_extmarks(0, g:mark_ns, 0, -1, {})
- => [[1, 0, 2]]
+ " => [[1, 0, 2]]
Deleting all surrounding text does NOT remove an extmark! To remove extmarks
use |nvim_buf_del_extmark()|. Deleting "x" in our example: >
@@ -530,9 +531,10 @@ use |nvim_buf_del_extmark()|. Deleting "x" in our example: >
0 12345678
0 e|ample..
^ extmark position
-
+<
+>vim
echo nvim_buf_get_extmark_by_id(0, g:mark_ns, g:mark_id, {})
- => [0, 1]
+ " => [0, 1]
<
Note: Extmark "gravity" decides how it will shift after a text edit.
See |nvim_buf_set_extmark()|
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index f4a17b1842..1c52b2d692 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -91,7 +91,7 @@ only bytes can be written to Nvim's own stderr.
There are two ways to deal with this:
- 1. To wait for the entire output, use |channel-buffered| mode.
- - 2. To read line-by-line, use the following code: >
+ - 2. To read line-by-line, use the following code: >vim
let s:lines = ['']
func! s:on_event(job_id, data, event) dict
let eof = (a:data == [''])
@@ -108,7 +108,7 @@ callbacks.
Data can be sent to the channel using the |chansend()| function. Here is a
simple example, echoing some data through a cat-process:
->
+>vim
function! s:OnEvent(id, data, event) dict
let str = join(a:data, "\n")
echomsg str
@@ -119,7 +119,7 @@ simple example, echoing some data through a cat-process:
Here is a example of setting a buffer to the result of grep, but only after
all data has been processed:
->
+>vim
function! s:OnEvent(id, data, event) dict
call nvim_buf_set_lines(2, 0, -1, v:true, a:data)
endfunction
@@ -142,7 +142,7 @@ However, change of PTY size can be signaled to the slave using |jobresize()|.
See also |terminal-emulator|.
Terminal characteristics (termios) for |:terminal| and PTY channels are copied
-from the host TTY, or if Nvim is |--headless| it uses default values: >
+from the host TTY, or if Nvim is |--headless| it uses default values: >vim
:echo system('nvim --headless +"te stty -a" +"sleep 1" +"1,/^$/print" +q')
==============================================================================
@@ -163,7 +163,7 @@ used as a channel. See also |--embed|.
Call |stdioopen()| during |startup| to open the stdio channel as |channel-id| 1.
Nvim's stderr is always available as |v:stderr|, a write-only bytes channel.
-Example: >
+Example: >vim
func! OnEvent(id, data, event)
if a:data == [""]
quit
@@ -172,7 +172,7 @@ Example: >
endfunc
call stdioopen({'on_stdin': 'OnEvent'})
<
-Put this in `uppercase.vim` and run: >
+Put this in `uppercase.vim` and run: >bash
nvim --headless --cmd "source uppercase.vim"
==============================================================================
@@ -223,7 +223,7 @@ start of the line.
Here is an example for Unix. It starts a shell in the background and prompts
for the next shell command. Output from the shell is displayed above the
-prompt. >
+prompt. >vim
" Function handling a line of text that has been typed.
func TextEntered(text)
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 401ac87d90..1bdd13ac0c 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -30,7 +30,7 @@ ENVIRONMENT VARIABLES
- detect a parent Nvim (use |$NVIM| instead)
- Ignored if --listen is given.
- Unset by |terminal| and |jobstart()| unless explicitly given by the "env"
- option. Example: >
+ option. Example: >vim
call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername } })
<
diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt
index 6afe2f7ee7..b96b01dbff 100644
--- a/runtime/doc/dev_style.txt
+++ b/runtime/doc/dev_style.txt
@@ -38,7 +38,7 @@ All header files should have `#define` guards to prevent multiple inclusion.
The format of the symbol name should be `NVIM_<DIRECTORY>_<FILE>_H`.
In foo/bar.h:
->
+>c
#ifndef NVIM_FOO_BAR_H
#define NVIM_FOO_BAR_H
@@ -71,7 +71,7 @@ C99 allows you to declare variables anywhere in a function. Declare them in as
local a scope as possible, and as close to the first use as possible. This
makes it easier for the reader to find the declaration and see what type the
variable is and what it was initialized to. In particular, initialization
-should be used instead of declaration and assignment, e.g. >
+should be used instead of declaration and assignment, e.g. >c
int i;
i = f(); // BAD: initialization separate from declaration.
@@ -110,7 +110,7 @@ Variable-length arrays can cause hard to detect stack overflows.
Postincrement and Postdecrement ~
-Use postfix form (`i++`) in statements. >
+Use postfix form (`i++`) in statements. >c
for (int i = 0; i < 3; i++) { }
int j = ++i; // OK: ++i is used as an expression.
@@ -136,7 +136,7 @@ Use `const` pointers whenever possible. Avoid `const` on non-pointer parameter d
before the "noun" (`int`).
That said, while we encourage putting `const` first, we do not require it.
- But be consistent with the code around you! >
+ But be consistent with the code around you! >c
void foo(const char *p, int i);
}
@@ -176,14 +176,14 @@ Type unsigned signed
Booleans ~
-Use `bool` to represent boolean values. >
+Use `bool` to represent boolean values. >c
int loaded = 1; // BAD: loaded should have type bool.
Conditions ~
-Don't use "yoda-conditions". Use at most one assignment per condition. >
+Don't use "yoda-conditions". Use at most one assignment per condition. >c
if (1 == x) {
@@ -196,7 +196,7 @@ Function declarations ~
Every function must not have a separate declaration.
-Function declarations are created by the gendeclarations.lua script. >
+Function declarations are created by the gendeclarations.lua script. >c
static void f(void);
@@ -209,7 +209,7 @@ Function declarations are created by the gendeclarations.lua script. >
General translation unit layout ~
The definitions of public functions precede the definitions of static
-functions. >
+functions. >c
<HEADER>
@@ -230,7 +230,7 @@ if .c file does not contain any static functions.
Included file name consists of the .c file name without extension, preceded by
the directory name relative to src/nvim. Name of the file containing static
functions declarations ends with `.c.generated.h`, `*.h.generated.h` files
-contain only non-static function declarations. >
+contain only non-static function declarations. >c
// src/nvim/foo.c file
#include <stddef.h>
@@ -274,7 +274,7 @@ comparisons, and structure alignment.
`#pragma pack()` and `__declspec(align())`.
- Use the `LL` or `ULL` suffixes as needed to create 64-bit constants. For
- example: >
+ example: >c
int64_t my_value = 0x123456789LL;
uint64_t my_mask = 3ULL << 48;
@@ -288,7 +288,7 @@ Use `sizeof(varname)` when you take the size of a particular variable.
`sizeof(varname)` will update appropriately if someone changes the variable
type either now or later. You may use `sizeof(type)` for code unrelated to any
particular variable, such as code that manages an external or internal data
-format where a variable of an appropriate C type is not convenient. >
+format where a variable of an appropriate C type is not convenient. >c
Struct data;
memset(&data, 0, sizeof(data));
@@ -324,7 +324,7 @@ Give as descriptive a name as possible, within reason. Do not worry about
saving horizontal space as it is far more important to make your code
immediately understandable by a new reader. Do not use abbreviations that are
ambiguous or unfamiliar to readers outside your project, and do not abbreviate
-by deleting letters within a word. >
+by deleting letters within a word. >c
int price_count_reader; // No abbreviation.
int num_errors; // "num" is a widespread convention.
@@ -361,7 +361,7 @@ Typedef-ed structs and enums start with a capital letter and have a capital
letter for each new word, with no underscores: `MyExcitingStruct`.
Non-Typedef-ed structs and enums are all lowercase with underscores between
-words: `struct my_exciting_struct` . >
+words: `struct my_exciting_struct` . >c
struct my_struct {
...
@@ -376,7 +376,7 @@ instance: `my_exciting_local_variable`.
Common Variable names ~
- For example: >
+ For example: >c
string table_name; // OK: uses underscore.
string tablename; // OK: all lowercase.
@@ -386,7 +386,7 @@ instance: `my_exciting_local_variable`.
Struct Variables ~
- Data members in structs should be named like regular variables. >
+ Data members in structs should be named like regular variables. >c
struct url_table_properties {
string name;
@@ -406,7 +406,7 @@ Use a `k` followed by mixed case: `kDaysInAWeek`.
All compile-time constants, whether they are declared locally or globally,
follow a slightly different naming convention from other variables. Use a `k`
-followed by words with uppercase first letters: >
+followed by words with uppercase first letters: >c
const int kDaysInAWeek = 7;
@@ -416,7 +416,7 @@ Function names are all lowercase, with underscores between words. For
instance: `my_exceptional_function()`. All functions in the same header file
should have a common prefix.
-In `os_unix.h`: >
+In `os_unix.h`: >c
void unix_open(const char *path);
void unix_user_id(void);
@@ -429,7 +429,7 @@ normal operation.
Enumerator Names ~
-Enumerators should be named like constants: `kEnumName`. >
+Enumerators should be named like constants: `kEnumName`. >c
enum url_table_errors {
kOK = 0,
@@ -440,7 +440,7 @@ Enumerators should be named like constants: `kEnumName`. >
Macro Names ~
-They're like this: `MY_MACRO_THAT_SCARES_CPP_DEVELOPERS`. >
+They're like this: `MY_MACRO_THAT_SCARES_CPP_DEVELOPERS`. >c
#define ROUND(x) ...
#define PI_ROUNDED 5.0
@@ -461,7 +461,7 @@ Nvim uses Doxygen comments.
Comment Style ~
-Use the `//`-style syntax only. >
+Use the `//`-style syntax only. >c
// This is a comment spanning
// multiple lines
@@ -489,7 +489,7 @@ Start each file with a description of its contents.
mention in the `.c` that the documentation is in the `.h` file.
Do not duplicate comments in both the `.h` and the `.c`. Duplicated
- comments diverge. >
+ comments diverge. >c
/// A brief description of this file.
///
@@ -500,7 +500,7 @@ Start each file with a description of its contents.
Struct Comments ~
Every struct definition should have accompanying comments that describes what
-it is for and how it should be used. >
+it is for and how it should be used. >c
/// Window info stored with a buffer.
///
@@ -522,7 +522,7 @@ it is for and how it should be used. >
};
If the field comments are short, you can also put them next to the field. But
-be consistent within one struct, and follow the necessary doxygen style. >
+be consistent within one struct, and follow the necessary doxygen style. >c
struct wininfo_S {
WinInfo *wi_next; ///< Next entry or NULL for last entry.
@@ -560,8 +560,7 @@ of a function describe operation.
- If the function allocates memory that the caller must free.
- Whether any of the arguments can be a null pointer.
- If there are any performance implications of how a function is used.
- - If the function is re-entrant. What are its synchronization assumptions?
- >
+ - If the function is re-entrant. What are its synchronization assumptions? >c
/// Brief description of the function.
///
/// Detailed description.
@@ -589,7 +588,7 @@ of a function describe operation.
Note you should not just repeat the comments given with the function
declaration, in the `.h` file or wherever. It's okay to recapitulate
briefly what the function does, but the focus of the comments should be on
- how it does it. >
+ how it does it. >c
// Note that we don't use Doxygen comments here.
Iterator *get_iterator(void *arg1, void *arg2)
@@ -607,7 +606,7 @@ comments are required.
Global Variables ~
All global variables should have a comment describing what they are and
- what they are used for. For example: >
+ what they are used for. For example: >c
/// The total number of tests cases that we run
/// through in this regression test.
@@ -623,7 +622,7 @@ interesting, or important parts of your code.
Also, lines that are non-obvious should get a comment at the end of the
line. These end-of-line comments should be separated from the code by 2
- spaces. Example: >
+ spaces. Example: >c
// If we have enough memory, mmap the data portion too.
mmap_budget = max<int64>(0, mmap_budget - index_->length());
@@ -636,7 +635,7 @@ interesting, or important parts of your code.
function returns.
If you have several comments on subsequent lines, it can often be more
- readable to line them up: >
+ readable to line them up: >c
do_something(); // Comment here so the comments line up.
do_something_else_that_is_longer(); // Comment here so there are two spaces between
@@ -652,7 +651,7 @@ interesting, or important parts of your code.
When you pass in a null pointer, boolean, or literal integer values to
functions, you should consider adding a comment about what they are, or
make your code self-documenting by using constants. For example, compare:
- >
+ >c
bool success = calculate_something(interesting_value,
10,
@@ -660,7 +659,7 @@ interesting, or important parts of your code.
NULL); // What are these arguments??
<
- versus: >
+ versus: >c
bool success = calculate_something(interesting_value,
10, // Default base value.
@@ -668,7 +667,7 @@ interesting, or important parts of your code.
NULL); // No callback.
<
- Or alternatively, constants or self-describing variables: >
+ Or alternatively, constants or self-describing variables: >c
const int kDefaultBaseValue = 10;
const bool kFirstTimeCalling = false;
@@ -683,7 +682,7 @@ interesting, or important parts of your code.
Note that you should never describe the code itself. Assume that the
person reading the code knows C better than you do, even though he or she
- does not know what you are trying to do: >
+ does not know what you are trying to do: >c
// Now go through the b array and make sure that if i occurs,
// the next element is i+1.
@@ -718,7 +717,7 @@ about the problem referenced by the `TODO`. The main purpose is to have a
consistent `TODO` format that can be searched to find the person who can
provide more details upon request. A `TODO` is not a commitment that the
person referenced will fix the problem. Thus when you create a `TODO`, it is
-almost always your name that is given. >
+almost always your name that is given. >c
// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
// TODO(Zeke): change this to use relations.
@@ -786,19 +785,19 @@ Function Calls ~
On one line if it fits; otherwise, wrap arguments at the parenthesis.
-Function calls have the following format: >
+Function calls have the following format: >c
bool retval = do_something(argument1, argument2, argument3);
If the arguments do not all fit on one line, they should be broken up onto
multiple lines, with each subsequent line aligned with the first argument. Do
-not add spaces after the open paren or before the close paren: >
+not add spaces after the open paren or before the close paren: >c
bool retval = do_something(averyveryveryverylongargument1,
argument2, argument3);
If the function has many arguments, consider having one per line if this makes
-the code more readable: >
+the code more readable: >c
bool retval = do_something(argument1,
argument2,
@@ -806,7 +805,7 @@ the code more readable: >
argument4);
Arguments may optionally all be placed on subsequent lines, with one line per
-argument: >
+argument: >c
if (...) {
...
@@ -830,7 +829,7 @@ place but with one space after the `{` and one space before the `}`
If the braced list follows a name (e.g. a type or variable name), format as if
the `{}` were the parentheses of a function call with that name. If there is
-no name, assume a zero-length name. >
+no name, assume a zero-length name. >c
struct my_struct m = { // Here, you could also break before {.
superlongvariablename1,
@@ -847,7 +846,7 @@ Annotate non-trivial fall-through between cases.
If not conditional on an enumerated value, switch statements should always
have a `default` case (in the case of an enumerated value, the compiler will
warn you if any values are not handled). If the default case should never
-execute, simply `assert`: >
+execute, simply `assert`: >c
switch (var) {
case 0:
@@ -865,7 +864,7 @@ Return Values ~
Do not needlessly surround the `return` expression with parentheses.
Use parentheses in `return expr`; only where you would use them in `x =
-expr;`. >
+expr;`. >c
return result;
return (some_long_condition && another_condition);
@@ -879,12 +878,12 @@ Horizontal Whitespace ~
Use of horizontal whitespace depends on location.
General ~
->
+>c
int x[] = { 0 }; // Spaces inside braces for braced-init-list.
<
Variables ~
->
+>c
int long_variable = 0; // Don't align assignments.
int i = 1;
@@ -901,7 +900,7 @@ Use of horizontal whitespace depends on location.
Operators ~
->
+>c
x = 0; // Assignment operators always have spaces around
// them.
x = -5; // No spaces separating unary operators and their
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 1ba6ae757b..6862426b1b 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -119,7 +119,7 @@ reflects whether Python support is working.
*provider-reload*
Sometimes a GUI or other application may want to force a provider to
"reload". To reload a provider, undefine its "loaded" flag, then use
-|:runtime| to reload it: >
+|:runtime| to reload it: >vim
:unlet g:loaded_clipboard_provider
:runtime autoload/provider/clipboard.vim
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 07a7d5190f..56c2af10b4 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -68,11 +68,11 @@ The "severity" key in a diagnostic is one of the values defined in
Functions that take a severity as an optional parameter (e.g.
|vim.diagnostic.get()|) accept one of two forms:
-1. A single |vim.diagnostic.severity| value: >
+1. A single |vim.diagnostic.severity| value: >lua
vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN })
-2. A table with a "min" or "max" key (or both): >
+2. A table with a "min" or "max" key (or both): >lua
vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } })
@@ -107,7 +107,7 @@ Nvim provides these handlers by default: "virtual_text", "signs", and
*diagnostic-handlers-example*
The example below creates a new handler that notifies the user of diagnostics
-with |vim.notify()|: >
+with |vim.notify()|: >lua
-- It's good practice to namespace custom handlers to avoid collisions
vim.diagnostic.handlers["my/notify"] = {
@@ -135,7 +135,7 @@ In this example, there is nothing to do when diagnostics are hidden, so we
omit the "hide" function.
Existing handlers can be overridden. For example, use the following to only
-show a sign for the highest severity diagnostic on a given line: >
+show a sign for the highest severity diagnostic on a given line: >lua
-- Create a custom namespace. This will aggregate signs from all other
-- namespaces and only show the one with the highest severity on a
@@ -185,7 +185,7 @@ own default highlight groups.
For example, the default highlighting for |hl-DiagnosticSignError| is linked
to |hl-DiagnosticError|. To change the default (and therefore the linked
-highlights), use the |:highlight| command: >
+highlights), use the |:highlight| command: >vim
highlight DiagnosticError guifg="BrightRed"
<
@@ -279,7 +279,7 @@ SIGNS *diagnostic-signs*
Signs are defined for each diagnostic severity. The default text for each sign
is the first letter of the severity name (for example, "E" for ERROR). Signs
-can be customized using the following: >
+can be customized using the following: >vim
sign define DiagnosticSignError text=E texthl=DiagnosticSignError linehl= numhl=
sign define DiagnosticSignWarn text=W texthl=DiagnosticSignWarn linehl= numhl=
@@ -299,7 +299,7 @@ DiagnosticChanged After diagnostics have changed. When used from Lua,
the new diagnostics are passed to the autocmd
callback in the "data" table.
-Example: >
+Example: >lua
vim.api.nvim_create_autocmd('DiagnosticChanged', {
callback = function(args)
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index 9b434e61d7..4c184ddf94 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -16,7 +16,7 @@ Commands *python-commands*
*:python* *:py* *E263* *E264* *E887*
:[range]py[thon] {stmt}
Execute Python statement {stmt}. A simple check if
- the `:python` command is working: >
+ the `:python` command is working: >vim
:python print "Hello"
:[range]py[thon] << [endmarker]
@@ -31,7 +31,7 @@ The {endmarker} below the {script} must NOT be preceded by any white space.
If [endmarker] is omitted from after the "<<", a dot '.' must be used after
{script}, like for the |:append| and |:insert| commands.
-Example: >
+Example: >vim
function! IcecreamInitialize()
python << EOF
class StrawberryIcecream:
@@ -40,7 +40,7 @@ Example: >
EOF
endfunction
-To see what version of Python you have: >
+To see what version of Python you have: >vim
:python print(sys.version)
There is no need to "import sys", it's done by default.
@@ -64,12 +64,12 @@ Note: Python is very sensitive to indenting. Make sure the "class" line and
is the whole file: "1,$".
Examples:
->
+>vim
:pydo return "%s\t%d" % (line[::-1], len(line))
:pydo if line: return "%4d: %s" % (linenr, line)
<
One can use `:pydo` in possible conjunction with `:py` to filter a range using
-python. For example: >
+python. For example: >vim
:py3 << EOF
needle = vim.eval('@a')
@@ -94,12 +94,13 @@ In the case of :pyfile, the code to execute is the contents of the given file.
Python commands cannot be used in the |sandbox|.
-To pass arguments you need to set sys.argv[] explicitly. Example: >
+To pass arguments you need to set sys.argv[] explicitly. Example: >vim
:python sys.argv = ["foo", "bar"]
:pyfile myscript.py
-Here are some examples *python-examples* >
+Here are some examples *python-examples*
+>vim
:python from vim import *
:python from string import upper
@@ -113,7 +114,7 @@ to the next, just like the Python REPL.
*script-here*
When using a script language in-line, you might want to skip this when the
language isn't supported. Note that this mechanism doesn't work:
->
+>vim
if has('python')
python << EOF
this will NOT work!
@@ -121,7 +122,7 @@ language isn't supported. Note that this mechanism doesn't work:
endif
Instead, put the Python command in a function and call that function:
->
+>vim
if has('python')
function DefPython()
python << EOF
@@ -139,10 +140,10 @@ The vim module *python-vim*
Python code gets all of its access to vim (with one exception - see
|python-output| below) via the "vim" module. The vim module implements two
methods, three constants, and one error object. You need to import the vim
-module before using it: >
+module before using it: >vim
:python import vim
-Overview >
+Overview >vim
:py print "Hello" # displays a message
:py vim.command(cmd) # execute an Ex command
:py w = vim.windows[n] # gets window "n"
@@ -166,10 +167,10 @@ Methods of the "vim" module
vim.command(str) *python-command*
Executes the vim (ex-mode) command str. Returns None.
- Examples: >
+ Examples: >vim
:py vim.command("set tw=72")
:py vim.command("%s/aaa/bbb/g")
-< The following definition executes Normal mode commands: >
+< The following definition executes Normal mode commands: >python
def normal(str):
vim.command("normal "+str)
# Note the use of single quotes to delimit a string containing
@@ -177,7 +178,7 @@ vim.command(str) *python-command*
normal('"a2dd"aP')
< *E659*
The ":python" command cannot be used recursively with Python 2.2 and
- older. This only works with Python 2.3 and later: >
+ older. This only works with Python 2.3 and later: >vim
:py vim.command("python print 'Hello again Python'")
vim.eval(str) *python-eval*
@@ -187,7 +188,7 @@ vim.eval(str) *python-eval*
- a list if the Vim expression evaluates to a Vim list
- a dictionary if the Vim expression evaluates to a Vim dictionary
Dictionaries and lists are recursively expanded.
- Examples: >
+ Examples: >vim
:py text_width = vim.eval("&tw")
:py str = vim.eval("12+12") # NB result is a string! Use
# string.atoi() to convert to
@@ -215,7 +216,7 @@ Error object of the "vim" module
vim.error *python-error*
Upon encountering a Vim error, Python raises an exception of type
vim.error.
- Example: >
+ Example: >python
try:
vim.command("put a")
except vim.error:
@@ -229,7 +230,7 @@ Constants of the "vim" module
vim.buffers *python-buffers*
A mapping object providing access to the list of vim buffers. The
- object supports the following operations: >
+ object supports the following operations: >vim
:py b = vim.buffers[i] # Indexing (read-only)
:py b in vim.buffers # Membership test
:py n = len(vim.buffers) # Number of elements
@@ -237,7 +238,7 @@ vim.buffers *python-buffers*
<
vim.windows *python-windows*
A sequence object providing access to the list of vim windows. The
- object supports the following operations: >
+ object supports the following operations: >vim
:py w = vim.windows[i] # Indexing (read-only)
:py w in vim.windows # Membership test
:py n = len(vim.windows) # Number of elements
@@ -251,7 +252,7 @@ vim.windows *python-windows*
vim.tabpages *python-tabpages*
A sequence object providing access to the list of vim tab pages. The
- object supports the following operations: >
+ object supports the following operations: >vim
:py t = vim.tabpages[i] # Indexing (read-only)
:py t in vim.tabpages # Membership test
:py n = len(vim.tabpages) # Number of elements
@@ -277,7 +278,7 @@ vim.current *python-current*
switching to given buffer, window or tab page. It is the only way to
switch UI objects in python: you can't assign to
|python-tabpage|.window attribute. To switch without triggering
- autocommands use >
+ autocommands use >vim
py << EOF
saved_eventignore = vim.options['eventignore']
vim.options['eventignore'] = 'all'
@@ -330,7 +331,7 @@ the list of paths found in 'runtimepath': with this directory in sys.path and
vim.path_hooks in sys.path_hooks python will try to load module from
{rtp}/python3 and {rtp}/pythonx for each {rtp} found in 'runtimepath'.
-Implementation is similar to the following, but written in C: >
+Implementation is similar to the following, but written in C: >python
from imp import find_module, load_module
import vim
@@ -461,12 +462,12 @@ The buffer object methods are:
numbers s and e |inclusive|.
Note that when adding a line it must not contain a line break character '\n'.
-A trailing '\n' is allowed and ignored, so that you can do: >
+A trailing '\n' is allowed and ignored, so that you can do: >vim
:py b.append(f.readlines())
Buffer object type is available using "Buffer" attribute of vim module.
-Examples (assume b is the current buffer) >
+Examples (assume b is the current buffer) >vim
:py print b.name # write the buffer file name
:py b[0] = "hello!!!" # replace the top line
:py b[:] = None # delete the whole buffer
@@ -605,10 +606,10 @@ variants explicitly if Python 3 is required.
{script}
{endmarker}
The `:py3` and `:python3` commands work similar to `:python`. A
- simple check if the `:py3` command is working: >
+ simple check if the `:py3` command is working: >vim
:py3 print("Hello")
<
- To see what version of Python you have: >
+ To see what version of Python you have: >vim
:py3 import sys
:py3 print(sys.version)
< *:py3file*
@@ -619,11 +620,12 @@ variants explicitly if Python 3 is required.
The `:py3do` command works similar to `:pydo`.
*E880*
-Raising SystemExit exception in python isn't endorsed way to quit vim, use: >
+Raising SystemExit exception in python isn't endorsed way to quit vim, use:
+>vim
:py vim.command("qall!")
<
*has-python*
-You can test if Python is available with: >
+You can test if Python is available with: >vim
if has('pythonx')
echo 'there is Python'
endif
@@ -642,10 +644,10 @@ works with Python 2.6+ and Python 3. As Nvim only supports Python 3,
all these commands are now synonymous to their "python3" equivalents.
*:pyx* *:pythonx*
-`:pyx` and `:pythonx` work the same as `:python3`. To check if `:pyx` works: >
+`:pyx` and `:pythonx` work the same as `:python3`. To check if `:pyx` works: >vim
:pyx print("Hello")
-To see what version of Python is being used: >
+To see what version of Python is being used: >vim
:pyx import sys
:pyx print(sys.version)
<
@@ -656,7 +658,7 @@ To see what version of Python is being used: >
`:pyxdo` works the same as `:py3do`.
*has-pythonx*
-To check if `pyx*` functions and commands are available: >
+To check if `pyx*` functions and commands are available: >vim
if has('pythonx')
echo 'pyx* commands are available. (Python ' .. &pyx .. ')'
endif
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index 348c56ba70..4722982ab5 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -408,12 +408,12 @@ the ":map" command. The rules are:
The <> notation uses <lt> to escape the special meaning of key names. Using a
backslash also works, but only when 'cpoptions' does not include the 'B' flag.
-Examples for mapping CTRL-H to the six characters "<Home>": >
+Examples for mapping CTRL-H to the six characters "<Home>": >vim
:imap <C-H> \<Home>
:imap <C-H> <lt>Home>
The first one only works when the 'B' flag is not in 'cpoptions'. The second
one always works.
-To get a literal "<lt>" in a mapping: >
+To get a literal "<lt>" in a mapping: >vim
:map <C-L> <lt>lt>
The notation can be used in a double quoted strings, using "\<" at the start,
diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt
index 6a9d865c40..37a4e2ebb1 100644
--- a/runtime/doc/job_control.txt
+++ b/runtime/doc/job_control.txt
@@ -30,7 +30,7 @@ Usage *job-control-usage*
To control jobs, use the "job…" family of functions: |jobstart()|,
|jobstop()|, etc.
-Example: >
+Example: >vim
function! s:OnEvent(job_id, data, event) dict
if a:event == 'stdout'
@@ -51,7 +51,7 @@ Example: >
let job1 = jobstart(['bash'], extend({'shell': 'shell 1'}, s:callbacks))
let job2 = jobstart(['bash', '-c', 'for i in {1..10}; do echo hello $i!; sleep 1; done'], extend({'shell': 'shell 2'}, s:callbacks))
-To test the above script, copy it to a file ~/foo.vim and run it: >
+To test the above script, copy it to a file ~/foo.vim and run it: >bash
nvim -u ~/foo.vim
<
Description of what happens:
@@ -75,7 +75,7 @@ Arguments passed to on_exit callback:
will not trigger the on_stdout/on_stderr callback (but if the process
ends, the on_exit callback will be invoked).
For example, "ruby -e" buffers output, so small strings will be
- buffered unless "auto-flushing" ($stdout.sync=true) is enabled. >
+ buffered unless "auto-flushing" ($stdout.sync=true) is enabled. >vim
function! Receive(job_id, data, event)
echom printf('%s: %s',a:event,string(a:data))
endfunction
@@ -92,7 +92,7 @@ Arguments passed to on_exit callback:
- `abc\nefg` may arrive as `['abc', '']`, `['efg']` or `['abc']`,
`['','efg']`, or even `['ab']`, `['c','efg']`.
Easy way to deal with this: initialize a list as `['']`, then append
- to it as follows: >
+ to it as follows: >vim
let s:chunks = ['']
func! s:on_stdout(job_id, data, event) dict
let s:chunks[-1] .= a:data[0]
@@ -101,7 +101,7 @@ Arguments passed to on_exit callback:
<
The |jobstart-options| dictionary is passed as |self| to the callback.
-The above example could be written in this "object-oriented" style: >
+The above example could be written in this "object-oriented" style: >vim
let Shell = {}
@@ -129,16 +129,16 @@ The above example could be written in this "object-oriented" style: >
let instance = Shell.new('bomb',
\ 'for i in $(seq 9 -1 1); do echo $i 1>&$((i % 2 + 1)); sleep 1; done')
<
-To send data to the job's stdin, use |chansend()|: >
+To send data to the job's stdin, use |chansend()|: >vim
:call chansend(job1, "ls\n")
:call chansend(job1, "invalid-command\n")
:call chansend(job1, "exit\n")
<
-A job may be killed with |jobstop()|: >
+A job may be killed with |jobstop()|: >vim
:call jobstop(job1)
<
A job may be killed at any time with the |jobstop()| function:
->
+>vim
:call jobstop(job1)
<
Individual streams can be closed without killing the job, see |chanclose()|.
diff --git a/runtime/doc/lsp-extension.txt b/runtime/doc/lsp-extension.txt
index 6e9ad940c7..fe72e9eb18 100644
--- a/runtime/doc/lsp-extension.txt
+++ b/runtime/doc/lsp-extension.txt
@@ -6,7 +6,7 @@
The `vim.lsp` Lua module is a framework for building LSP plugins.
1. Start with |vim.lsp.start_client()| and |vim.lsp.buf_attach_client()|.
- 2. Peek at the API: >
+ 2. Peek at the API: >vim
:lua print(vim.inspect(vim.lsp))
< 3. See |lsp-extension-example| for a full example.
@@ -30,7 +30,7 @@ The example will:
3. Create a new LSP for that root directory if one doesn't exist.
4. Attach the buffer to the client for that root directory.
->
+>lua
-- Some path manipulation utilities
local function is_dir(filename)
local stat = vim.loop.fs_stat(filename)
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index d9b944bfe2..06c0f466e7 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -33,7 +33,7 @@ Follow these steps to get LSP features:
2. Configure the LSP client per language server.
A minimal example:
->
+>lua
vim.lsp.start({
name = 'my-server-name',
cmd = {'name-of-language-server-executable'},
@@ -44,7 +44,7 @@ Follow these steps to get LSP features:
3. Configure keymaps and autocmds to utilize LSP features.
See |lsp-config|.
-<
+
*lsp-config*
Starting a LSP client will automatically report diagnostics via
@@ -66,7 +66,7 @@ language server supports the functionality.
To use other LSP features like hover, rename, etc. you can setup some
additional keymaps. It's recommended to setup them in a |LspAttach| autocmd to
ensure they're only active if there is a LSP client running. An example:
->
+>lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
@@ -86,7 +86,7 @@ The most used functions are:
Not all language servers provide the same capabilities. To ensure you only set
keymaps if the language server supports a feature, you can guard the keymap
calls behind capability checks:
->
+>lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
local client = vim.lsp.get_client_by_id(args.data.client_id)
@@ -100,7 +100,7 @@ calls behind capability checks:
To learn what capabilities are available you can run the following command in
a buffer with a started LSP client:
->
+>vim
:lua =vim.lsp.get_active_clients()[1].server_capabilities
<
@@ -110,14 +110,14 @@ Full list of features provided by default can be found in |lsp-buf|.
FAQ *lsp-faq*
- Q: How to force-reload LSP?
- A: Stop all clients, then reload the buffer. >
+ A: Stop all clients, then reload the buffer. >vim
:lua vim.lsp.stop_client(vim.lsp.get_active_clients())
:edit
- Q: Why isn't completion working?
A: In the buffer where you want to use LSP, check that 'omnifunc' is set to
- "v:lua.vim.lsp.omnifunc": >
+ "v:lua.vim.lsp.omnifunc": >vim
:verbose set omnifunc?
@@ -129,7 +129,7 @@ FAQ *lsp-faq*
A: Check if the function has an `async` parameter and set the value to
false.
- E.g. code formatting: >
+ E.g. code formatting: >vim
" Auto-format *.rs (rust) files prior to saving them
" (async = false is the default for format)
@@ -162,7 +162,7 @@ to the given buffer. |lsp-buf|
LSP request/response handlers are implemented as Lua functions (see
|lsp-handler|). The |vim.lsp.handlers| table defines default handlers used
-when creating a new client. Keys are LSP method names: >
+when creating a new client. Keys are LSP method names: >vim
:lua print(vim.inspect(vim.tbl_keys(vim.lsp.handlers)))
<
@@ -291,7 +291,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
To configure the behavior of |vim.lsp.diagnostic.on_publish_diagnostics()|,
consider the following example, where a new |lsp-handler| is created using
- |vim.lsp.with()| that no longer generates signs for the diagnostics: >
+ |vim.lsp.with()| that no longer generates signs for the diagnostics: >lua
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -301,7 +301,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
)
<
To enable signs, use |vim.lsp.with()| again to create and assign a new
- |lsp-handler| to |vim.lsp.handlers| for the associated method: >
+ |lsp-handler| to |vim.lsp.handlers| for the associated method: >lua
vim.lsp.handlers["textDocument/publishDiagnostics"] = vim.lsp.with(
vim.lsp.diagnostic.on_publish_diagnostics, {
@@ -311,7 +311,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
)
<
To configure a handler on a per-server basis, you can use the {handlers} key
- for |vim.lsp.start_client()| >
+ for |vim.lsp.start_client()| >lua
vim.lsp.start_client {
..., -- Other configuration omitted.
@@ -325,7 +325,8 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
},
}
<
- or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`: >
+ or if using 'nvim-lspconfig', you can use the {handlers} key of `setup()`:
+ >lua
require('lspconfig').rust_analyzer.setup {
handlers = {
@@ -340,7 +341,7 @@ To configure the behavior of a builtin |lsp-handler|, the convenient method
<
Some handlers do not have an explicitly named handler function (such as
||vim.lsp.diagnostic.on_publish_diagnostics()|). To override these, first
- create a reference to the existing handler: >
+ create a reference to the existing handler: >lua
local on_references = vim.lsp.handlers["textDocument/references"]
vim.lsp.handlers["textDocument/references"] = vim.lsp.with(
@@ -357,14 +358,14 @@ Handlers can be set by:
vim.lsp.handlers is a global table that contains the default mapping of
|lsp-method| names to |lsp-handlers|.
- To override the handler for the `"textDocument/definition"` method: >
+ To override the handler for the `"textDocument/definition"` method: >lua
vim.lsp.handlers["textDocument/definition"] = my_custom_default_definition
<
- The {handlers} parameter for |vim.lsp.start_client()|.
This will set the |lsp-handler| as the default handler for this server.
- For example: >
+ For example: >lua
vim.lsp.start_client {
..., -- Other configuration omitted.
@@ -376,7 +377,7 @@ Handlers can be set by:
- The {handler} parameter for |vim.lsp.buf_request()|.
This will set the |lsp-handler| ONLY for the current request.
- For example: >
+ For example: >lua
vim.lsp.buf_request(
0,
@@ -403,7 +404,7 @@ and helper functions for creating protocol-related objects.
https://github.com/microsoft/language-server-protocol/raw/gh-pages/_specifications/specification-3-14.md
For example `vim.lsp.protocol.ErrorCodes` allows reverse lookup by number or
-name: >
+name: >lua
vim.lsp.protocol.TextDocumentSyncKind.Full == 1
vim.lsp.protocol.TextDocumentSyncKind[1] == "Full"
@@ -426,7 +427,7 @@ For the format of the notification message, see:
- `context` table|nil. `ctx` from |lsp-handler|
This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
->
+>lua
local function on_list(options)
vim.fn.setqflist({}, ' ', options)
vim.api.nvim_command('cfirst')
@@ -436,7 +437,7 @@ This table can be used with vim.fn.setqflist or vim.fn.setloclist. E.g.:
vim.lsp.buf.references(nil, {on_list=on_list})
<
If you prefer loclist do something like this:
->
+>lua
local function on_list(options)
vim.fn.setloclist(0, {}, ' ', options)
vim.api.nvim_command('lopen')
@@ -487,7 +488,7 @@ EVENTS *lsp-events*
*LspAttach*
After an LSP client attaches to a buffer. The |autocmd-pattern| is the
name of the buffer. When used from Lua, the client ID is passed to the
-callback in the "data" table. Example: >
+callback in the "data" table. Example: >lua
vim.api.nvim_create_autocmd("LspAttach", {
callback = function(args)
@@ -505,7 +506,7 @@ callback in the "data" table. Example: >
*LspDetach*
Just before an LSP client detaches from a buffer. The |autocmd-pattern| is the
name of the buffer. When used from Lua, the client ID is passed to the
-callback in the "data" table. Example: >
+callback in the "data" table. Example: >lua
vim.api.nvim_create_autocmd("LspDetach", {
callback = function(args)
@@ -525,7 +526,7 @@ LspRequest *LspRequest*
After a change to the active set of pending LSP requests. See {requests}
in |vim.lsp.client|.
-Example: >
+Example: >vim
autocmd User LspProgressUpdate redrawstatus
autocmd User LspRequest redrawstatus
<
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 93471b50ad..1c381bd956 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -361,17 +361,17 @@ Vimscript v:lua interface *v:lua-call*
From Vimscript the special `v:lua` prefix can be used to call Lua functions
which are global or accessible from global tables. The expression >vim
- v:lua.func(arg1, arg2)
+ call v:lua.func(arg1, arg2)
is equivalent to the Lua chunk >lua
return func(...)
where the args are converted to Lua values. The expression >vim
- v:lua.somemod.func(args)
+ call v:lua.somemod.func(args)
is equivalent to the Lua chunk >lua
return somemod.func(...)
In addition, functions of packages can be accessed like >vim
- v:lua.require'mypack'.func(arg1, arg2)
- v:lua.require'mypack.submod'.func(arg1, arg2)
+ call v:lua.require'mypack'.func(arg1, arg2)
+ call v:lua.require'mypack.submod'.func(arg1, arg2)
Note: Only single quote form without parens is allowed. Using
`require"mypack"` or `require('mypack')` as prefixes do NOT work (the latter
is still valid as a function call of itself, in case require returns a useful
@@ -379,7 +379,7 @@ value).
The `v:lua` prefix may be used to call Lua functions as |method|s. For
example: >vim
- arg1->v:lua.somemod.func(arg2)
+ :eval arg1->v:lua.somemod.func(arg2)
<
You can use `v:lua` in "func" options like 'tagfunc', 'omnifunc', etc.
For example consider the following Lua omnifunc handler: >lua
@@ -646,20 +646,19 @@ vim.diff({a}, {b}, {opts}) *vim.diff()*
Run diff on strings {a} and {b}. Any indices returned by this function,
either directly or via callback arguments, are 1-based.
- Examples: >
-
+ Examples: >lua
vim.diff('a\n', 'b\nc\n')
- =>
- @@ -1 +1,2 @@
- -a
- +b
- +c
+ -- =>
+ -- @@ -1 +1,2 @@
+ -- -a
+ -- +b
+ -- +c
vim.diff('a\n', 'b\nc\n', {result_type = 'indices'})
- =>
- {
- {1, 1, 1, 2}
- }
+ -- =>
+ -- {
+ -- {1, 1, 1, 2}
+ -- }
<
Parameters: ~
• {a} First string to compare
@@ -730,13 +729,12 @@ vim.spell.check({str}) *vim.spell.check()*
'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to
the buffer. Consider calling this with |nvim_buf_call()|.
- Example: >
-
+ Example: >lua
vim.spell.check("the quik brown fox")
- =>
- {
- {'quik', 'bad', 4}
- }
+ -- =>
+ -- {
+ -- {'quik', 'bad', 4}
+ -- }
<
Parameters: ~
• {str} String to spell check.
@@ -1171,37 +1169,37 @@ offers object-oriented method for adding and removing entries.
Examples: ~
The following methods of setting a list-style option are equivalent:
- In Vimscript:
- `set wildignore=*.o,*.a,__pycache__`
-
- In Lua using `vim.o`:
- `vim.o.wildignore = '*.o,*.a,__pycache__'`
-
- In Lua using `vim.opt`:
- `vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }`
-
- To replicate the behavior of |:set+=|, use: >
+ In Vimscript: >vim
+ set wildignore=*.o,*.a,__pycache__
+<
+ In Lua using `vim.o`: >lua
+ vim.o.wildignore = '*.o,*.a,__pycache__'
+<
+ In Lua using `vim.opt`: >lua
+ vim.opt.wildignore = { '*.o', '*.a', '__pycache__' }
+<
+ To replicate the behavior of |:set+=|, use: >lua
vim.opt.wildignore:append { "*.pyc", "node_modules" }
<
- To replicate the behavior of |:set^=|, use: >
+ To replicate the behavior of |:set^=|, use: >lua
vim.opt.wildignore:prepend { "new_first_value" }
<
- To replicate the behavior of |:set-=|, use: >
+ To replicate the behavior of |:set-=|, use: >lua
vim.opt.wildignore:remove { "node_modules" }
<
The following methods of setting a map-style option are equivalent:
- In Vimscript:
- `set listchars=space:_,tab:>~`
-
- In Lua using `vim.o`:
- `vim.o.listchars = 'space:_,tab:>~'`
-
- In Lua using `vim.opt`:
- `vim.opt.listchars = { space = '_', tab = '>~' }`
-
+ In Vimscript: >vim
+ set listchars=space:_,tab:>~
+<
+ In Lua using `vim.o`: >lua
+ vim.o.listchars = 'space:_,tab:>~'
+<
+ In Lua using `vim.opt`: >lua
+ vim.opt.listchars = { space = '_', tab = '>~' }
+<
Note that |vim.opt| returns an `Option` object, not the value of the option,
which is accessed through |vim.opt:get()|:
@@ -1209,15 +1207,15 @@ which is accessed through |vim.opt:get()|:
Examples: ~
The following methods of getting a list-style option are equivalent:
- In Vimscript:
- `echo wildignore`
-
- In Lua using `vim.o`:
- `print(vim.o.wildignore)`
-
- In Lua using `vim.opt`:
- `vim.pretty_print(vim.opt.wildignore:get())`
-
+ In Vimscript: >vim
+ echo wildignore
+<
+ In Lua using `vim.o`: >lua
+ print(vim.o.wildignore)
+<
+ In Lua using `vim.opt`: >lua
+ vim.pretty_print(vim.opt.wildignore:get())
+<
In any of the above examples, to replicate the behavior |:setlocal|, use
`vim.opt_local`. Additionally, to replicate the behavior of |:setglobal|, use
@@ -1272,28 +1270,28 @@ Option:append(value)
Append a value to string-style options. See |:set+=|
- These are equivalent:
- `vim.opt.formatoptions:append('j')`
- `vim.opt.formatoptions = vim.opt.formatoptions + 'j'`
-
+ These are equivalent: >lua
+ vim.opt.formatoptions:append('j')
+ vim.opt.formatoptions = vim.opt.formatoptions + 'j'
+<
*vim.opt:prepend()*
Option:prepend(value)
Prepend a value to string-style options. See |:set^=|
- These are equivalent:
- `vim.opt.wildignore:prepend('*.o')`
- `vim.opt.wildignore = vim.opt.wildignore ^ '*.o'`
-
+ These are equivalent: >lua
+ vim.opt.wildignore:prepend('*.o')
+ vim.opt.wildignore = vim.opt.wildignore ^ '*.o'
+<
*vim.opt:remove()*
Option:remove(value)
Remove a value from string-style options. See |:set-=|
- These are equivalent:
- `vim.opt.wildignore:remove('*.pyc')`
- `vim.opt.wildignore = vim.opt.wildignore - '*.pyc'`
-
+ These are equivalent: >lua
+ vim.opt.wildignore:remove('*.pyc')
+ vim.opt.wildignore = vim.opt.wildignore - '*.pyc'
+<
==============================================================================
Lua module: vim *lua-vim*
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
index 259f2ba681..aafdd5c43e 100644
--- a/runtime/doc/luaref.txt
+++ b/runtime/doc/luaref.txt
@@ -136,7 +136,7 @@ For convenience, when the opening long bracket is immediately followed by a
newline, the newline is not included in the string. As an example, in a system
using ASCII (in which `a` is coded as 97, newline is coded as 10, and `1` is
coded as 49), the five literals below denote the same string:
->
+>lua
a = 'alo\n123"'
a = "alo\n123\""
a = '\97lo\10\04923"'
@@ -283,7 +283,7 @@ library; see |luaref-libDebug|.)
An access to a global variable `x` is equivalent to `_env.x`, which in turn is
equivalent to
->
+>lua
gettable_event(_env, "x")
<
where `_env` is the environment of the running function. (The `_env` variable is
@@ -366,13 +366,13 @@ before the adjustment (except when the call is enclosed in parentheses; see
The assignment statement first evaluates all its expressions and only then are
the assignments performed. Thus the code
->
+>lua
i = 3
i, a[i] = i+1, 20
<
sets `a[3]` to 20, without affecting `a[4]` because the `i` in `a[i]` is evaluated (to
3) before it is assigned 4. Similarly, the line
->
+>lua
x, y = y, x
<
exchanges the values of `x` and `y`.
@@ -385,7 +385,7 @@ defined or callable in Lua. We use it here only for explanatory purposes.)
An assignment to a global variable `x = val` is equivalent to the
assignment `_env.x = val`, which in turn is equivalent to
->
+>lua
settable_event(_env, "x", val)
<
where `_env` is the environment of the running function. (The `_env` variable is
@@ -448,11 +448,11 @@ through an arithmetic progression. It has the following syntax:
<
The `block` is repeated for `name` starting at the value of the first `exp`, until
it passes the second `exp` by steps of the third `exp`. More precisely,
-a `for` statement like >
+a `for` statement like
- for var = e1, e2, e3 do block end
+ `for var = e1, e2, e3 do block end`
-< is equivalent to the code: >
+is equivalent to the code: >lua
do
local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)
@@ -489,7 +489,7 @@ A `for` statement like
`for` `var1, ..., varn` `in` `explist` `do` `block` `end`
-is equivalent to the code: >
+is equivalent to the code: >lua
do
local f, s, var = explist
@@ -582,7 +582,7 @@ adjusts the result list to one element, discarding all values except the first
one.
Here are some examples:
->
+>lua
f() -- adjusted to 0 results
g(f(), x) -- f() is adjusted to 1 result
g(x, f()) -- g gets x plus all results from f()
@@ -615,7 +615,7 @@ or strings that can be converted to numbers (see |luaref-langCoercion|), then al
operations have the usual meaning. Exponentiation works for any exponent. For
instance, `x^(-0.5)` computes the inverse of the square root of `x`. Modulo is
defined as
->
+>lua
a % b == a - math.floor(a/b)*b
<
That is, it is the remainder of a division that rounds the quotient towards
@@ -742,11 +742,11 @@ key `exp1` and value `exp2`. A field of the form `name = exp` is equivalent to
`["name"] = exp`. Finally, fields of the form `exp` are equivalent to
`[i] = exp`, where `i` are consecutive numerical integers, starting with 1.
Fields in the other formats do not affect this counting. For example,
->
+>lua
a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
<
is equivalent to
->
+>lua
do
local t = {}
t[f(1)] = g
@@ -802,7 +802,7 @@ argument list is a single new table. A call of the form `f'` `string` `'`
As an exception to the free-format syntax of Lua, you cannot put a line break
before the `(` in a function call. This restriction avoids some ambiguities
in the language. If you write
->
+>lua
a = f
(g).x(a)
<
@@ -820,7 +820,7 @@ function. Note that a tail call only happens with a particular syntax, where
the `return` has one single function call as argument; this syntax makes the
calling function return exactly the returns of the called function. So, none
of the following examples are tail calls:
->
+>lua
return (f(x)) -- results adjusted to 1
return 2 * f(x)
return x, f(x) -- additional results
@@ -901,7 +901,7 @@ expression is used as the last element of a list of expressions, then no
adjustment is made (unless the call is enclosed in parentheses).
As an example, consider the following definitions:
->
+>lua
function f(a, b) end
function g(a, b, ...) end
function r() return 1,2,3 end
@@ -942,7 +942,7 @@ is syntactic sugar for
Lua is a lexically scoped language. The scope of variables begins at the first
statement after their declaration and lasts until the end of the innermost
block that includes the declaration. Consider the following example:
->
+>lua
x = 10 -- global variable
do -- new block
local x = x -- new `x`, with value 10
@@ -967,7 +967,7 @@ function.
Notice that each execution of a local statement defines new local variables.
Consider the following example:
->
+>lua
a = {}
local x = 20
for i=1,10 do
@@ -1043,7 +1043,7 @@ given object, we use the expression
metatable(obj)[event]
<
This should be read as
->
+>lua
rawget(metatable(obj) or {}, event)
<
That is, the access to a metamethod does not invoke other metamethods, and the
@@ -1057,13 +1057,13 @@ the `+` operation.
The function `getbinhandler` below defines how Lua chooses a handler for a
binary operation. First, Lua tries the first operand. If its type does not
define a handler for the operation, then Lua tries the second operand.
->
+>lua
function getbinhandler (op1, op2, event)
return metatable(op1)[event] or metatable(op2)[event]
end
<
By using this function, the behavior of the `op1 + op2` is
->
+>lua
function add_event (op1, op2)
local o1, o2 = tonumber(op1), tonumber(op2)
if o1 and o2 then -- both operands are numeric?
@@ -1104,7 +1104,7 @@ with the function `pow` (from the C math library) as the primitive operation.
"unm": *__unm()*
------
the unary `-` operation.
->
+>lua
function unm_event (op)
local o = tonumber(op)
if o then -- operand is numeric?
@@ -1124,7 +1124,7 @@ the unary `-` operation.
"concat": *__concat()*
---------
the `..` (concatenation) operation.
->
+>lua
function concat_event (op1, op2)
if (type(op1) == "string" or type(op1) == "number") and
(type(op2) == "string" or type(op2) == "number") then
@@ -1142,7 +1142,7 @@ the `..` (concatenation) operation.
"len": *__len()*
------
the `#` operation.
->
+>lua
function len_event (op)
if type(op) == "string" then
return strlen(op) -- primitive string length
@@ -1167,7 +1167,7 @@ The function `getcomphandler` defines how Lua chooses a metamethod for
comparison operators. A metamethod only is selected when both objects being
compared have the same type and the same metamethod for the selected
operation.
->
+>lua
function getcomphandler (op1, op2, event)
if type(op1) ~= type(op2) then return nil end
local mm1 = metatable(op1)[event]
@@ -1176,7 +1176,7 @@ operation.
end
<
The "eq" event is defined as follows:
->
+>lua
function eq_event (op1, op2)
if type(op1) ~= type(op2) then -- different types?
return false -- different objects
@@ -1198,7 +1198,7 @@ The "eq" event is defined as follows:
"lt": *__lt()*
-----
the `<` operation.
->
+>lua
function lt_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 < op2 -- numeric comparison
@@ -1219,7 +1219,7 @@ the `<` operation.
"le": *__le()*
-----
the `<=` operation.
->
+>lua
function le_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 <= op2 -- numeric comparison
@@ -1247,7 +1247,7 @@ to `not (b < a)`.
"index": *__index()*
--------
The indexing access `table[key]`.
->
+>lua
function gettable_event (table, key)
local h
if type(table) == "table" then
@@ -1269,7 +1269,7 @@ The indexing access `table[key]`.
"newindex": *__newindex()*
-----------
The indexing assignment `table[key] = value`.
->
+>lua
function settable_event (table, key, value)
local h
if type(table) == "table" then
@@ -1291,7 +1291,7 @@ The indexing assignment `table[key] = value`.
"call": *__call()*
-------
called when Lua calls a value.
->
+>lua
function function_event (func, ...)
if type(func) == "function" then
return func(...) -- primitive call
@@ -1386,7 +1386,7 @@ Garbage userdata with a field `__gc` in their metatables are not collected
immediately by the garbage collector. Instead, Lua puts them in a list. After
the collection, Lua does the equivalent of the following function for each
userdata in that list:
->
+>lua
function gc_event (udata)
local h = metatable(udata).__gc
if h then
@@ -1469,7 +1469,7 @@ coroutine. Any arguments passed to this function go as extra arguments to
propagated to the caller.
As an example, consider the next code:
->
+>lua
function foo1 (a)
print("foo", a)
return coroutine.yield(2*a)
@@ -1559,7 +1559,7 @@ Most query functions accept as indices any value inside the available stack
space, that is, indices up to the maximum stack size you have set through
`lua_checkstack`. Such indices are called acceptable indices. More formally,
we define an acceptable index as follows:
->
+>lua
(index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace)
<
Note that 0 is never an acceptable index.
@@ -1580,7 +1580,7 @@ pseudo-index `LUA_ENVIRONINDEX`.
To access and change the value of global variables, you can use regular table
operations over an environment table. For instance, to access the value of a
global variable, do
->
+>c
lua_getfield(L, LUA_GLOBALSINDEX, varname);
<
@@ -1639,7 +1639,7 @@ Inside a C function you can raise an error by calling `lua_error` (see
Here we list all functions and types from the C API in alphabetical order.
lua_Alloc *lua_Alloc()*
->
+>c
typedef void * (*lua_Alloc) (void *ud,
void *ptr,
size_t osize,
@@ -1663,7 +1663,7 @@ lua_Alloc *lua_Alloc()*
Here is a simple implementation for the allocator function. It is used
in the auxiliary library by `luaL_newstate` (see
|luaL_newstate()|).
->
+>c
static void *l_alloc (void *ud, void *ptr, size_t osize,
size_t nsize) {
(void)ud; (void)osize; /* not used */
@@ -1680,7 +1680,7 @@ lua_Alloc *lua_Alloc()*
behaviors.
lua_atpanic *lua_atpanic()*
->
+>c
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
<
Sets a new panic function and returns the old one.
@@ -1694,7 +1694,7 @@ lua_atpanic *lua_atpanic()*
stack.
lua_call *lua_call()*
->
+>c
void lua_call (lua_State *L, int nargs, int nresults);
<
Calls a function.
@@ -1718,11 +1718,11 @@ lua_call *lua_call()*
The following example shows how the host program may do the equivalent
to this Lua code:
->
+>lua
a = f("how", t.x, 14)
<
Here it is in C:
->
+>c
lua_getfield(L, LUA_GLOBALSINDEX, "f"); // function to be called
lua_pushstring(L, "how"); // 1st argument
lua_getfield(L, LUA_GLOBALSINDEX, "t"); // table to be indexed
@@ -1737,7 +1737,7 @@ lua_call *lua_call()*
practice.
lua_CFunction *luaref-cfunction* *lua_CFunction()*
->
+>c
typedef int (*lua_CFunction) (lua_State *L);
<
Type for C functions.
@@ -1758,7 +1758,7 @@ lua_CFunction *luaref-cfunction* *lua_CFunction()*
*luaref-cfunctionexample*
As an example, the following function receives a variable number of
numerical arguments and returns their average and sum:
->
+>c
static int foo (lua_State *L) {
int n = lua_gettop(L); /* number of arguments */
lua_Number sum = 0;
@@ -1777,7 +1777,7 @@ lua_CFunction *luaref-cfunction* *lua_CFunction()*
<
lua_checkstack *lua_checkstack()*
->
+>c
int lua_checkstack (lua_State *L, int extra);
<
Ensures that there are at least `extra` free stack slots in the stack.
@@ -1786,7 +1786,7 @@ lua_checkstack *lua_checkstack()*
the new size, it is left unchanged.
lua_close *lua_close()*
->
+>c
void lua_close (lua_State *L);
<
Destroys all objects in the given Lua state (calling the corresponding
@@ -1798,7 +1798,7 @@ lua_close *lua_close()*
are not needed, to avoid growing too large.
lua_concat *lua_concat()*
->
+>c
void lua_concat (lua_State *L, int n);
<
Concatenates the `n` values at the top of the stack, pops them, and
@@ -1808,7 +1808,7 @@ lua_concat *lua_concat()*
usual semantics of Lua (see |luaref-langConcat|).
lua_cpcall *lua_cpcall()*
->
+>c
int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
<
Calls the C function `func` in protected mode. `func` starts with only
@@ -1819,7 +1819,7 @@ lua_cpcall *lua_cpcall()*
returned by `func` are discarded.
lua_createtable *lua_createtable()*
->
+>c
void lua_createtable (lua_State *L, int narr, int nrec);
<
Creates a new empty table and pushes it onto the stack. The new table
@@ -1829,7 +1829,7 @@ lua_createtable *lua_createtable()*
`lua_newtable` (see |lua_newtable()|).
lua_dump *lua_dump()*
->
+>c
int lua_dump (lua_State *L, lua_Writer writer, void *data);
<
Dumps a function as a binary chunk. Receives a Lua function on the top
@@ -1844,7 +1844,7 @@ lua_dump *lua_dump()*
This function does not pop the Lua function from the stack.
lua_equal *lua_equal()*
->
+>c
int lua_equal (lua_State *L, int index1, int index2);
<
Returns 1 if the two values in acceptable indices `index1` and
@@ -1853,7 +1853,7 @@ lua_equal *lua_equal()*
if any of the indices is non valid.
lua_error *lua_error()*
->
+>c
int lua_error (lua_State *L);
<
Generates a Lua error. The error message (which can actually be a Lua
@@ -1861,7 +1861,7 @@ lua_error *lua_error()*
jump, and therefore never returns (see |luaL_error()|).
lua_gc *lua_gc()*
->
+>c
int lua_gc (lua_State *L, int what, int data);
<
Controls the garbage collector.
@@ -1893,7 +1893,7 @@ lua_gc *lua_gc()*
previous value of the step multiplier.
lua_getallocf *lua_getallocf()*
->
+>c
lua_Alloc lua_getallocf (lua_State *L, void **ud);
<
Returns the memory-allocation function of a given state. If `ud` is
@@ -1901,14 +1901,14 @@ lua_getallocf *lua_getallocf()*
`lua_newstate` (see |lua_newstate()|).
lua_getfenv *lua_getfenv()*
->
+>c
void lua_getfenv (lua_State *L, int index);
<
Pushes onto the stack the environment table of the value at the given
index.
lua_getfield *lua_getfield()*
->
+>c
void lua_getfield (lua_State *L, int index, const char *k);
<
Pushes onto the stack the value `t[k]`, where `t` is the value at the
@@ -1916,17 +1916,17 @@ lua_getfield *lua_getfield()*
metamethod for the "index" event (see |luaref-langMetatables|).
lua_getglobal *lua_getglobal()*
->
+>c
void lua_getglobal (lua_State *L, const char *name);
<
Pushes onto the stack the value of the global `name`. It is defined as
a macro:
->
+>c
#define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
<
lua_getmetatable *lua_getmetatable()*
->
+>c
int lua_getmetatable (lua_State *L, int index);
<
Pushes onto the stack the metatable of the value at the given
@@ -1935,7 +1935,7 @@ lua_getmetatable *lua_getmetatable()*
stack.
lua_gettable *lua_gettable()*
->
+>c
void lua_gettable (lua_State *L, int index);
<
Pushes onto the stack the value `t[k]`, where `t` is the value at the
@@ -1947,7 +1947,7 @@ lua_gettable *lua_gettable()*
the "index" event (see |luaref-langMetatables|).
lua_gettop *lua_gettop()*
->
+>c
int lua_gettop (lua_State *L);
<
Returns the index of the top element in the stack. Because indices
@@ -1956,7 +1956,7 @@ lua_gettop *lua_gettop()*
0 means an empty stack).
lua_insert *lua_insert()*
->
+>c
void lua_insert (lua_State *L, int index);
<
Moves the top element into the given valid index, shifting up the
@@ -1964,7 +1964,7 @@ lua_insert *lua_insert()*
pseudo-index, because a pseudo-index is not an actual stack position.
lua_Integer *lua_Integer()*
->
+>c
typedef ptrdiff_t lua_Integer;
<
The type used by the Lua API to represent integral values.
@@ -1973,77 +1973,77 @@ lua_Integer *lua_Integer()*
type the machine handles "comfortably".
lua_isboolean *lua_isboolean()*
->
+>c
int lua_isboolean (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index has type boolean,
and 0 otherwise.
lua_iscfunction *lua_iscfunction()*
->
+>c
int lua_iscfunction (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a C function,
and 0 otherwise.
lua_isfunction *lua_isfunction()*
->
+>c
int lua_isfunction (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a function
(either C or Lua), and 0 otherwise.
lua_islightuserdata *lua_islightuserdata()*
->
+>c
int lua_islightuserdata (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a light
userdata, and 0 otherwise.
lua_isnil *lua_isnil()*
->
+>c
int lua_isnil (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is `nil`, and 0
otherwise.
lua_isnumber *lua_isnumber()*
->
+>c
int lua_isnumber (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a number or a
string convertible to a number, and 0 otherwise.
lua_isstring *lua_isstring()*
->
+>c
int lua_isstring (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a string or a
number (which is always convertible to a string), and 0 otherwise.
lua_istable *lua_istable()*
->
+>c
int lua_istable (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a table, and
0 otherwise.
lua_isthread *lua_isthread()*
->
+>c
int lua_isthread (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a thread, and
0 otherwise.
lua_isuserdata *lua_isuserdata()*
->
+>c
int lua_isuserdata (lua_State *L, int index);
<
Returns 1 if the value at the given acceptable index is a userdata
(either full or light), and 0 otherwise.
lua_lessthan *lua_lessthan()*
->
+>c
int lua_lessthan (lua_State *L, int index1, int index2);
<
Returns 1 if the value at acceptable index `index1` is smaller than
@@ -2052,7 +2052,7 @@ lua_lessthan *lua_lessthan()*
Also returns 0 if any of the indices is non valid.
lua_load *lua_load()*
->
+>c
int lua_load (lua_State *L,
lua_Reader reader,
void *data,
@@ -2079,7 +2079,7 @@ lua_load *lua_load()*
error messages and in debug information (see |luaref-apiDebug|).
lua_newstate *lua_newstate()*
->
+>c
lua_State *lua_newstate (lua_Alloc f, void *ud);
<
Creates a new, independent state. Returns `NULL` if cannot create the
@@ -2089,7 +2089,7 @@ lua_newstate *lua_newstate()*
simply passes to the allocator in every call.
lua_newtable *lua_newtable()*
->
+>c
void lua_newtable (lua_State *L);
<
Creates a new empty table and pushes it onto the stack. It is
@@ -2097,7 +2097,7 @@ lua_newtable *lua_newtable()*
|lua_createtable()|).
lua_newthread *lua_newthread()*
->
+>c
lua_State *lua_newthread (lua_State *L);
<
Creates a new thread, pushes it on the stack, and returns a pointer to
@@ -2110,7 +2110,7 @@ lua_newthread *lua_newthread()*
are subject to garbage collection, like any Lua object.
lua_newuserdata *lua_newuserdata()*
->
+>c
void *lua_newuserdata (lua_State *L, size_t size);
<
This function allocates a new block of memory with the given size,
@@ -2128,7 +2128,7 @@ lua_newuserdata *lua_newuserdata()*
is collected again then Lua frees its corresponding memory.
lua_next *lua_next()*
->
+>c
int lua_next (lua_State *L, int index);
<
Pops a key from the stack, and pushes a key-value pair from the table
@@ -2138,7 +2138,7 @@ lua_next *lua_next()*
*luaref-tabletraversal*
A typical traversal looks like this:
->
+>c
/* table is in the stack at index 't' */
lua_pushnil(L); /* first key */
while (lua_next(L, t) != 0) {
@@ -2156,7 +2156,7 @@ lua_next *lua_next()*
value at the given index; this confuses the next call to `lua_next`.
lua_Number *lua_Number()*
->
+>c
typedef double lua_Number;
<
The type of numbers in Lua. By default, it is double, but that can be
@@ -2166,7 +2166,7 @@ lua_Number *lua_Number()*
another type for numbers (e.g., float or long).
lua_objlen *lua_objlen()*
->
+>c
size_t lua_objlen (lua_State *L, int index);
<
Returns the "length" of the value at the given acceptable index: for
@@ -2175,7 +2175,7 @@ lua_objlen *lua_objlen()*
block of memory allocated for the userdata; for other values, it is 0.
lua_pcall *lua_pcall()*
->
+>c
lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
<
Calls a function in protected mode.
@@ -2210,19 +2210,19 @@ lua_pcall *lua_pcall()*
- `LUA_ERRERR` error while running the error handler function.
lua_pop *lua_pop()*
->
+>c
void lua_pop (lua_State *L, int n);
<
Pops `n` elements from the stack.
lua_pushboolean *lua_pushboolean()*
->
+>c
void lua_pushboolean (lua_State *L, int b);
<
Pushes a boolean value with value `b` onto the stack.
lua_pushcclosure *lua_pushcclosure()*
->
+>c
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
<
Pushes a new C closure onto the stack.
@@ -2238,7 +2238,7 @@ lua_pushcclosure *lua_pushcclosure()*
pops these values from the stack.
lua_pushcfunction *lua_pushcfunction()*
->
+>c
void lua_pushcfunction (lua_State *L, lua_CFunction f);
<
Pushes a C function onto the stack. This function receives a pointer
@@ -2250,12 +2250,12 @@ lua_pushcfunction *lua_pushcfunction()*
|lua_CFunction()|).
`lua_pushcfunction` is defined as a macro:
->
+>c
#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
<
lua_pushfstring *lua_pushfstring()*
->
+>c
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
<
Pushes onto the stack a formatted string and returns a pointer to this
@@ -2274,13 +2274,13 @@ lua_pushfstring *lua_pushfstring()*
character).
lua_pushinteger *lua_pushinteger()*
->
+>c
void lua_pushinteger (lua_State *L, lua_Integer n);
<
Pushes a number with value `n` onto the stack.
lua_pushlightuserdata *lua_pushlightuserdata()*
->
+>c
void lua_pushlightuserdata (lua_State *L, void *p);
<
Pushes a light userdata onto the stack.
@@ -2292,7 +2292,7 @@ lua_pushlightuserdata *lua_pushlightuserdata()*
same C address.
lua_pushlstring *lua_pushlstring()*
->
+>c
void lua_pushlstring (lua_State *L, const char *s, size_t len);
<
Pushes the string pointed to by `s` with size `len` onto the stack.
@@ -2301,19 +2301,19 @@ lua_pushlstring *lua_pushlstring()*
returns. The string can contain embedded zeros.
lua_pushnil *lua_pushnil()*
->
+>c
void lua_pushnil (lua_State *L);
<
Pushes a nil value onto the stack.
lua_pushnumber *lua_pushnumber()*
->
+>c
void lua_pushnumber (lua_State *L, lua_Number n);
<
Pushes a number with value `n` onto the stack.
lua_pushstring *lua_pushstring()*
->
+>c
void lua_pushstring (lua_State *L, const char *s);
<
Pushes the zero-terminated string pointed to by `s` onto the stack.
@@ -2323,20 +2323,20 @@ lua_pushstring *lua_pushstring()*
end at the first zero.
lua_pushthread *lua_pushthread()*
->
+>c
int lua_pushthread (lua_State *L);
<
Pushes the thread represented by `L` onto the stack. Returns 1 if this
thread is the main thread of its state.
lua_pushvalue *lua_pushvalue()*
->
+>c
void lua_pushvalue (lua_State *L, int index);
<
Pushes a copy of the element at the given valid index onto the stack.
lua_pushvfstring *lua_pushvfstring()*
->
+>c
const char *lua_pushvfstring (lua_State *L,
const char *fmt,
va_list argp);
@@ -2346,7 +2346,7 @@ lua_pushvfstring *lua_pushvfstring()*
arguments.
lua_rawequal *lua_rawequal()*
->
+>c
int lua_rawequal (lua_State *L, int index1, int index2);
<
Returns 1 if the two values in acceptable indices `index1` and
@@ -2355,14 +2355,14 @@ lua_rawequal *lua_rawequal()*
valid.
lua_rawget *lua_rawget()*
->
+>c
void lua_rawget (lua_State *L, int index);
<
Similar to `lua_gettable` (see |lua_gettable()|), but does a raw
access (i.e., without metamethods).
lua_rawgeti *lua_rawgeti()*
->
+>c
void lua_rawgeti (lua_State *L, int index, int n);
<
Pushes onto the stack the value `t[n]`, where `t` is the value at the
@@ -2370,14 +2370,14 @@ lua_rawgeti *lua_rawgeti()*
invoke metamethods.
lua_rawset *lua_rawset()*
->
+>c
void lua_rawset (lua_State *L, int index);
<
Similar to `lua_settable` (see |lua_settable()|), but does a raw
assignment (i.e., without metamethods).
lua_rawseti *lua_rawseti()*
->
+>c
void lua_rawseti (lua_State *L, int index, int n);
<
Does the equivalent of `t[n] = v`, where `t` is the value at the given
@@ -2387,7 +2387,7 @@ lua_rawseti *lua_rawseti()*
that is, it does not invoke metamethods.
lua_Reader *lua_Reader()*
->
+>c
typedef const char * (*lua_Reader) (lua_State *L,
void *data,
size_t *size);
@@ -2402,20 +2402,20 @@ lua_Reader *lua_Reader()*
zero.
lua_register *lua_register()*
->
+>c
void lua_register (lua_State *L,
const char *name,
lua_CFunction f);
<
Sets the C function `f` as the new value of global `name`. It is
defined as a macro:
->
+>c
#define lua_register(L,n,f) \
(lua_pushcfunction(L, f), lua_setglobal(L, n))
<
lua_remove *lua_remove()*
->
+>c
void lua_remove (lua_State *L, int index);
<
Removes the element at the given valid index, shifting down the
@@ -2423,7 +2423,7 @@ lua_remove *lua_remove()*
pseudo-index, because a pseudo-index is not an actual stack position.
lua_replace *lua_replace()*
->
+>c
void lua_replace (lua_State *L, int index);
<
Moves the top element into the given position (and pops it), without
@@ -2431,7 +2431,7 @@ lua_replace *lua_replace()*
position).
lua_resume *lua_resume()*
->
+>c
int lua_resume (lua_State *L, int narg);
<
Starts and resumes a coroutine in a given thread.
@@ -2452,14 +2452,14 @@ lua_resume *lua_resume()*
and then call `lua_resume`.
lua_setallocf *lua_setallocf()*
->
+>c
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
<
Changes the allocator function of a given state to `f` with user data
`ud`.
lua_setfenv *lua_setfenv()*
->
+>c
int lua_setfenv (lua_State *L, int index);
<
Pops a table from the stack and sets it as the new environment for the
@@ -2468,7 +2468,7 @@ lua_setfenv *lua_setfenv()*
Otherwise it returns 1.
lua_setfield *lua_setfield()*
->
+>c
void lua_setfield (lua_State *L, int index, const char *k);
<
Does the equivalent to `t[k] = v`, where `t` is the value at the given
@@ -2479,24 +2479,24 @@ lua_setfield *lua_setfield()*
|luaref-langMetatables|).
lua_setglobal *lua_setglobal()*
->
+>c
void lua_setglobal (lua_State *L, const char *name);
<
Pops a value from the stack and sets it as the new value of global
`name`. It is defined as a macro:
->
+>c
#define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
<
lua_setmetatable *lua_setmetatable()*
->
+>c
int lua_setmetatable (lua_State *L, int index);
<
Pops a table from the stack and sets it as the new metatable for the
value at the given acceptable index.
lua_settable *lua_settable()*
->
+>c
void lua_settable (lua_State *L, int index);
<
Does the equivalent to `t[k] = v`, where `t` is the value at the given
@@ -2508,7 +2508,7 @@ lua_settable *lua_settable()*
(see |luaref-langMetatables|).
lua_settop *lua_settop()*
->
+>c
void lua_settop (lua_State *L, int index);
<
Accepts any acceptable index, or 0, and sets the stack top to this
@@ -2517,7 +2517,7 @@ lua_settop *lua_settop()*
elements are removed.
lua_State *lua_State()*
->
+>c
typedef struct lua_State lua_State;
<
Opaque structure that keeps the whole state of a Lua interpreter. The
@@ -2529,7 +2529,7 @@ lua_State *lua_State()*
|lua_newstate()|), which creates a Lua state from scratch.
lua_status *lua_status()*
->
+>c
int lua_status (lua_State *L);
<
Returns the status of the thread `L`.
@@ -2539,7 +2539,7 @@ lua_status *lua_status()*
suspended.
lua_toboolean *lua_toboolean()*
->
+>c
int lua_toboolean (lua_State *L, int index);
<
Converts the Lua value at the given acceptable index to a C boolean
@@ -2550,14 +2550,14 @@ lua_toboolean *lua_toboolean()*
|lua_isboolean()| to test the value's type.)
lua_tocfunction *lua_tocfunction()*
->
+>c
lua_CFunction lua_tocfunction (lua_State *L, int index);
<
Converts a value at the given acceptable index to a C function. That
value must be a C function; otherwise it returns `NULL`.
lua_tointeger *lua_tointeger()*
->
+>c
lua_Integer lua_tointeger (lua_State *L, int idx);
<
Converts the Lua value at the given acceptable index to the signed
@@ -2569,7 +2569,7 @@ lua_tointeger *lua_tointeger()*
way.
lua_tolstring *lua_tolstring()*
->
+>c
const char *lua_tolstring (lua_State *L, int index, size_t *len);
<
Converts the Lua value at the given acceptable index to a C string. If
@@ -2588,7 +2588,7 @@ lua_tolstring *lua_tolstring()*
value is removed from the stack.
lua_tonumber *lua_tonumber()*
->
+>c
lua_Number lua_tonumber (lua_State *L, int index);
<
Converts the Lua value at the given acceptable index to the C type
@@ -2597,7 +2597,7 @@ lua_tonumber *lua_tonumber()*
otherwise, `lua_tonumber` returns 0.
lua_topointer *lua_topointer()*
->
+>c
const void *lua_topointer (lua_State *L, int index);
<
Converts the value at the given acceptable index to a generic C
@@ -2609,14 +2609,14 @@ lua_topointer *lua_topointer()*
Typically this function is used only for debug information.
lua_tostring *lua_tostring()*
->
+>c
const char *lua_tostring (lua_State *L, int index);
<
Equivalent to `lua_tolstring` (see |lua_tolstring()|) with `len`
equal to `NULL`.
lua_tothread *lua_tothread()*
->
+>c
lua_State *lua_tothread (lua_State *L, int index);
<
Converts the value at the given acceptable index to a Lua thread
@@ -2624,7 +2624,7 @@ lua_tothread *lua_tothread()*
thread; otherwise, the function returns `NULL`.
lua_touserdata *lua_touserdata()*
->
+>c
void *lua_touserdata (lua_State *L, int index);
<
If the value at the given acceptable index is a full userdata, returns
@@ -2632,7 +2632,7 @@ lua_touserdata *lua_touserdata()*
pointer. Otherwise, it returns `NULL`.
lua_type *lua_type()*
->
+>c
int lua_type (lua_State *L, int index);
<
Returns the type of the value in the given acceptable index, or
@@ -2643,14 +2643,14 @@ lua_type *lua_type()*
`LUA_TUSERDATA`, `LUA_TTHREAD`, and `LUA_TLIGHTUSERDATA`.
lua_typename *lua_typename()*
->
+>c
const char *lua_typename (lua_State *L, int tp);
<
Returns the name of the type encoded by the value `tp`, which must be
one the values returned by `lua_type`.
lua_Writer *lua_Writer()*
->
+>c
typedef int (*lua_Writer) (lua_State *L,
const void* p,
size_t sz,
@@ -2665,7 +2665,7 @@ lua_Writer *lua_Writer()*
means an error and stops `lua_dump` from calling the writer again.
lua_xmove *lua_xmove()*
->
+>c
void lua_xmove (lua_State *from, lua_State *to, int n);
<
Exchange values between different threads of the `same` global state.
@@ -2674,14 +2674,14 @@ lua_xmove *lua_xmove()*
onto the stack `to`.
lua_yield *lua_yield()*
->
+>c
int lua_yield (lua_State *L, int nresults);
<
Yields a coroutine.
This function should only be called as the return expression of a C
function, as follows:
->
+>c
return lua_yield (L, nresults);
<
When a C function calls `lua_yield` in that way, the running coroutine
@@ -2715,7 +2715,7 @@ need "inside information" from the interpreter.
lua_Debug *lua_Debug()*
->
+>c
typedef struct lua_Debug {
int event;
const char *name; /* (n) */
@@ -2768,25 +2768,25 @@ The fields of `lua_Debug` have the following meaning:
upvalues of the function.
lua_gethook *lua_gethook()*
->
+>c
lua_Hook lua_gethook (lua_State *L);
<
Returns the current hook function.
lua_gethookcount *lua_gethookcount()*
->
+>c
int lua_gethookcount (lua_State *L);
<
Returns the current hook count.
lua_gethookmask *lua_gethookmask()*
->
+>c
int lua_gethookmask (lua_State *L);
<
Returns the current hook mask.
lua_getinfo *lua_getinfo()*
->
+>c
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
<
Returns information about a specific function or function invocation.
@@ -2801,7 +2801,7 @@ lua_getinfo *lua_getinfo()*
`lua_getinfo` pops the function in the top of the stack.) For
instance, to know in which line a function `f` was defined, you can
write the following code:
->
+>c
lua_Debug ar;
lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */
lua_getinfo(L, ">S", &ar);
@@ -2826,7 +2826,7 @@ lua_getinfo *lua_getinfo()*
`what`).
lua_getlocal *lua_getlocal()*
->
+>c
const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);
<
Gets information about a local variable of a given activation record.
@@ -2846,7 +2846,7 @@ lua_getlocal *lua_getlocal()*
number of active local variables.
lua_getstack *lua_getstack()*
->
+>c
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
<
Gets information about the interpreter runtime stack.
@@ -2859,7 +2859,7 @@ lua_getstack *lua_getstack()*
with a level greater than the stack depth, it returns 0.
lua_getupvalue *lua_getupvalue()*
->
+>c
const char *lua_getupvalue (lua_State *L, int funcindex, int n);
<
Gets information about a closure's upvalue. (For Lua functions,
@@ -2875,7 +2875,7 @@ lua_getupvalue *lua_getupvalue()*
string `""` as a name for all upvalues.
lua_Hook *lua_Hook()*
->
+>c
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
<
Type for debugging hook functions.
@@ -2897,7 +2897,7 @@ lua_Hook *lua_Hook()*
lua_sethook *lua_sethook()*
->
+>c
int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);
<
Sets the debugging hook function.
@@ -2926,7 +2926,7 @@ lua_sethook *lua_sethook()*
A hook is disabled by setting `mask` to zero.
lua_setlocal *lua_setlocal()*
->
+>c
const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);
<
Sets the value of a local variable of a given activation record.
@@ -2939,7 +2939,7 @@ lua_setlocal *lua_setlocal()*
number of active local variables.
lua_setupvalue *lua_setupvalue()*
->
+>c
const char *lua_setupvalue (lua_State *L, int funcindex, int n);
<
Sets the value of a closure's upvalue. It assigns the value at the top
@@ -2953,7 +2953,7 @@ lua_setupvalue *lua_setupvalue()*
*luaref-debugexample*
As an example, the following function lists the names of all local
variables and upvalues for a function at a given level of the stack:
->
+>c
int listvars (lua_State *L, int level) {
lua_Debug ar;
int i;
@@ -3002,20 +3002,20 @@ Here we list all functions and types from the auxiliary library in
alphabetical order.
luaL_addchar *luaL_addchar()*
->
+>c
void luaL_addchar (luaL_Buffer *B, char c);
<
Adds the character `c` to the buffer `B` (see |luaL_Buffer()|).
luaL_addlstring *luaL_addlstring()*
->
+>c
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
<
Adds the string pointed to by `s` with length `l` to the buffer `B`
(see |luaL_Buffer()|). The string may contain embedded zeros.
luaL_addsize *luaL_addsize()*
->
+>c
void luaL_addsize (luaL_Buffer *B, size_t n);
<
Adds to the buffer `B` (see |luaL_Buffer()|) a string of length
@@ -3023,14 +3023,14 @@ luaL_addsize *luaL_addsize()*
|luaL_prepbuffer()|).
luaL_addstring *luaL_addstring()*
->
+>c
void luaL_addstring (luaL_Buffer *B, const char *s);
<
Adds the zero-terminated string pointed to by `s` to the buffer `B`
(see |luaL_Buffer()|). The string may not contain embedded zeros.
luaL_addvalue *luaL_addvalue()*
->
+>c
void luaL_addvalue (luaL_Buffer *B);
<
Adds the value at the top of the stack to the buffer `B` (see
@@ -3041,7 +3041,7 @@ luaL_addvalue *luaL_addvalue()*
added to the buffer.
luaL_argcheck *luaL_argcheck()*
->
+>c
void luaL_argcheck (lua_State *L,
int cond,
int narg,
@@ -3054,7 +3054,7 @@ luaL_argcheck *luaL_argcheck()*
<
luaL_argerror *luaL_argerror()*
->
+>c
int luaL_argerror (lua_State *L, int narg, const char *extramsg);
<
Raises an error with the following message, where `func` is retrieved
@@ -3066,7 +3066,7 @@ luaL_argerror *luaL_argerror()*
functions as `return luaL_argerror(` `args` `)`.
luaL_Buffer *luaL_Buffer()*
->
+>c
typedef struct luaL_Buffer luaL_Buffer;
<
Type for a `string buffer`.
@@ -3095,14 +3095,14 @@ luaL_Buffer *luaL_Buffer()*
string on its top.
luaL_buffinit *luaL_buffinit()*
->
+>c
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
<
Initializes a buffer `B`. This function does not allocate any space;
the buffer must be declared as a variable (see |luaL_Buffer()|).
luaL_callmeta *luaL_callmeta()*
->
+>c
int luaL_callmeta (lua_State *L, int obj, const char *e);
<
Calls a metamethod.
@@ -3115,49 +3115,49 @@ luaL_callmeta *luaL_callmeta()*
0 (without pushing any value on the stack).
luaL_checkany *luaL_checkany()*
->
+>c
void luaL_checkany (lua_State *L, int narg);
<
Checks whether the function has an argument of any type (including
`nil`) at position `narg`.
luaL_checkint *luaL_checkint()*
->
+>c
int luaL_checkint (lua_State *L, int narg);
<
Checks whether the function argument `narg` is a number and returns
this number cast to an `int`.
luaL_checkinteger *luaL_checkinteger()*
->
+>c
lua_Integer luaL_checkinteger (lua_State *L, int narg);
<
Checks whether the function argument `narg` is a number and returns
this number cast to a `lua_Integer` (see |lua_Integer()|).
luaL_checklong *luaL_checklong()*
->
+>c
long luaL_checklong (lua_State *L, int narg);
<
Checks whether the function argument `narg` is a number and returns
this number cast to a `long`.
luaL_checklstring *luaL_checklstring()*
->
+>c
const char *luaL_checklstring (lua_State *L, int narg, size_t *l);
<
Checks whether the function argument `narg` is a string and returns
this string; if `l` is not `NULL` fills `*l` with the string's length.
luaL_checknumber *luaL_checknumber()*
->
+>c
lua_Number luaL_checknumber (lua_State *L, int narg);
<
Checks whether the function argument `narg` is a number and returns
this number (see |lua_Number()|).
luaL_checkoption *luaL_checkoption()*
->
+>c
int luaL_checkoption (lua_State *L,
int narg,
const char *def,
@@ -3177,7 +3177,7 @@ luaL_checkoption *luaL_checkoption()*
select options.)
luaL_checkstack *luaL_checkstack()*
->
+>c
void luaL_checkstack (lua_State *L, int sz, const char *msg);
<
Grows the stack size to `top + sz` elements, raising an error if the
@@ -3185,48 +3185,48 @@ luaL_checkstack *luaL_checkstack()*
the error message.
luaL_checkstring *luaL_checkstring()*
->
+>c
const char *luaL_checkstring (lua_State *L, int narg);
<
Checks whether the function argument `narg` is a string and returns
this string.
luaL_checktype *luaL_checktype()*
->
+>c
void luaL_checktype (lua_State *L, int narg, int t);
<
Checks whether the function argument `narg` has type `t` (see
|lua_type()|).
luaL_checkudata *luaL_checkudata()*
->
+>c
void *luaL_checkudata (lua_State *L, int narg, const char *tname);
<
Checks whether the function argument `narg` is a userdata of the type
`tname` (see |luaL_newmetatable()|).
luaL_dofile *luaL_dofile()*
->
+>c
int luaL_dofile (lua_State *L, const char *filename);
<
Loads and runs the given file. It is defined as the following macro:
->
+>c
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
<
It returns 0 if there are no errors or 1 in case of errors.
luaL_dostring *luaL_dostring()*
->
+>c
int luaL_dostring (lua_State *L, const char *str);
<
Loads and runs the given string. It is defined as the following macro:
->
+>c
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
<
It returns 0 if there are no errors or 1 in case of errors.
luaL_error *luaL_error()*
->
+>c
int luaL_error (lua_State *L, const char *fmt, ...);
<
Raises an error. The error message format is given by `fmt` plus any
@@ -3239,7 +3239,7 @@ luaL_error *luaL_error()*
functions as `return luaL_error(` `args` `)`.
luaL_getmetafield *luaL_getmetafield()*
->
+>c
int luaL_getmetafield (lua_State *L, int obj, const char *e);
<
Pushes onto the stack the field `e` from the metatable of the object
@@ -3247,14 +3247,14 @@ luaL_getmetafield *luaL_getmetafield()*
metatable does not have this field, returns 0 and pushes nothing.
luaL_getmetatable *luaL_getmetatable()*
->
+>c
void luaL_getmetatable (lua_State *L, const char *tname);
<
Pushes onto the stack the metatable associated with name `tname` in
the registry (see |luaL_newmetatable()|).
luaL_gsub *luaL_gsub()*
->
+>c
const char *luaL_gsub (lua_State *L,
const char *s,
const char *p,
@@ -3265,7 +3265,7 @@ luaL_gsub *luaL_gsub()*
returns it.
luaL_loadbuffer *luaL_loadbuffer()*
->
+>c
int luaL_loadbuffer (lua_State *L,
const char *buff,
size_t sz,
@@ -3279,7 +3279,7 @@ luaL_loadbuffer *luaL_loadbuffer()*
chunk name, used for debug information and error messages.
luaL_loadfile *luaL_loadfile()*
->
+>c
int luaL_loadfile (lua_State *L, const char *filename);
<
Loads a file as a Lua chunk. This function uses `lua_load` (see
@@ -3293,7 +3293,7 @@ luaL_loadfile *luaL_loadfile()*
As `lua_load`, this function only loads the chunk; it does not run it.
luaL_loadstring *luaL_loadstring()*
->
+>c
int luaL_loadstring (lua_State *L, const char *s);
<
Loads a string as a Lua chunk. This function uses `lua_load` (see
@@ -3306,7 +3306,7 @@ luaL_loadstring *luaL_loadstring()*
run it.
luaL_newmetatable *luaL_newmetatable()*
->
+>c
int luaL_newmetatable (lua_State *L, const char *tname);
<
If the registry already has the key `tname`, returns 0. Otherwise,
@@ -3317,7 +3317,7 @@ luaL_newmetatable *luaL_newmetatable()*
`tname` in the registry.
luaL_newstate *luaL_newstate()*
->
+>c
lua_State *luaL_newstate (void);
<
Creates a new Lua state. It calls `lua_newstate` (see
@@ -3330,14 +3330,14 @@ luaL_newstate *luaL_newstate()*
error.
luaL_openlibs *luaL_openlibs()*
->
+>c
void luaL_openlibs (lua_State *L);
<
Opens all standard Lua libraries into the given state. See also
|luaref-openlibs| for details on how to open individual libraries.
luaL_optint *luaL_optint()*
->
+>c
int luaL_optint (lua_State *L, int narg, int d);
<
If the function argument `narg` is a number, returns this number cast
@@ -3345,7 +3345,7 @@ luaL_optint *luaL_optint()*
Otherwise, raises an error.
luaL_optinteger *luaL_optinteger()*
->
+>c
lua_Integer luaL_optinteger (lua_State *L,
int narg,
lua_Integer d);
@@ -3355,7 +3355,7 @@ luaL_optinteger *luaL_optinteger()*
absent or is `nil`, returns `d`. Otherwise, raises an error.
luaL_optlong *luaL_optlong()*
->
+>c
long luaL_optlong (lua_State *L, int narg, long d);
<
If the function argument `narg` is a number, returns this number cast
@@ -3363,7 +3363,7 @@ luaL_optlong *luaL_optlong()*
Otherwise, raises an error.
luaL_optlstring *luaL_optlstring()*
->
+>c
const char *luaL_optlstring (lua_State *L,
int narg,
const char *d,
@@ -3376,7 +3376,7 @@ luaL_optlstring *luaL_optlstring()*
If `l` is not `NULL`, fills the position `*l` with the results' length.
luaL_optnumber *luaL_optnumber()*
->
+>c
lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);
<
If the function argument `narg` is a number, returns this number. If
@@ -3384,7 +3384,7 @@ luaL_optnumber *luaL_optnumber()*
error.
luaL_optstring *luaL_optstring()*
->
+>c
const char *luaL_optstring (lua_State *L,
int narg,
const char *d);
@@ -3394,7 +3394,7 @@ luaL_optstring *luaL_optstring()*
error.
luaL_prepbuffer *luaL_prepbuffer()*
->
+>c
char *luaL_prepbuffer (luaL_Buffer *B);
<
Returns an address to a space of size `LUAL_BUFFERSIZE` where you can
@@ -3404,14 +3404,14 @@ luaL_prepbuffer *luaL_prepbuffer()*
add it to the buffer.
luaL_pushresult *luaL_pushresult()*
->
+>c
void luaL_pushresult (luaL_Buffer *B);
<
Finishes the use of buffer `B` leaving the final string on the top of
the stack.
luaL_ref *luaL_ref()*
->
+>c
int luaL_ref (lua_State *L, int t);
<
Creates and returns a `reference`, in the table at index `t`, for the
@@ -3429,7 +3429,7 @@ luaL_ref *luaL_ref()*
different from any reference returned by `luaL_ref`.
luaL_Reg *luaL_Reg()*
->
+>c
typedef struct luaL_Reg {
const char *name;
lua_CFunction func;
@@ -3441,7 +3441,7 @@ luaL_Reg *luaL_Reg()*
sentinel entry in which both `name` and `func` are `NULL`.
luaL_register *luaL_register()*
->
+>c
void luaL_register (lua_State *L,
const char *libname,
const luaL_Reg *l);
@@ -3462,13 +3462,13 @@ luaL_register *luaL_register()*
In any case the function leaves the table on the top of the stack.
luaL_typename *luaL_typename()*
->
+>c
const char *luaL_typename (lua_State *L, int idx);
<
Returns the name of the type of the value at index `idx`.
luaL_typerror *luaL_typerror()*
->
+>c
int luaL_typerror (lua_State *L, int narg, const char *tname);
<
Generates an error with a message like the following:
@@ -3481,7 +3481,7 @@ luaL_typerror *luaL_typerror()*
`rt` is the type name of the actual argument.
luaL_unref *luaL_unref()*
->
+>c
void luaL_unref (lua_State *L, int t, int ref);
<
Releases reference `ref` from the table at index `t` (see
@@ -3492,7 +3492,7 @@ luaL_unref *luaL_unref()*
If `ref` is `LUA_NOREF` or `LUA_REFNIL`, `luaL_unref` does nothing.
luaL_where *luaL_where()*
->
+>c
void luaL_where (lua_State *L, int lvl);
<
Pushes onto the stack a string identifying the current position of the
@@ -3641,7 +3641,7 @@ loadstring({string} [, {chunkname}]) *luaref-loadstring()*
given {string}.
To load and run a given string, use the idiom
->
+>lua
assert(loadstring(s))()
<
@@ -3756,7 +3756,7 @@ type({v}) *luaref-type()*
unpack({list} [, {i} [, {j}]]) *luaref-unpack()*
Returns the elements from the given table. This function is equivalent
to
->
+>lua
return list[i], list[i+1], ..., list[j]
<
except that the above code can be written only for a fixed number of
@@ -4021,11 +4021,11 @@ string.format({formatstring}, {...}) *string.format()*
interpreter: the string is written between double quotes, and all
double quotes, newlines, embedded zeros, and backslashes in the string
are correctly escaped when written. For instance, the call
->
+>lua
string.format('%q', 'a string with "quotes" and \n new line')
<
will produce the string:
->
+>lua
"a string with \"quotes\" and \
new line"
<
@@ -4043,7 +4043,7 @@ string.gmatch({s}, {pattern}) *string.gmatch()*
in each call.
As an example, the following loop
->
+>lua
s = "hello world from Lua"
for w in string.gmatch(s, "%a+") do
print(w)
@@ -4052,7 +4052,7 @@ string.gmatch({s}, {pattern}) *string.gmatch()*
will iterate over all the words from string {s}, printing one per
line. The next example collects all pairs `key=value` from the given
string into a table:
->
+>lua
t = {}
s = "from=world, to=Lua"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
@@ -4091,7 +4091,7 @@ string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsub()*
occurrence of `pattern` is replaced.
Here are some examples:
->
+>lua
x = string.gsub("hello world", "(%w+)", "%1 %1")
--> x="hello hello world world"
diff --git a/runtime/doc/luvref.txt b/runtime/doc/luvref.txt
index dd4162c179..b0d1b6764a 100644
--- a/runtime/doc/luvref.txt
+++ b/runtime/doc/luvref.txt
@@ -28,7 +28,7 @@ TCP Echo Server Example~
Here is a small example showing a TCP echo server:
- >
+ >lua
local uv = vim.loop
local server = uv.new_tcp()
@@ -250,7 +250,7 @@ uv.loop_configure({option}, {...}) *uv.loop_configure()*
An example of a valid call to this function is:
- >
+ >lua
uv.loop_configure("block_signal", "sigprof")
<
@@ -343,7 +343,7 @@ uv.walk({callback}) *uv.walk()*
Returns: Nothing.
- >
+ >lua
-- Example usage of uv.walk to close all handles that
-- aren't already closing.
uv.walk(function (handle)
@@ -613,7 +613,7 @@ uv.new_timer() *uv.new_timer()*
Returns: `uv_timer_t userdata` or `fail`
- >
+ >lua
-- Creating a simple setTimeout wrapper
local function setTimeout(timeout, callback)
local timer = uv.new_timer()
@@ -737,7 +737,7 @@ uv.timer_get_due_in({timer}) *uv.timer_get_due_in()*
Prepare handles will run the given callback once per loop iteration, right
before polling for I/O.
- >
+ >lua
local prepare = uv.new_prepare()
prepare:start(function()
print("Before I/O polling")
@@ -782,7 +782,7 @@ uv.prepare_stop({prepare}) *uv.prepare_stop()*
Check handles will run the given callback once per loop iteration, right after
polling for I/O.
- >
+ >lua
local check = uv.new_check()
check:start(function()
print("After I/O polling")
@@ -834,7 +834,7 @@ blocking for I/O.
WARNING: Despite the name, idle handles will get their callbacks called on
every loop iteration, not when the loop is actually "idle".
- >
+ >lua
local idle = uv.new_idle()
idle:start(function()
print("Before I/O polling, no blocking")
@@ -879,7 +879,7 @@ uv.idle_stop({check}) *uv.idle_stop()*
Async handles allow the user to "wakeup" the event loop and get a callback
called from another thread.
- >
+ >lua
local async
async = uv.new_async(function()
print("async operation ran")
@@ -1062,7 +1062,7 @@ Unix Notes:
will lead to unpredictable behavior and is strongly discouraged. Future
versions of libuv may simply reject them.
- >
+ >lua
-- Create a new signal handler
local signal = uv.new_signal()
-- Define a handler function
@@ -1164,7 +1164,7 @@ uv.spawn({path}, {options}, {on_exit}) *uv.spawn()*
permissions to use the setuid or setgid specified, or not
having enough memory to allocate for the new process.
- >
+ >lua
local stdin = uv.new_pipe()
local stdout = uv.new_pipe()
local stderr = uv.new_pipe()
@@ -1358,7 +1358,7 @@ uv.accept({stream}, {client_stream}) *uv.accept()*
Returns: `0` or `fail`
- >
+ >lua
server:listen(128, function (err)
local client = uv.new_tcp()
server:accept(client)
@@ -1382,7 +1382,7 @@ uv.read_start({stream}, {callback}) *uv.read_start()*
Returns: `0` or `fail`
- >
+ >lua
stream:read_start(function (err, chunk)
if err then
-- handle read error
@@ -1690,7 +1690,7 @@ uv.tcp_connect({tcp}, {host}, {port}, {callback}) *uv.tcp_connect()*
Returns: `uv_connect_t userdata` or `fail`
- >
+ >lua
local client = uv.new_tcp()
client:connect("127.0.0.1", 8080, function (err)
-- check error and carry on.
@@ -1755,7 +1755,7 @@ uv.socketpair([{socktype}, [{protocol}, [{flags1}, [{flags2}]]]])
Returns: `table` or `fail`
- `[1, 2]` : `integer` (file descriptor)
- >
+ >lua
-- Simple read/write with tcp
local fds = uv.socketpair(nil, nil, {nonblock=true}, {nonblock=true})
@@ -1780,7 +1780,7 @@ uv.socketpair([{socktype}, [{protocol}, [{flags1}, [{flags2}]]]])
Pipe handles provide an abstraction over local domain sockets on Unix and
named pipes on Windows.
- >
+ >lua
local pipe = uv.new_pipe(false)
pipe:bind('/tmp/sock.test')
@@ -1959,7 +1959,7 @@ uv.pipe({read_flags}, {write_flags}) *uv.pipe()*
- `read` : `integer` (file descriptor)
- `write` : `integer` (file descriptor)
- >
+ >lua
-- Simple read/write with pipe_open
local fds = uv.pipe({nonblock=true}, {nonblock=true})
@@ -1983,7 +1983,7 @@ uv.pipe({read_flags}, {write_flags}) *uv.pipe()*
TTY handles represent a stream for the console.
- >
+ >lua
-- Simple echo program
local stdin = uv.new_tty(0, true)
local stdout = uv.new_tty(1, false)
@@ -2537,7 +2537,7 @@ FS call.
Synchronous and asynchronous versions of `readFile` (with naive error
handling) are implemented below as an example:
- >
+ >lua
local function readFileSync(path)
local fd = assert(uv.fs_open(path, "r", 438))
local stat = assert(uv.fs_fstat(fd))
@@ -2550,7 +2550,7 @@ handling) are implemented below as an example:
print("synchronous read", data)
<
- >
+ >lua
local function readFile(path, callback)
uv.fs_open(path, "r", 438, function(err, fd)
assert(not err, err)
@@ -3253,7 +3253,7 @@ Libuv provides a threadpool which can be used to run user code and get
notified in the loop thread. This threadpool is internally used to run all
file system operations, as well as `getaddrinfo` and `getnameinfo` requests.
- >
+ >lua
local function work_callback(a, b)
return a + b
end
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index 203f57024c..4946779a7c 100644
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@@ -9,7 +9,7 @@ Nvim *nvim* *nvim-intro*
Nvim is based on Vim by Bram Moolenaar.
If you already use Vim see |nvim-from-vim| for a quickstart.
-If you are new to Vim, try the 30-minute tutorial: >
+If you are new to Vim, try the 30-minute tutorial: >vim
:Tutor<Enter>
@@ -22,12 +22,12 @@ Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim
==============================================================================
Transitioning from Vim *nvim-from-vim*
-1. To start the transition, create your |init.vim| (user config) file: >
+1. To start the transition, create your |init.vim| (user config) file: >vim
:call mkdir(stdpath('config'), 'p')
:exe 'edit '.stdpath('config').'/init.vim'
-2. Add these contents to the file: >
+2. Add these contents to the file: >vim
set runtimepath^=~/.vim runtimepath+=~/.vim/after
let &packpath = &runtimepath
@@ -43,19 +43,19 @@ Your Vim configuration might not be entirely Nvim-compatible (see
because mouse support is always enabled if possible. If you use the same
|vimrc| for Vim and Nvim you could guard |'ttymouse'| in your configuration
like so:
->
+>vim
if !has('nvim')
set ttymouse=xterm2
endif
And for Nvim-specific configuration, you can do this:
->
+>vim
if has('nvim')
tnoremap <Esc> <C-\><C-n>
endif
For a more granular approach use |exists()|:
->
+>vim
if exists(':tnoremap')
tnoremap <Esc> <C-\><C-n>
endif
@@ -67,7 +67,7 @@ for more information.
Because Nvim follows the XDG |base-directories| standard, configuration on
Windows is stored in ~/AppData instead of ~/.config. But you can still share
the same Nvim configuration on all of your machines, by creating
-~/AppData/Local/nvim/init.vim containing just this line: >
+~/AppData/Local/nvim/init.vim containing just this line: >vim
source ~/.config/nvim/init.vim
==============================================================================
diff --git a/runtime/doc/nvim_terminal_emulator.txt b/runtime/doc/nvim_terminal_emulator.txt
index 3fe86b00bc..96f99528ed 100644
--- a/runtime/doc/nvim_terminal_emulator.txt
+++ b/runtime/doc/nvim_terminal_emulator.txt
@@ -27,12 +27,12 @@ There are several ways to create a terminal buffer:
- Run the |:terminal| command.
- Call the |nvim_open_term()| or |termopen()| function.
-- Edit a "term://" buffer. Examples: >
+- Edit a "term://" buffer. Examples: >vim
:edit term://bash
:vsplit term://top
< Note: To open a "term://" buffer from an autocmd, the |autocmd-nested|
- modifier is required. >
+ modifier is required. >vim
autocmd VimEnter * ++nested split term://sh
< (This is only mentioned for reference; use |:terminal| instead.)
@@ -62,13 +62,13 @@ Terminal-mode forces these local options:
Terminal-mode has its own |:tnoremap| namespace for mappings, this can be used
to automate any terminal interaction.
-To map <Esc> to exit terminal-mode: >
+To map <Esc> to exit terminal-mode: >vim
:tnoremap <Esc> <C-\><C-n>
-To simulate |i_CTRL-R| in terminal-mode: >
+To simulate |i_CTRL-R| in terminal-mode: >vim
:tnoremap <expr> <C-R> '<C-\><C-N>"'.nr2char(getchar()).'pi'
-To use `ALT+{h,j,k,l}` to navigate windows from any mode: >
+To use `ALT+{h,j,k,l}` to navigate windows from any mode: >vim
:tnoremap <A-h> <C-\><C-N><C-w>h
:tnoremap <A-j> <C-\><C-N><C-w>j
:tnoremap <A-k> <C-\><C-N><C-w>k
@@ -109,7 +109,7 @@ global configuration.
- 'list' is disabled
- 'wrap' is disabled
-You can change the defaults with a TermOpen autocommand: >
+You can change the defaults with a TermOpen autocommand: >vim
au TermOpen * setlocal list
TERMINAL COLORS ~
@@ -117,7 +117,7 @@ TERMINAL COLORS ~
The `{g,b}:terminal_color_x` variables control the terminal color palette,
where `x` is the color index between 0 and 255 inclusive. The variables are
read during |TermOpen|. The value must be a color name or hexadecimal string.
-Example: >
+Example: >vim
let g:terminal_color_4 = '#ff0000'
let g:terminal_color_5 = 'green'
Only works for RGB UIs (see 'termguicolors'); for 256-color terminals the
@@ -131,7 +131,7 @@ Status Variables *terminal-status*
Terminal buffers maintain some buffer-local variables and options. The values
are initialized before TermOpen, so you can use them in a local 'statusline'.
-Example: >
+Example: >vim
:autocmd TermOpen * setlocal statusline=%{b:term_title}
- *b:term_title* Terminal title (user-writable), typically displayed in the
@@ -141,10 +141,10 @@ Example: >
input to the terminal.
- The |TermClose| event gives the terminal job exit code in the |v:event|
"status" field. For example, this autocmd closes terminal buffers if the job
- exited without error: >
+ exited without error: >vim
autocmd TermClose * if !v:event.status | exe 'bdelete! '..expand('<abuf>') | endif
-Use |jobwait()| to check if the terminal job has finished: >
+Use |jobwait()| to check if the terminal job has finished: >vim
let running = jobwait([&channel], 0)[0] == -1
==============================================================================
@@ -156,11 +156,11 @@ Vim this also works remotely over an ssh connection.
Starting ~
*termdebug-starting*
-Load the plugin with this command: >
+Load the plugin with this command: >vim
packadd termdebug
< *:Termdebug*
To start debugging use `:Termdebug` or `:TermdebugCommand` followed by the
-command name, for example: >
+command name, for example: >vim
:Termdebug vim
This opens two windows:
@@ -189,16 +189,16 @@ Only one debugger can be active at a time.
*:TermdebugCommand*
If you want to give specific commands to the command being debugged, you can
use the `:TermdebugCommand` command followed by the command name and
-additional parameters. >
+additional parameters. >vim
:TermdebugCommand vim --clean -c ':set nu'
Both the `:Termdebug` and `:TermdebugCommand` support an optional "!" bang
argument to start the command right away, without pausing at the gdb window
-(and cursor will be in the debugged window). For example: >
+(and cursor will be in the debugged window). For example: >vim
:TermdebugCommand! vim --clean
To attach gdb to an already running executable or use a core file, pass extra
-arguments. E.g.: >
+arguments. E.g.: >vim
:Termdebug vim core
:Termdebug vim 98343
@@ -212,7 +212,7 @@ Start in the Vim "src" directory and build Vim: >
% make
Start Vim: >
% ./vim
-Load the termdebug plugin and start debugging Vim: >
+Load the termdebug plugin and start debugging Vim: >vim
:packadd termdebug
:Termdebug vim
You should now have three windows:
@@ -223,7 +223,7 @@ You should now have three windows:
Put focus on the gdb window and type: >
break ex_help
run
-Vim will start running in the program window. Put focus there and type: >
+Vim will start running in the program window. Put focus there and type: >vim
:help gui
Gdb will run into the ex_help breakpoint. The source window now shows the
ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the
@@ -329,7 +329,7 @@ Other commands ~
Events ~
*termdebug-events*
-Four autocommands can be used: >
+Four autocommands can be used: >vim
au User TermdebugStartPre echomsg 'debugging starting'
au User TermdebugStartPost echomsg 'debugging started'
au User TermdebugStopPre echomsg 'debugging stopping'
@@ -360,7 +360,7 @@ Customizing ~
In the past several global variables were used for configuration. These are
deprecated and using the g:termdebug_config dictionary is preferred. When
g:termdebug_config exists the other global variables will NOT be used.
-The recommended way is to start with an empty dictionary: >
+The recommended way is to start with an empty dictionary: >vim
let g:termdebug_config = {}
Then you can add entries to the dictionary as mentioned below. The
@@ -380,23 +380,23 @@ This works slightly differently:
- A separate :terminal window will be opened to run the debugged program in.
*termdebug_use_prompt*
-Prompt mode can be used with: >
+Prompt mode can be used with: >vim
let g:termdebug_config['use_prompt'] = 1
-If there is no g:termdebug_config you can use: >
+If there is no g:termdebug_config you can use: >vim
let g:termdebug_use_prompt = 1
<
*termdebug_map_K*
-The K key is normally mapped to :Evaluate. If you do not want this use: >
+The K key is normally mapped to :Evaluate. If you do not want this use: >vim
let g:termdebug_config['map_K'] = 0
-If there is no g:termdebug_config you can use: >
+If there is no g:termdebug_config you can use: >vim
let g:termdebug_map_K = 0
<
*termdebug_disasm_window*
If you want the Asm window shown by default, set the flag to 1.
-the "disasm_window_height" entry can be used to set the window height: >
+the "disasm_window_height" entry can be used to set the window height: >vim
let g:termdebug_config['disasm_window'] = 1
let g:termdebug_config['disasm_window_height'] = 15
-If there is no g:termdebug_config you can use: >
+If there is no g:termdebug_config you can use: >vim
let g:termdebug_disasm_window = 15
Any value greater than 1 will set the Asm window height to that value.
@@ -418,34 +418,34 @@ GDB command ~
*g:termdebugger*
To change the name of the gdb command, set "debugger" entry in
g:termdebug_config or the "g:termdebugger" variable before invoking
-`:Termdebug`: >
+`:Termdebug`: >vim
let g:termdebug_config['command'] = "mygdb"
-If there is no g:termdebug_config you can use: >
+If there is no g:termdebug_config you can use: >vim
let g:termdebugger = "mygdb"
-If the command needs an argument use a List: >
+If the command needs an argument use a List: >vim
let g:termdebug_config['command'] = ['rr', 'replay', '--']
-If there is no g:termdebug_config you can use: >
+If there is no g:termdebug_config you can use: >vim
let g:termdebugger = ['rr', 'replay', '--']
To not use neovim floating windows for previewing variable evaluation, set the
-`g:termdebug_useFloatingHover` variable like this: >
+`g:termdebug_useFloatingHover` variable like this: >vim
let g:termdebug_useFloatingHover = 0
If you are a mouse person, you can also define a mapping using your right
click to one of the terminal command like evaluate the variable under the
-cursor: >
+cursor: >vim
nnoremap <RightMouse> :Evaluate<CR>
-or set/unset a breakpoint: >
+or set/unset a breakpoint: >vim
nnoremap <RightMouse> :Break<CR>
Several arguments will be added to make gdb work well for the debugger.
-If you want to modify them, add a function to filter the argument list: >
+If you want to modify them, add a function to filter the argument list: >vim
let g:termdebug_config['command_filter'] = MyDebugFilter
If you do not want the arguments to be added, but you do need to set the
-"pty", use a function to add the necessary arguments: >
+"pty", use a function to add the necessary arguments: >vim
let g:termdebug_config['command_add_args'] = MyAddArguments
The function will be called with the list of arguments so far, and a second
argument that is the name of the pty.
@@ -475,7 +475,7 @@ When 'background' is "dark":
Shortcuts ~
*termdebug_shortcuts*
You can define your own shortcuts (mappings) to control gdb, that can work in
-any window, using the TermDebugSendCommand() function. Example: >
+any window, using the TermDebugSendCommand() function. Example: >vim
map ,w :call TermDebugSendCommand('where')<CR>
The argument is the gdb command.
@@ -487,18 +487,18 @@ these entries to the popup menu:
Set breakpoint `:Break`
Clear breakpoint `:Clear`
Evaluate `:Evaluate`
-If you don't want this then disable it with: >
+If you don't want this then disable it with: >vim
let g:termdebug_config['popup'] = 0
-If there is no g:termdebug_config you can use: >
+If there is no g:termdebug_config you can use: >vim
let g:termdebug_popup = 0
Vim window width ~
*termdebug_wide*
To change the width of the Vim window when debugging starts and use a vertical
-split: >
+split: >vim
let g:termdebug_config['wide'] = 163
-If there is no g:termdebug_config you can use: >
+If there is no g:termdebug_config you can use: >vim
let g:termdebug_wide = 163
This will set 'columns' to 163 when `:Termdebug` is used. The value is
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 3ccff3dc3c..8f2feb416b 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -36,7 +36,7 @@ itself).
For Python 3 plugins:
1. Make sure Python 3.4+ is available in your $PATH.
-2. Install the module (try "python" if "python3" is missing): >
+2. Install the module (try "python" if "python3" is missing): >bash
python3 -m pip install --user --upgrade pynvim
The pip `--upgrade` flag ensures that you get the latest version even if
@@ -46,7 +46,7 @@ See also |python-virtualenv|.
Note: The old "neovim" module was renamed to "pynvim".
https://github.com/neovim/neovim/wiki/Following-HEAD#20181118
-If you run into problems, uninstall _both_ then install "pynvim" again: >
+If you run into problems, uninstall _both_ then install "pynvim" again: >bash
python -m pip uninstall neovim pynvim
python -m pip install --user --upgrade pynvim
@@ -55,11 +55,11 @@ PYTHON PROVIDER CONFIGURATION ~
*g:python3_host_prog*
Command to start Python 3 (executable, not directory). Setting this makes
startup faster. Useful for working with virtualenvs. Must be set before any
-check for has("python3"). >
+check for has("python3"). >vim
let g:python3_host_prog = '/path/to/python3'
<
*g:loaded_python3_provider*
-To disable Python 3 support: >
+To disable Python 3 support: >vim
let g:loaded_python3_provider = 0
@@ -70,13 +70,13 @@ virtualenv for Neovim and hard-code the interpreter path via
|g:python3_host_prog| so that the "pynvim" package is not required
for each virtualenv.
-Example using pyenv: >
+Example using pyenv: >bash
pyenv install 3.4.4
pyenv virtualenv 3.4.4 py3nvim
pyenv activate py3nvim
python3 -m pip install pynvim
pyenv which python # Note the path
-The last command reports the interpreter path, add it to your init.vim: >
+The last command reports the interpreter path, add it to your init.vim: >vim
let g:python3_host_prog = '/path/to/py3nvim/bin/python'
See also: https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim
@@ -90,7 +90,7 @@ Nvim supports Ruby |remote-plugin|s and the Vim legacy |ruby-vim| interface
RUBY QUICKSTART ~
-To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >
+To use Ruby plugins with Nvim, install the latest "neovim" RubyGem: >bash
gem install neovim
Run |:checkhealth| to see if your system is up-to-date.
@@ -98,7 +98,7 @@ Run |:checkhealth| to see if your system is up-to-date.
RUBY PROVIDER CONFIGURATION ~
*g:loaded_ruby_provider*
-To disable Ruby support: >
+To disable Ruby support: >vim
let g:loaded_ruby_provider = 0
<
*g:ruby_host_prog*
@@ -106,10 +106,10 @@ Command to start the Ruby host. By default this is "neovim-ruby-host". With
project-local Ruby versions (via tools like RVM or rbenv) setting this can
avoid the need to install the "neovim" gem in every project.
-To use an absolute path (e.g. to an rbenv installation): >
+To use an absolute path (e.g. to an rbenv installation): >vim
let g:ruby_host_prog = '~/.rbenv/versions/2.4.1/bin/neovim-ruby-host'
-To use the RVM "system" Ruby installation: >
+To use the RVM "system" Ruby installation: >vim
let g:ruby_host_prog = 'rvm system do neovim-ruby-host'
==============================================================================
@@ -125,7 +125,7 @@ Note: Only perl versions from 5.22 onward are supported.
PERL QUICKSTART~
-To use perl remote-plugins with Nvim, install the "Neovim::Ext" cpan package: >
+To use perl remote-plugins with Nvim, install the "Neovim::Ext" cpan package: >bash
cpanm -n Neovim::Ext
Run |:checkhealth| to see if your system is up-to-date.
@@ -133,12 +133,12 @@ Run |:checkhealth| to see if your system is up-to-date.
PERL PROVIDER CONFIGURATION~
*g:loaded_perl_provider*
-To disable Perl support: >
+To disable Perl support: >vim
:let g:loaded_perl_provider = 0
<
*g:perl_host_prog*
Command to start the Perl executable. Must be set before any
-check for has("perl"). >
+check for has("perl"). >vim
let g:perl_host_prog = '/path/to/perl'
<
==============================================================================
@@ -150,7 +150,7 @@ https://github.com/neovim/node-client/
NODEJS QUICKSTART~
-To use javascript remote-plugins with Nvim, install the "neovim" npm package: >
+To use javascript remote-plugins with Nvim, install the "neovim" npm package: >bash
npm install -g neovim
Run |:checkhealth| to see if your system is up-to-date.
@@ -158,14 +158,14 @@ Run |:checkhealth| to see if your system is up-to-date.
NODEJS PROVIDER CONFIGURATION~
*g:loaded_node_provider*
-To disable Node.js support: >
+To disable Node.js support: >vim
:let g:loaded_node_provider = 0
<
*g:node_host_prog*
Command to start the Node.js host. Setting this makes startup faster.
By default, Nvim searches for "neovim-node-host" using "npm root -g", which
-can be slow. To avoid this, set g:node_host_prog to the host path: >
+can be slow. To avoid this, set g:node_host_prog to the host path: >vim
let g:node_host_prog = '/usr/local/bin/neovim-node-host'
<
==============================================================================
@@ -176,7 +176,7 @@ a |provider| which transparently uses shell commands to communicate with the
system clipboard or any other clipboard "backend".
To ALWAYS use the clipboard for ALL operations (instead of interacting with
-the '+' and/or '*' registers explicitly): >
+the '+' and/or '*' registers explicitly): >vim
set clipboard+=unnamedplus
See 'clipboard' for details and options.
@@ -199,7 +199,7 @@ registers. Nvim looks for these clipboard tools, in order of priority:
*g:clipboard*
To configure a custom clipboard tool, set g:clipboard to a dictionary.
-For example this configuration integrates the tmux clipboard: >
+For example this configuration integrates the tmux clipboard: >vim
let g:clipboard = {
\ 'name': 'myClipboard',
@@ -219,7 +219,8 @@ the selection until the copy command process dies. When pasting, if the copy
process has not died the cached selection is applied.
g:clipboard can also use functions (see |lambda|) instead of strings.
-For example this configuration uses the g:foo variable as a fake clipboard: >
+For example this configuration uses the g:foo variable as a fake clipboard:
+>vim
let g:clipboard = {
\ 'name': 'myClipboard',
@@ -239,7 +240,7 @@ a list of lines and `regtype` is a register type conforming to |setreg()|.
*clipboard-wsl*
For Windows WSL, try this g:clipboard definition:
->
+>vim
let g:clipboard = {
\ 'name': 'WslClipboard',
\ 'copy': {
@@ -283,7 +284,7 @@ many commands. Use the |cmdline-window| if you really want to paste multiple
lines to the cmdline.
You can implement a custom paste handler by redefining |vim.paste()|.
-Example: >
+Example: >lua
vim.paste = (function(lines, phase)
vim.api.nvim_put(lines, 'c', true, true)
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index 2a131a34dd..847b4b6112 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -76,7 +76,7 @@ supplying an external one with entries for the terminal type.
Settings depending on terminal *term-dependent-settings*
If you want to set terminal-dependent options or mappings, you can do this in
-your init.vim. Example: >
+your init.vim. Example: >vim
if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$'
set notermguicolors
@@ -222,9 +222,9 @@ are not in terminfo you must add them by setting "terminal-overrides" in
~/.tmux.conf .
See the tmux(1) manual page for the details of how and what to do in the tmux
-configuration file. It will look something like: >
+configuration file. It will look something like: >bash
set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q'
-<or (alas!) for Konsole 18.07.70 or older, something more complex like: >
+<or (alas!) for Konsole 18.07.70 or older, something more complex like: >bash
set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007'
<
==============================================================================
@@ -262,7 +262,7 @@ See the "Options" chapter |options|.
If you are using a color terminal that is slow when displaying lines beyond
the end of a buffer, this is because Nvim is drawing the whitespace twice, in
-two sets of colours and attributes. To prevent this, use this command: >
+two sets of colours and attributes. To prevent this, use this command: >vim
hi NonText cterm=NONE ctermfg=NONE
This draws the spaces with the default colours and attributes, which allows the
second pass of drawing to be optimized away. Note: Although in theory the
@@ -372,7 +372,7 @@ that has a match selects until that match (like using "v%"). If the match is
an #if/#else/#endif block, the selection becomes linewise.
For MS-Windows and xterm the time for double clicking can be set with the
'mousetime' option. For the other systems this time is defined outside of Vim.
-An example, for using a double click to jump to the tag under the cursor: >
+An example, for using a double click to jump to the tag under the cursor: >vim
:map <2-LeftMouse> :exe "tag " .. expand("<cword>")<CR>
Dragging the mouse with a double click (button-down, button-up, button-down
@@ -410,23 +410,23 @@ The X1 and X2 buttons refer to the extra buttons found on some mice. The
'Microsoft Explorer' mouse has these buttons available to the right thumb.
Currently X1 and X2 only work on Win32 and X11 environments.
-Examples: >
+Examples: >vim
:noremap <MiddleMouse> <LeftMouse><MiddleMouse>
Paste at the position of the middle mouse button click (otherwise the paste
-would be done at the cursor position). >
+would be done at the cursor position). >vim
:noremap <LeftRelease> <LeftRelease>y
Immediately yank the selection, when using Visual mode.
Note the use of ":noremap" instead of "map" to avoid a recursive mapping.
->
+>vim
:map <X1Mouse> <C-O>
:map <X2Mouse> <C-I>
Map the X1 and X2 buttons to go forwards and backwards in the jump list, see
|CTRL-O| and |CTRL-I|.
*mouse-swap-buttons*
-To swap the meaning of the left and right mouse buttons: >
+To swap the meaning of the left and right mouse buttons: >vim
:noremap <LeftMouse> <RightMouse>
:noremap <LeftDrag> <RightDrag>
:noremap <LeftRelease> <RightRelease>
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index dfaff672e6..cef48e207f 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -24,7 +24,7 @@ via a plugin like https://github.com/nvim-treesitter/nvim-treesitter.
Parsers are searched for as `parser/{lang}.*` in any 'runtimepath' directory.
If multiple parsers for the same language are found, the first one is used.
(This typically implies the priority "user config > plugins > bundled".
-A parser can also be loaded manually using a full path: >
+A parser can also be loaded manually using a full path: >lua
vim.treesitter.require_language("python", "/path/to/python.so")
<
@@ -37,7 +37,7 @@ file), multiple parsers may be needed to parse the full buffer. These are
combined in a |LanguageTree| object.
To create a LanguageTree (parser object) for a buffer and a given language,
-use >
+use >lua
tsparser = vim.treesitter.get_parser(bufnr, lang)
<
@@ -46,7 +46,7 @@ Currently, the parser will be retained for the lifetime of a buffer but this
is subject to change. A plugin should keep a reference to the parser object as
long as it wants incremental updates.
-Whenever you need to access the current syntax tree, parse the buffer: >
+Whenever you need to access the current syntax tree, parse the buffer: >lua
tstree = tsparser:parse()
<
@@ -366,10 +366,10 @@ queries that make them available.
As an additional rule, capture highlights can always be specialized by
language, by appending the language name after an additional dot. For
-instance, to highlight comments differently per language: >
+instance, to highlight comments differently per language: >vim
hi @comment.c guifg=Blue
- hi @comment.lua @guifg=DarkBlue
+ hi @comment.lua guifg=DarkBlue
hi link @comment.doc.java String
<
The following captures are linked by default to standard |group-name|s:
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 5d1788be1b..1cffe1f902 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -119,7 +119,7 @@ for forward-compatibility. |api-contract|
UI startup *ui-startup*
UI embedders (clients that start Nvim with |--embed| and later call
-|nvim_ui_attach()|) must start Nvim without |--headless|: >
+|nvim_ui_attach()|) must start Nvim without |--headless|: >bash
nvim --embed
Nvim will pause before loading startup files and reading buffers, so the UI
has a chance to invoke requests and do early initialization. Startup will
@@ -138,7 +138,7 @@ procedure:
to set |g:| variables visible to init.vim
3. If the UI wants to do additional setup after user config is loaded,
- register a VimEnter autocmd: >
+ register a VimEnter autocmd: >vim
nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now:
@@ -722,7 +722,7 @@ For command-line 'wildmenu' UI events, activate |ui-popupmenu|.
["cmdline_block_show", lines] ~
Show a block of context to the current command line. For example if
- the user defines a |:function| interactively: >
+ the user defines a |:function| interactively: >vim
:function Foo()
: echo "foo"
:
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index b5222c9ddd..6a2e74eaf5 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -73,7 +73,7 @@ centralized reference of the differences.
- 'wildoptions' defaults to "pum,tagfile"
- |man.lua| plugin is enabled, so |:Man| is available by default.
-- |matchit| plugin is enabled. To disable it in your config: >
+- |matchit| plugin is enabled. To disable it in your config: >vim
:let loaded_matchit = 1
- |g:vimsyn_embed| defaults to "l" to enable Lua highlighting
@@ -88,11 +88,11 @@ typing ":".
If you don't like this you can disable the mouse in your |config| using any of
the following:
-- Disable mouse completely by unsetting the 'mouse' option: >
+- Disable mouse completely by unsetting the 'mouse' option: >vim
set mouse=
-- Pressing <RightMouse> extends selection instead of showing popup-menu: >
+- Pressing <RightMouse> extends selection instead of showing popup-menu: >vim
set mousemodel=extend
-- Pressing <A-LeftMouse> releases mouse until the cursor moves: >
+- Pressing <A-LeftMouse> releases mouse until the cursor moves: >vim
nnoremap <A-LeftMouse> <Cmd>
\ set mouse=<Bar>
\ echo 'mouse OFF until next cursor-move'<Bar>
@@ -104,7 +104,7 @@ Default Mappings ~
*default-mappings*
Nvim creates the following default mappings at |startup|. You can disable any
of these in your config by simply removing the mapping, e.g. ":unmap Y".
->
+>vim
nnoremap Y y$
nnoremap <C-L> <Cmd>nohlsearch<Bar>diffupdate<Bar>normal! <C-L><CR>
inoremap <C-U> <C-G>u<C-U>
@@ -302,7 +302,7 @@ are always available and may be used simultaneously. See |provider-python|.
structures.
2. |string()| fails immediately on nested containers, not when recursion limit
was exceeded.
-2. When |:echo| encounters duplicate containers like >
+2. When |:echo| encounters duplicate containers like >vim
let l = []
echo [l, l]
@@ -462,7 +462,7 @@ TUI:
<
*'term'* *E529* *E530* *E531*
'term' reflects the terminal type derived from |$TERM| and other environment
- checks. For debugging only; not reliable during startup. >
+ checks. For debugging only; not reliable during startup. >vim
:echo &term
< "builtin_x" means one of the |builtin-terms| was chosen, because the expected
terminfo file was not found on the system.
@@ -568,7 +568,7 @@ Events:
Highlight groups:
*hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim
supports 'winhighlight' window-local highlights.
- For example, to mimic Vim's StatusLineTerm: >
+ For example, to mimic Vim's StatusLineTerm: >vim
hi StatusLineTerm ctermfg=black ctermbg=green
hi StatusLineTermNC ctermfg=green
autocmd TermOpen,WinEnter * if &buftype=='terminal'
@@ -604,7 +604,7 @@ Options:
*'imactivatekey'* *'imak'*
*'imstatusfunc'* *'imsf'*
*'insertmode'* *'im'* Use the following script to emulate 'insertmode':
->
+>vim
autocmd BufWinEnter * startinsert
inoremap <Esc> <C-X><C-Z><C-]>
inoremap <C-C> <C-X><C-Z>