refactor: rename smart_open() to sbuffer()

Trying to reduce the number of entities that have "open" in the name, to
reduce confusion.

Author: wincent

ARCHITECTURE.md

@@ -7,7 +7,7 @@ There are two generic classes of "finders", that are paired with corresponding g
 1. **"List"-based finders and scanners.** These take a list of candidate haystacks, like a list of buffers, a list of help tags, or a list of search patterns. These are accessed by commands like `:CommandTBuffer`, `:CommandTHelp`, and `:CommandTSearch`.
 2. **"Command"-based finders and scanners.** These run a command to generate the list of candidate haystacks. These are accessed by commands like `:CommandTGit` and `:CommandTRipgrep`.
 
-Each instance of a list or command-based finder is defined using a Lua table. Finders definitions are found under `finders`, and define either `candidates` (a list of candidates, or a function that returns such a list) or `command` (a command string, or a function that returns such a string).
+Each instance of a list or command-based finder is defined using a Lua table. Finder definitions are found under `finders`, and specify either `candidates` (a list of candidates, or a function that returns such a list) or `command` (a command string, or a function that returns such a string).
 
 There are also two specialised "finder" and "scanner" pairs:
 
@@ -18,7 +18,7 @@ These finders are hard-coded in the Command-T source code as functions.
 
 In the following discussion, note that there are a few sets of confusing, overlapping, or overloading terms that would make a good target for refactoring:
 
-- "open", "on_open", "opener", "smart_open": used at various layers of abstraction for configuration key names, callbacks, parameters, and so on.
+- "open", "on_open", "opener": used at various layers of abstraction for configuration key names, callbacks, parameters, and so on.
 - "config" vs "options": used to describe user-supplied settings, defaults, and also function-level parameters.
 
 ## List-based finder life-cycle
@@ -39,7 +39,7 @@ In the following discussion, note that there are a few sets of confusing, overla
     1.  It looks up the finder config under the `name` key (`'buffer'`, for example) of the user's settings (obtained via a call to `commandt.options()`, which returns a _copy_ of the user's settings, or falls back to the defaults if there are no explicit user settings).
     2.  If the config defines an `options` callback, it calls the callback with the existing options so that it has an opportunity to transform those options, and then sanitizes them. This is used by several finders to force the display of dotfiles (ie. by unconditionally setting `always_show_dot_files` to `true`, and `never_show_dot_files` to `false`); specifically, the `'buffer'`, `'help'`, `'history'`, `'jump'`, `'line'`, `'search'`, and `'tag'` finders.
     3.  If the config defines an `on_directory` callback, it calls the callback with the directory to give it the opportunity to transform the directory. This is used by finders which change their root directory based on the `commandt.traverse` setting; if no directory is provided, and the user settings require it, the callback will attempt to infer an appropriate directory, using the current working directory as a fallback. Finders which use `on_directory` include `'fd'`, `'find'`, `'git'`, and `'rg'`.
-    4.  It prepares an `open` callback with signature `open(item, ex_command)` and assigns it back to the `options` object that will be passed into the `finders.list` or `finders.command` implementation, and also into `ui.show()`. This `open` callback will in turn forward to the `open` implementation specified in the config, if provided, otherwise falling back to `commandt.open(item, ex_command)` which is otherwise known as `smart_open(buffer, command)` (it's called "smart" because it tries to intelligently pick the right place to open the requested buffer). Finders which specify a custom `'open'` in their config include `'fd'`, `'find'`, `'git'`, and `'rg'`; which all pass in an `on_open(item, ex_command, directory, _options, opener, _context)` implementation which uses the `opener` to open a relativized path (ie. `opener(relativize(directory, item), ex_command)`); note that the `opener` here is actually `commandt.open` (ie. `smart_open()`). In contrast, the `'help'`, `'history'`, `'line'`, `'search'`, and `'tag'` finders define totally custom open callbacks. Finally, the `'buffer'` and `'jump'` finders define nothing, which means they use the fallback.
+    4.  It prepares an `open` callback with signature `open(item, ex_command)` and assigns it back to the `options` object that will be passed into the `finders.list` or `finders.command` implementation, and also into `ui.show()`. This `open` callback will in turn forward to the `open` implementation specified in the config, if provided, otherwise falling back to `commandt.open(item, ex_command)` which is otherwise known as `sbuffer(buffer, command)` (it's called "smart" because it tries to intelligently pick the right place to open the requested buffer). Finders which specify a custom `'open'` in their config include `'fd'`, `'find'`, `'git'`, and `'rg'`; which all pass in an `on_open(item, ex_command, directory, _options, opener, _context)` implementation which uses the `opener` to open a relativized path (ie. `opener(relativize(directory, item), ex_command)`); note that the `opener` here is actually `commandt.open` (ie. `sbuffer()`). In contrast, the `'help'`, `'history'`, `'line'`, `'search'`, and `'tag'` finders define totally custom open callbacks. Finally, the `'buffer'` and `'jump'` finders define nothing, which means they use the fallback.
     5.  If the finder config provides a `candidates` field, it obtains the actual list finder and context by passing in the `directory`, `config.candidates`, and `options`. Otherwise, it must contain a `command` field and it obtains a command finder passing in `directory`, `config.command`, `options`, and `name` (the `name` is used to look up finder-specific settings in the `options`).
     6.  If the finder config provides a `fallback` field set to `true`, it adds the fallback finder to the `finder` object, passing in the original `finder`, `directory`, and `options` (this fallback finder is a lazy wrapper around the built-in file finder, which gets invoked if the primary finder fails.
     7.  It invokes `ui.show()`, passing in the `finder` and `options`, merging in three additional settings: `name`, `mode` (`mode` is `'virtual'`, `'file'` or `nil`), and an `on_close` callback set to `config.on_close`. Finders which actually specify an `on_close` are `'fd'`, `'find'`, `'rg'`, and the built-in file finders; they all use `popd` for this purpose, to reset to the original working directory in case the user specified a temporary directory as an argument to those finders (the watchman finder doesn't need this as it does not change into a temporary directory even when the user specifies a directory argument).

lua/wincent/commandt/init.lua

@@ -19,7 +19,7 @@ local commandt = {}
 --- @param buffer string
 --- @param command 'edit' | 'split' | 'tabedit' | 'vsplit'
 --- @return nil
-local function smart_open(buffer, command)
+local function sbuffer(buffer, command)
   buffer = vim.fn.fnameescape(buffer)
   local is_visible = require('wincent.commandt.private.buffer_visible')(buffer)
   if is_visible then
@@ -733,7 +733,7 @@ local default_options = {
   prompt = {
     border = { '┌', '─', '┐', '│', '┤', '─', '├', '│' }, -- 'double', 'none', 'rounded', 'shadow', 'single', 'solid', 'winborder', or a list of strings.
   },
-  open = smart_open,
+  open = sbuffer,
   root_markers = { '.git', '.hg', '.svn', '.bzr', '_darcs' },
   scanners = {
     fd = {
@@ -908,8 +908,8 @@ commandt.pushd = pushd
 commandt.on_directory = on_directory
 -- TODO: maybe rename this
 commandt.on_open = on_open
--- TODO: probably rename this to smart_open
-commandt.open = smart_open
+-- TODO: rename `commandt.open` to `commandt.sbuffer`?
+commandt.open = sbuffer
 
 commandt.options = function()
   return copy(_options or commandt.default_options())