From 673d2b52fa4335aa083c52e6686f0728e25b8ebd Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Tue, 7 Mar 2023 16:04:57 +0100
Subject: refactor!: rename vim.pretty_print => vim.print

Problem:
The function name `vim.pretty_print`:
1. is verbose, which partially defeats its purpose as sugar
2. does not draw from existing precedent or any sort of convention
   (except external projects like penlight or python?), which reduces
   discoverability, and degrades signaling about best practices.

Solution:
- Rename to `vim.print`.
- Change the behavior so that
  1. strings are printed without quotes
  2. each arg is printed on its own line
  3. tables are indented with 2 instead of 4 spaces
- Example:
  :lua ='a', 'b', 42, {a=3}
  a
  b
  42
  {
    a = 3
  }

Comparison of alternatives:
- `vim.print`:
  - pro: consistent with Lua's `print()`
  - pro: aligns with potential `nvim_print` API function which will
    replace nvim_echo, nvim_notify, etc.
  - con: behaves differently than Lua's `print()`, slightly misleading?
- `vim.echo`:
  - pro: `:echo` has similar "pretty print" behavior.
  - con: inconsistent with Lua idioms.
- `vim.p`:
  - pro: very short, fits with `vim.o`, etc.
  - con: not as discoverable as "echo"
  - con: less opportunity for `local p = vim.p` because of potential shadowing.
---
 runtime/doc/lua.txt | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

(limited to 'runtime/doc/lua.txt')

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: ~
-- 
cgit