feat(ALL)!: stop forcing option values behind set_vim_settings

Details:
- Instead set them automatically in `setup()` if not set by user/plugin
  before it (no matter the value).
  Document this as a new general principle to be followed in the future.

  The general idea behind this principle is that if user sets the
  particular option prior to `setup()`, then it is assumed to be
  intentional and the module should not interfere. For example, setting
  fuzzy support for 'mini.completion' (with
  `vim.o.completeopt = 'menuone,noselect,fuzzy'`) should be possible to
  do independently of `require('mini.completion').setup()`.

Author: echasnovski

CHANGELOG.md

@@ -10,6 +10,12 @@
 
 - BREAKING FEATURE: Unify how module-related buffers are named: `mini<module-name>://<buffer-number>/<useful-info>`. This structure allows creating identifiable, reasonably unique, and useful buffer names. This is a user facing change because in some cases the shown buffer's name will change (like in statusline of opened 'mini.starter' buffer or output of `:buffers!`).
 
+- BREAKING FEATURE: stop forcing recommended option values behind `set_vim_settings` config setting. Instead set them automatically in `setup()` if not set by user/plugin before it (no matter the value). Document this as a new general principle to be followed in the future. Affected modules:
+    - 'mini.bufremove' (do nothing as recommended 'hidden' is on by default)
+    - 'mini.completion' (set 'completeopt=menuone,noselect' and flags "cC" in 'shortmess')
+    - 'mini.statusline' (do nothing as recommended 'laststatus=2' is default)
+    - 'mini.tabline' (set 'showtabline=2')
+
 ## mini.ai
 
 - FEATURE: textobject identifier can now be any single character supported by `:h getcharstr()`. This also makes it possible to use characters outside of Latin alphanumeric and punctuation sets as `custom_textobjects` keys. Default textobject is extended to be anything but Latin letters (to fall back to `:h text-objects`).

README.md

@@ -161,6 +161,8 @@ These modules don't quite fit in any of the previous categories.
 
     - Values of `config` which affect runtime activity can be changed on the fly to have effect. For example, `MiniSurround.config.n_lines` can be changed during runtime; but changing `MiniSurround.config.mappings` won't have any effect (as mappings are created once during `setup()`).
 
+    - If module works best with some specific non-default option value, it is set during `setup()` but only if it was not explicitly set (by user or another plugin, no matter the value) before that.
+
 - **Buffer local configuration**. Each module can be additionally configured to use certain runtime config settings locally to buffer. See `mini.nvim-buffer-local-config` section in help file for more information.
 
 - **Buffer names**. All module-related buffers are named according to the following format: `mini<module-name>://<buffer-number>/<useful-info>` (forward slashes are used on any platform; `<useful-info>` may be empty). This structure allows creating identifiable, reasonably unique, and useful buffer names. For example, 'mini.files' buffers are created per displayed directory/file with names like `minifiles://10/path/to/displayed/directory`.

doc/mini-bufremove.txt

@@ -61,9 +61,6 @@ Module config
 Default values:
 >lua
   MiniBufremove.config = {
-    -- Whether to set Vim's settings for buffers (allow hidden buffers)
-    set_vim_settings = true,
-
     -- Whether to disable showing non-error feedback
     silent = false,
   }

doc/mini-completion.txt

@@ -80,6 +80,13 @@ You can override runtime config settings locally to buffer inside
 `vim.b.minicompletion_config` which should have same structure as
 `MiniCompletion.config`. See |mini.nvim-buffer-local-config| for more details.
 
+# Suggested option values ~
+
+Some options are set automatically (if not set before |MiniCompletion.setup()|):
+- 'completeopt' is set to "menuone,noselect" for less intrusive popup.
+  To enable fuzzy matching, manually set to "menuone,noselect,fuzzy".
+- 'shortmess' is appended with "c" flag for silent <C-n> fallback.
+
 # Snippets ~
 
 As per LSP specification, some completion items can be supplied in the form of
@@ -280,10 +287,6 @@ Default values:
       scroll_down = '<C-f>',
       scroll_up = '<C-b>',
     },
-
-    -- Whether to set Vim's settings for better experience (modifies
-    -- `shortmess` and `completeopt`)
-    set_vim_settings = true,
   }
 <
 ------------------------------------------------------------------------------

doc/mini-statusline.txt

@@ -149,9 +149,6 @@ Default values:
 
     -- Whether to use icons by default
     use_icons = true,
