aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--runtime/doc/deprecated.txt1
-rw-r--r--runtime/doc/diagnostic.txt2
-rw-r--r--runtime/doc/lua-guide.txt39
-rw-r--r--runtime/doc/lua.txt17
-rw-r--r--runtime/doc/news.txt2
-rw-r--r--runtime/lua/vim/_editor.lua39
-rw-r--r--runtime/plugin/nvim.lua2
-rw-r--r--src/nvim/lua/executor.c4
-rw-r--r--test/functional/api/vim_spec.lua2
-rw-r--r--test/functional/lua/commands_spec.lua30
-rw-r--r--test/functional/lua/vim_spec.lua21
11 files changed, 102 insertions, 57 deletions
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 3d861b07b3..5c8d7f044f 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -129,6 +129,7 @@ TREESITTER FUNCTIONS
LUA
- *vim.register_keystroke_callback()* Use |vim.on_key()| instead.
+- *vim.pretty_print()* Use |vim.print()| instead.
NORMAL COMMANDS
- *]f* *[f* Same as "gf".
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index cff73ad097..f888bb0991 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -325,7 +325,7 @@ Example: >lua
vim.api.nvim_create_autocmd('DiagnosticChanged', {
callback = function(args)
local diagnostics = args.data.diagnostics
- vim.pretty_print(diagnostics)
+ vim.print(diagnostics)
end,
})
<
diff --git a/runtime/doc/lua-guide.txt b/runtime/doc/lua-guide.txt
index 8ea84f8c60..5e2b753645 100644
--- a/runtime/doc/lua-guide.txt
+++ b/runtime/doc/lua-guide.txt
@@ -10,16 +10,16 @@
==============================================================================
Introduction *lua-guide*
-This guide will go through the basics of using Lua in Neovim. It is not meant
+This guide will go through the basics of using Lua in Nvim. It is not meant
to be a comprehensive encyclopedia of all available features, nor will it
detail all intricacies. Think of it as a survival kit -- the bare minimum
-needed to know to comfortably get started on using Lua in Neovim.
+needed to know to comfortably get started on using Lua in Nvim.
An important thing to note is that this isn't a guide to the Lua language
-itself. Rather, this is a guide on how to configure and modify Neovim through
+itself. Rather, this is a guide on how to configure and modify Nvim through
the Lua language and the functions we provide to help with this. Take a look
at |luaref| and |lua-concepts| if you'd like to learn more about Lua itself.
-Similarly, this guide assumes some familiarity with the basics of Neovim
+Similarly, this guide assumes some familiarity with the basics of Nvim
(commands, options, mappings, autocommands), which are covered in the
|user-manual|.
@@ -27,7 +27,7 @@ Similarly, this guide assumes some familiarity with the basics of Neovim
Some words on the API *lua-guide-api*
The purpose of this guide is to introduce the different ways of interacting
-with Neovim through Lua (the "API"). This API consists of three different
+with Nvim through Lua (the "API"). This API consists of three different
layers:
1. The "Vim API" inherited from Vim: |ex-commands| and |builtin-functions| as
@@ -35,14 +35,14 @@ well as |user-function|s in Vimscript. These are accessed through |vim.cmd()|
and |vim.fn| respectively, which are discussed under |lua-guide-vimscript|
below.
-2. The "Neovim API" written in C for use in remote plugins and GUIs; see |api|.
+2. The "Nvim API" written in C for use in remote plugins and GUIs; see |api|.
These functions are accessed through |vim.api|.
3. The "Lua API" written in and specifically for Lua. These are any other
functions accessible through `vim.*` not mentioned already; see |lua-stdlib|.
This distinction is important, as API functions inherit behavior from their
-original layer: For example, Neovim API functions always need all arguments to
+original layer: For example, Nvim API functions always need all arguments to
be specified even if Lua itself allows omitting arguments (which are then
passed as `nil`); and Vim API functions can use 0-based indexing even if Lua
arrays are 1-indexed by default.
@@ -58,7 +58,7 @@ convenient to use from Lua.
==============================================================================
Using Lua *lua-guide-using-Lua*
-To run Lua code from the Neovim command line, use the |:lua| command:
+To run Lua code from the Nvim command line, use the |:lua| command:
>vim
:lua print("Hello!")
<
@@ -69,10 +69,10 @@ local keyword are not accessible outside of the command. This won't work:
:lua print(foo)
" prints "nil" instead of "1"
<
-You can also use `:lua=`, which is the same as `:lua vim.pretty_print(...)`,
-to conveniently check the value of a variable or a table:
+You can also use `:lua=`, which is equivalent to `:lua vim.print(...)`, to
+conveniently check the value of a variable or a table:
>vim
- :lua=package
+ :lua =package
<
To run a Lua script in an external file, you can use the |:source| command
exactly like for a Vimscript file:
@@ -92,7 +92,7 @@ Finally, you can include Lua code in a Vimscript file by putting it inside a
------------------------------------------------------------------------------
Using Lua files on startup *lua-guide-config*
-Neovim supports using `init.vim` or `init.lua` as the configuration file, but
+Nvim supports using `init.vim` or `init.lua` as the configuration file, but
not both at the same time. This should be placed in your |config| directory,
which is typically `~/.config/nvim` for Linux, BSD, or macOS, and
`~/AppData/Local/nvim/` for Windows. Note that you can use Lua in `init.vim`
@@ -279,7 +279,7 @@ Note that you cannot directly change fields of array variables. This won't
work:
>lua
vim.g.some_global_variable.key2 = 400
- vim.pretty_print(vim.g.some_global_variable)
+ vim.print(vim.g.some_global_variable)
--> { key1 = "value", key2 = 300 }
<
Instead, you need to create an intermediate Lua table and change this:
@@ -287,7 +287,7 @@ Instead, you need to create an intermediate Lua table and change this:
local temp_table = vim.g.some_global_variable
temp_table.key2 = 400
vim.g.some_global_variable = temp_table
- vim.pretty_print(vim.g.some_global_variable)
+ vim.print(vim.g.some_global_variable)
--> { key1 = "value", key2 = 400 }
<
To delete a variable, simply set it to `nil`:
@@ -350,7 +350,7 @@ use |vim.opt:get()|:
--> {...} (big table)
print(vim.opt.smarttab:get())
--> false
- vim.pretty_print(vim.opt.listchars:get())
+ vim.print(vim.opt.listchars:get())
--> { space = '_', tab = '>~' }
<
------------------------------------------------------------------------------
@@ -488,7 +488,7 @@ Autocommands *lua-guide-autocommands*
An |autocommand| is a Vim command or a Lua function that is automatically
executed whenever one or more |events| are triggered, e.g., when a file is
read or written, or when a window is created. These are accessible from Lua
-through the Neovim API.
+through the Nvim API.
------------------------------------------------------------------------------
Creating autocommands *lua-guide-autocommand-create*
@@ -530,7 +530,7 @@ Examples:
})
<
-Neovim will always call a Lua function with a single table containing information
+Nvim will always call a Lua function with a single table containing information
about the triggered autocommand. The most useful keys are
• `match`: a string that matched the `pattern` (see |<amatch>|)
• `buf`: the number of the buffer the event was triggered in (see |<abuf>|)
@@ -667,9 +667,8 @@ cover only the basics of this advanced topic.
------------------------------------------------------------------------------
Creating user commands *lua-guide-commands-create*
-User commands can be created through the Neovim API with
-`vim.api.`|nvim_create_user_command()|. This function takes three mandatory
-arguments:
+User commands can be created through with |nvim_create_user_command()|. This
+function takes three mandatory arguments:
• a string that is the name of the command (which must start with an uppercase
letter to distinguish it from builtin commands);
• a string containing Vim commands or a Lua function that is executed when the
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index bcd68b7608..81e45ae9bb 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1239,7 +1239,7 @@ which is accessed through |vim.opt:get()|:
print(vim.o.wildignore)
<
In Lua using `vim.opt`: >lua
- vim.pretty_print(vim.opt.wildignore:get())
+ vim.print(vim.opt.wildignore:get())
<
In any of the above examples, to replicate the behavior |:setlocal|, use
@@ -1258,7 +1258,7 @@ Option:get()
the values as entries in the array: >lua
vim.cmd [[set wildignore=*.pyc,*.o]]
- vim.pretty_print(vim.opt.wildignore:get())
+ vim.print(vim.opt.wildignore:get())
-- { "*.pyc", "*.o", }
for _, ignore_pattern in ipairs(vim.opt.wildignore:get()) do
@@ -1271,7 +1271,7 @@ Option:get()
the names as keys and the values as entries: >lua
vim.cmd [[set listchars=space:_,tab:>~]]
- vim.pretty_print(vim.opt.listchars:get())
+ vim.print(vim.opt.listchars:get())
-- { space = "_", tab = ">~", }
for char, representation in pairs(vim.opt.listchars:get()) do
@@ -1282,7 +1282,7 @@ Option:get()
as keys and `true` as entries. >lua
vim.cmd [[set formatoptions=njtcroql]]
- vim.pretty_print(vim.opt.formatoptions:get())
+ vim.print(vim.opt.formatoptions:get())
-- { n = true, j = true, c = true, ... }
local format_opts = vim.opt.formatoptions:get()
@@ -1496,10 +1496,11 @@ paste({lines}, {phase}) *vim.paste()*
See also: ~
|paste| @alias paste_phase -1 | 1 | 2 | 3
-pretty_print({...}) *vim.pretty_print()*
- Prints given arguments in human-readable format. Example: >lua
- -- Print highlight group Normal and store it's contents in a variable.
- local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
+print({...}) *vim.print()*
+ "Pretty prints" the given arguments and returns them unmodified.
+
+ Example: >lua
+ local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true))
<
Return: ~
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 48d954fe2d..66e8e5ef9f 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -55,6 +55,8 @@ The following changes may require adaptations in user config or plugins.
- The `concat` option has been removed as it was not consistently applied.
- Invalid ranges now cause an error instead of returning `nil`.
+• Renamed vim.pretty_print to vim.print. |deprecated|
+
==============================================================================
NEW FEATURES *news-features*
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 9516233b45..5445c4e492 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -778,22 +778,37 @@ do
end
end
----Prints given arguments in human-readable format.
----Example:
----<pre>lua
---- -- Print highlight group Normal and store it's contents in a variable.
---- local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
----</pre>
----@see |vim.inspect()|
----@return any # given arguments.
+---@private
function vim.pretty_print(...)
- local objects = {}
+ vim.deprecate('vim.pretty_print', 'vim.print', '0.10')
+ return vim.print(...)
+end
+
+--- "Pretty prints" the given arguments and returns them unmodified.
+---
+--- Example:
+--- <pre>lua
+--- local hl_normal = vim.print(vim.api.nvim_get_hl_by_name('Normal', true))
+--- </pre>
+---
+--- @see |vim.inspect()|
+--- @return any # given arguments.
+function vim.print(...)
+ if vim.in_fast_event() then
+ print(...)
+ return ...
+ end
+
for i = 1, select('#', ...) do
- local v = select(i, ...)
- table.insert(objects, vim.inspect(v))
+ local o = select(i, ...)
+ if type(o) == 'string' then
+ vim.api.nvim_out_write(o)
+ else
+ vim.api.nvim_out_write(vim.inspect(o, { newline = '\n', indent = ' ' }))
+ end
+ vim.api.nvim_out_write('\n')
end
- print(table.concat(objects, ' '))
return ...
end
diff --git a/runtime/plugin/nvim.lua b/runtime/plugin/nvim.lua
index 762e9519db..e4b099f7ad 100644
--- a/runtime/plugin/nvim.lua
+++ b/runtime/plugin/nvim.lua
@@ -1,6 +1,6 @@
vim.api.nvim_create_user_command('Inspect', function(cmd)
if cmd.bang then
- vim.pretty_print(vim.inspect_pos())
+ vim.print(vim.inspect_pos())
else
vim.show_pos()
end
diff --git a/src/nvim/lua/executor.c b/src/nvim/lua/executor.c
index 11a02ea402..819e3cccff 100644
--- a/src/nvim/lua/executor.c
+++ b/src/nvim/lua/executor.c
@@ -1623,12 +1623,12 @@ void ex_lua(exarg_T *const eap)
}
// When =expr is used transform it to print(vim.inspect(expr))
if (code[0] == '=') {
- len += sizeof("vim.pretty_print()") - sizeof("=");
+ len += sizeof("vim.print()") - sizeof("=");
// code_buf needs to be 1 char larger then len for null byte in the end.
// lua nlua_typval_exec doesn't expect null terminated string so len
// needs to end before null byte.
char *code_buf = xmallocz(len);
- vim_snprintf(code_buf, len + 1, "vim.pretty_print(%s)", code + 1);
+ vim_snprintf(code_buf, len + 1, "vim.print(%s)", code + 1);
xfree(code);
code = code_buf;
}
diff --git a/test/functional/api/vim_spec.lua b/test/functional/api/vim_spec.lua
index 48ac491ade..2af041c706 100644
--- a/test/functional/api/vim_spec.lua
+++ b/test/functional/api/vim_spec.lua
@@ -4042,7 +4042,7 @@ describe('API', function()
it('splits arguments correctly for Lua callback', function()
meths.exec_lua([[
local function FooFunc(opts)
- vim.pretty_print(opts.fargs)
+ vim.print(opts.fargs)
end
vim.api.nvim_create_user_command("Foo", FooFunc, { nargs = '+' })
diff --git a/test/functional/lua/commands_spec.lua b/test/functional/lua/commands_spec.lua
index b8346df290..943095c51e 100644
--- a/test/functional/lua/commands_spec.lua
+++ b/test/functional/lua/commands_spec.lua
@@ -8,6 +8,8 @@ local eval = helpers.eval
local feed = helpers.feed
local clear = helpers.clear
local meths = helpers.meths
+local exec_lua = helpers.exec_lua
+local exec_capture = helpers.exec_capture
local funcs = helpers.funcs
local source = helpers.source
local dedent = helpers.dedent
@@ -15,7 +17,6 @@ local command = helpers.command
local exc_exec = helpers.exc_exec
local pcall_err = helpers.pcall_err
local write_file = helpers.write_file
-local exec_capture = helpers.exec_capture
local curbufmeths = helpers.curbufmeths
local remove_trace = helpers.remove_trace
@@ -142,22 +143,29 @@ describe(':lua command', function()
]]}
end)
- it('Can print results of =expr', function()
- helpers.exec_lua("x = 5")
- eq("5", helpers.exec_capture(':lua =x'))
- helpers.exec_lua("function x() return 'hello' end")
- eq([["hello"]], helpers.exec_capture(':lua = x()'))
- helpers.exec_lua("x = {a = 1, b = 2}")
- eq("{\n a = 1,\n b = 2\n}", helpers.exec_capture(':lua =x'))
- helpers.exec_lua([[function x(success)
+ it('prints result of =expr', function()
+ exec_lua("x = 5")
+ eq("5", exec_capture(':lua =x'))
+ exec_lua("function x() return 'hello' end")
+ eq('hello', exec_capture(':lua = x()'))
+ exec_lua("x = {a = 1, b = 2}")
+ eq("{\n a = 1,\n b = 2\n}", exec_capture(':lua =x'))
+ exec_lua([[function x(success)
if success then
return true, "Return value"
else
return false, nil, "Error message"
end
end]])
- eq([[true "Return value"]], helpers.exec_capture(':lua =x(true)'))
- eq([[false nil "Error message"]], helpers.exec_capture(':lua =x(false)'))
+ eq(dedent[[
+ true
+ Return value]],
+ exec_capture(':lua =x(true)'))
+ eq(dedent[[
+ false
+ nil
+ Error message]],
+ exec_capture(':lua =x(false)'))
end)
end)
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 77628487ca..470102df5e 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -6,6 +6,7 @@ local nvim_prog = helpers.nvim_prog
local funcs = helpers.funcs
local meths = helpers.meths
local command = helpers.command
+local dedent = helpers.dedent
local insert = helpers.insert
local clear = helpers.clear
local eq = helpers.eq
@@ -2269,7 +2270,7 @@ describe('lua stdlib', function()
describe('vim.region', function()
it('charwise', function()
- insert(helpers.dedent( [[
+ insert(dedent( [[
text tααt tααt text
text tαxt txtα tex
text tαxt tαxt
@@ -2923,6 +2924,24 @@ describe('lua stdlib', function()
{4:-- Omni completion (^O^N^P) }{5:match 1 of 2} |
]]}
end)
+
+ it('vim.print', function()
+ -- vim.print() returns its args.
+ eq({42, 'abc', { a = { b = 77 }}},
+ exec_lua[[return {vim.print(42, 'abc', { a = { b = 77 }})}]])
+
+ -- vim.print() pretty-prints the args.
+ eq(dedent[[
+
+ 42
+ abc
+ {
+ a = {
+ b = 77
+ }
+ }]],
+ eval[[execute('lua vim.print(42, "abc", { a = { b = 77 }})')]])
+ end)
end)
describe('lua: builtin modules', function()
generated by cgit (git 2.34.1) at 2025-04-29 01:06:34 +0000