-
-    -- Whether to set Vim's settings for statusline (make it always shown)
-    set_vim_settings = true,
   }
 <
 ------------------------------------------------------------------------------

doc/mini-tabline.txt

@@ -50,6 +50,11 @@ You can override runtime config settings locally to buffer inside
 `vim.b.minitabline_config` which should have same structure as
 `MiniTabline.config`. See |mini.nvim-buffer-local-config| for more details.
 
+# Suggested option values ~
+
+Some options are set automatically (if not set before |MiniTabline.setup()|):
+- 'showtabline' is set to 2 to always show tabline.
+
 # Highlight groups ~
 
 * `MiniTablineCurrent` - buffer is current (has cursor in it).
@@ -101,10 +106,6 @@ Default values:
     -- By default surrounds with space and possibly prepends with icon
     format = nil,
 
-    -- Whether to set Vim's settings for tabline (make it always shown and
-    -- allow hidden buffers)
-    set_vim_settings = true,
-
     -- Where to show tabpage section in case of multiple vim tabpages.
     -- One of 'left', 'right', 'none'.
     tabpage_section = 'left',

doc/mini.txt

@@ -96,6 +96,10 @@ Table of contents:
       `MiniSurround.config.mappings` won't have any effect (as mappings are
       created once during `setup()`).
 
+    - If module works best with some specific non-default option value, it is
+      set during `setup()` but only if it was not explicitly set (by user or
+      another plugin, no matter the value) before that.
+
 - <Buffer local configuration>. Each module can be additionally configured
   to use certain runtime config settings locally to buffer.
   See |mini.nvim-buffer-local-config| for more information.
@@ -386,9 +390,8 @@ Automated disabling is suggested to be done inside autocommands: >lua
 Buffer local config
 
 Each module can be additionally configured locally to buffer by creating
-appropriate buffer-scoped variable with values you want to override. It
-will affect only runtime options and not those used once during setup (like
-`mappings` or `set_vim_settings`).
+appropriate buffer-scoped variable with values to override. It affects only
+runtime options and not those used once during setup (like most `mappings`).
 
 Variable names have the same structure: `b:mini*_config` where `*` is
 module's lowercase name. For example, `b:minianimate_config` can store

lua/mini/bufremove.lua

@@ -84,9 +84,6 @@ end
 --- Default values:
 ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
 MiniBufremove.config = {
-  -- Whether to set Vim's settings for buffers (allow hidden buffers)
-  set_vim_settings = true,
-
   -- Whether to disable showing non-error feedback
   silent = false,
 }
@@ -189,19 +186,12 @@ H.setup_config = function(config)
   H.check_type('config', config, 'table', true)
   config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})
 
-  H.check_type('set_vim_settings', config.set_vim_settings, 'boolean')
   H.check_type('silent', config.silent, 'boolean')
 
   return config
 end
 
-H.apply_config = function(config)
-  MiniBufremove.config = config
-
-  if config.set_vim_settings then
-    vim.o.hidden = true -- Allow hidden buffers
-  end
-end
+H.apply_config = function(config) MiniBufremove.config = config end
 
 H.is_disabled = function() return vim.g.minibufremove_disable == true or vim.b.minibufremove_disable == true end
 

lua/mini/completion.lua

@@ -80,6 +80,13 @@
 --- `vim.b.minicompletion_config` which should have same structure as
 --- `MiniCompletion.config`. See |mini.nvim-buffer-local-config| for more details.
 ---
+--- # Suggested option values ~
+---
+--- Some options are set automatically (if not set before |MiniCompletion.setup()|):
+--- - 'completeopt' is set to "menuone,noselect" for less intrusive popup.
+---   To enable fuzzy matching, manually set to "menuone,noselect,fuzzy".
+--- - 'shortmess' is appended with "c" flag for silent <C-n> fallback.
+---
 --- # Snippets ~
 ---
 --- As per LSP specification, some completion items can be supplied in the form of
@@ -342,10 +349,6 @@ MiniCompletion.config = {
     scroll_down = '<C-f>',
     scroll_up = '<C-b>',
   },
-
-  -- Whether to set Vim's settings for better experience (modifies
-  -- `shortmess` and `completeopt`)
-  set_vim_settings = true,
 }
 --minidoc_afterlines_end
 
@@ -711,7 +714,6 @@ H.setup_config = function(config)
     H.error('`fallback_action` should be function or string, not ' .. type(config.fallback_action))
   end
   H.check_type('mappings', config.mappings, 'table')
-  H.check_type('set_vim_settings', config.set_vim_settings, 'boolean')
 
   H.check_type('delay.completion', config.delay.completion, 'number')
   H.check_type('delay.info', config.delay.info, 'number')
@@ -762,14 +764,16 @@ H.apply_config = function(config)
   map_scroll(config.mappings.scroll_down, 'down')
   map_scroll(config.mappings.scroll_up, 'up')
 
-  if config.set_vim_settings then
-    -- Don't give ins-completion-menu messages
-    vim.opt.shortmess:append('c')
-    if vim.fn.has('nvim-0.9') == 1 then vim.opt.shortmess:append('C') end
+  -- Try setting suggested option values
+  -- TODO: use `nvim_get_option_info2` after Neovim=0.8 support is dropped
+  -- - More common completion behavior
+  local was_set = vim.api.nvim_get_option_info('completeopt').was_set
+  if not was_set then vim.o.completeopt = 'menuone,noselect' end
 
-    -- More common completion behavior
-    vim.o.completeopt = 'menuone,noselect'
-  end
+  -- - Don't show ins-completion-menu messages ("C" is default on Neovim>=0.10)
+  local shortmess_flags = 'c' .. ((vim.fn.has('nvim-0.9') == 1 and vim.fn.has('nvim-0.10') == 0) and 'C' or '')
+  was_set = vim.api.nvim_get_option_info('shortmess').was_set
+  if not was_set then vim.opt.shortmess:append(shortmess_flags) end
 end
 
 H.create_autocommands = function(config)

lua/mini/init.lua

@@ -96,6 +96,10 @@
 ---       `MiniSurround.config.mappings` won't have any effect (as mappings are
 ---       created once during `setup()`).
 ---
+---     - If module works best with some specific non-default option value, it is
+---       set during `setup()` but only if it was not explicitly set (by user or
+---       another plugin, no matter the value) before that.
+---
 --- - <Buffer local configuration>. Each module can be additionally configured
 ---   to use certain runtime config settings locally to buffer.
 ---   See |mini.nvim-buffer-local-config| for more information.
@@ -384,9 +388,8 @@
 --- Buffer local config
 ---
 --- Each module can be additionally configured locally to buffer by creating
---- appropriate buffer-scoped variable with values you want to override. It
---- will affect only runtime options and not those used once during setup (like
---- `mappings` or `set_vim_settings`).
+--- appropriate buffer-scoped variable with values to override. It affects only
+--- runtime options and not those used once during setup (like most `mappings`).
 ---
 --- Variable names have the same structure: `b:mini*_config` where `*` is
 --- module's lowercase name. For example, `b:minianimate_config` can store

lua/mini/statusline.lua

@@ -176,9 +176,6 @@ MiniStatusline.config = {
 
   -- Whether to use icons by default
   use_icons = true,
-
-  -- Whether to set Vim's settings for statusline (make it always shown)
-  set_vim_settings = true,
 }
 --minidoc_afterlines_end
 
@@ -502,7 +499,6 @@ H.setup_config = function(config)
   H.check_type('content.active', config.content.active, 'function', true)
   H.check_type('content.inactive', config.content.inactive, 'function', true)
 
-  H.check_type('set_vim_settings', config.set_vim_settings, 'boolean')
   H.check_type('use_icons', config.use_icons, 'boolean')
 
   return config
@@ -511,9 +507,6 @@ end
 H.apply_config = function(config)
   MiniStatusline.config = config
 
-  -- Set settings to ensure statusline is displayed properly
-  if config.set_vim_settings and (vim.o.laststatus == 0 or vim.o.laststatus == 1) then vim.o.laststatus = 2 end
-
   -- Set statusline globally and dynamically decide which content to use
   vim.go.statusline =
     '%{%(nvim_get_current_win()==#g:actual_curwin || &laststatus==3) ? v:lua.MiniStatusline.active() : v:lua.MiniStatusline.inactive()%}'

lua/mini/tabline.lua

@@ -50,6 +50,11 @@
 --- `vim.b.minitabline_config` which should have same structure as
 --- `MiniTabline.config`. See |mini.nvim-buffer-local-config| for more details.
 ---
+--- # Suggested option values ~
+---
+--- Some options are set automatically (if not set before |MiniTabline.setup()|):
+--- - 'showtabline' is set to 2 to always show tabline.
+---
 --- # Highlight groups ~
 ---
 --- * `MiniTablineCurrent` - buffer is current (has cursor in it).
@@ -146,10 +151,6 @@ MiniTabline.config = {
   -- By default surrounds with space and possibly prepends with icon
   format = nil,
 
-  -- Whether to set Vim's settings for tabline (make it always shown and
-  -- allow hidden buffers)
-  set_vim_settings = true,
-
   -- Where to show tabpage section in case of multiple vim tabpages.
   -- One of 'left', 'right', 'none'.
   tabpage_section = 'left',
@@ -215,7 +216,6 @@ H.setup_config = function(config)
 
   H.check_type('show_icons', config.show_icons, 'boolean')
   H.check_type('format', config.format, 'function', true)
-  H.check_type('set_vim_settings', config.set_vim_settings, 'boolean')
   H.check_type('tabpage_section', config.tabpage_section, 'string')
 
   return config
@@ -224,11 +224,10 @@ end
 H.apply_config = function(config)
   MiniTabline.config = config
 
-  -- Set settings to ensure tabline is displayed properly
-  if config.set_vim_settings then
-    vim.o.showtabline = 2 -- Always show tabline
-    vim.o.hidden = true -- Allow switching buffers without saving them
-  end
+  -- Try making tabline always visible
+  -- TODO: use `nvim_get_option_info2` after Neovim=0.8 support is dropped
+  local was_set = vim.api.nvim_get_option_info('showtabline').was_set
+  if not was_set then vim.o.showtabline = 2 end
 
   -- Cache truncation characters
   H.cache_trunc_chars()

readmes/mini-bufremove.md

@@ -136,9 +136,6 @@ Here are code snippets for some common installation methods (use only one):
 ```lua
 -- No need to copy this inside `setup()`. Will be used automatically.
 {
-  -- Whether to set Vim's settings for buffers (allow hidden buffers)
-  set_vim_settings = true,
-
   -- Whether to disable showing non-error feedback
   silent = false,
 }

readmes/mini-completion.md

@@ -215,10 +215,6 @@ Here are code snippets for some common installation methods (use only one):
     scroll_down = '<C-f>',
     scroll_up = '<C-b>',
   },
-
-  -- Whether to set Vim's settings for better experience (modifies
-  -- `shortmess` and `completeopt`)
-  set_vim_settings = true,
 }
 ```
 

readmes/mini-statusline.md

@@ -156,9 +156,6 @@ Here are code snippets for some common installation methods (use only one):
 
   -- Whether to use icons by default
   use_icons = true,
-
-  -- Whether to set Vim's settings for statusline (make it always shown)
-  set_vim_settings = true,
 }
 ```
 

readmes/mini-tabline.md

@@ -152,10 +152,6 @@ Here are code snippets for some common installation methods (use only one):
   -- By default surrounds with space and possibly prepends with icon
   format = nil,
 
-  -- Whether to set Vim's settings for tabline (make it always shown and
-  -- allow hidden buffers)
-  set_vim_settings = true,
-
   -- Where to show tabpage section in case of multiple vim tabpages.
   -- One of 'left', 'right', 'none'.
   tabpage_section = 'left',

tests/test_bufremove.lua

@@ -212,14 +212,13 @@ T['setup()']['creates `config` field'] = function()
   eq(child.lua_get('type(_G.MiniBufremove.config)'), 'table')
 
   -- Check default values
-  eq(child.lua_get('MiniBufremove.config.set_vim_settings'), true)
   eq(child.lua_get('MiniBufremove.config.silent'), false)
 end
 
 T['setup()']['respects `config` argument'] = function()
   unload_module()
-  load_module({ set_vim_settings = false })
-  eq(child.lua_get('MiniBufremove.config.set_vim_settings'), false)
+  load_module({ silent = true })
+  eq(child.lua_get('MiniBufremove.config.silent'), true)
 end
 
 T['setup()']['validates `config` argument'] = function()
@@ -230,7 +229,6 @@ T['setup()']['validates `config` argument'] = function()
   end
 
   expect_config_error('a', 'config', 'table')
-  expect_config_error({ set_vim_settings = 'a' }, 'set_vim_settings', 'boolean')
   expect_config_error({ silent = 'a' }, 'silent', 'boolean')
 end