refactor: closes #69, move common functionality into new source manager module (#81)

Author: cseickel

README.md

@@ -5,6 +5,34 @@ structures in a sidebar **or** floating window.
 
 ![Neo-tree file system](https://github.com/nvim-neo-tree/resources/raw/main/images/Neo-tree-filesystem.png)
 
+### Breaking Changes BAD :bomb: :imp:
+
+The biggest and most important feature of Neo-tree is that we will never
+knowingly push a breaking change and interrupt your day. Bugs happen, but
+breaking changes can always be avoided. When breaking changes are needed, there
+will be a new branch that you can opt into, when it is a good time for you.
+
+### User Experience GOOD :slightly_smiling_face: :thumbsup:
+
+Aside from being polite about breaking changes, Neo-tree is also focused on the
+little details of user experience. Everything should work exactly as you would
+expect a sidebar to work without all of the glitchy behavior that is normally
+accepted in (neo)vim sidebars. I can't stand glitchy behavior, and neither
+should you!
+
+- Neo-tree won't let other buffers take over it's window.
+- Neo-tree won't leave it's window scrolled to the last line when there is
+  plenty of room to display the whole tree.
+- Neo-tree does not need to be manually refreshed (set `use_libuv_file_watcher=true`)
+- Neo-tree can intelligently follow the current file (set `follow_current_file=true`)
+- Neo-tree is thoughtful about maintaining or setting focus on the right node
+- Neo-tree windows in different tabs are completely separate
+
+Neo-tree is smooth, efficient, stable, and pays attention to the little details.
+If you find anything janky, wanky, broken, or unintuitive, please open an issue
+so we can fix it.
+
+
 ## Quickstart
 
 Example for packer:
@@ -152,7 +180,7 @@ highlighting can also be viewed at the [filesystem README](/lua/neo-tree/sources
 ## Sources
 
 Neo-tree is built on the idea of supporting various sources. Sources are
-basically interface implimentations whose job it is to provide a list of
+basically interface implementations whose job it is to provide a list of
 hierachical items to be rendered, along with commands that are appropriate to
 those items.
 
@@ -180,33 +208,22 @@ filesystem is open in a sidebar:
 ![Neo-tree git_status](https://github.com/nvim-neo-tree/resources/raw/main/images/Neo-tree-git_status.png)
 
 
-
-## Status
-
-This is a fully functional file browser with navigation, mutation,
-git status, and filtering. It can also display a list of open buffers. Other
-sources that may be added include things like tags, treesitter or lsp document
-structures, git status, etc.
-
 ## Configuration and Customization
 
 This is designed to be flexible. The way that is acheived is by making
-everything a function, or a reference to a built-in function. All of the
-built-in functions can be replaced with your own implimentation, or you can 
+everything a function, or a string that identifies a built-in function. All of the
+built-in functions can be replaced with your own implementation, or you can 
 add new ones.
 
 Each node in the tree is created from the renderer specified for the given node
-type, and each renderer is a list of component configs. Each component is a
-function, either built-in or specified in your own the setup() config. Those 
-functions are called with the config, node, and state of the plugin, and return
-the text and highlight group for the component.
-
-Additionally, each source has a `before_render()` function that you can
-override and use to gather any additonal information you want to use in your
-components. This function is currently used to gather the git status and
-diagnostics for the tree. If you want to skip that, override the function and
-leave that part out. If you want to show some other data, gather it in
-`before_render()`, create a component to display it, and reference that
+type, and each renderer is a list of component configs to be rendered in order
+for each node in the tree. Each component is a function, either built-in or
+specified in your config. Those functions are called with the config, node, and
+state of the plugin, and return the text and highlight group for the component.
+
+Additionally, there is an events system that you can hook into. If you want to
+show some new data point related to your files, gather it in the
+`before_render` event, create a component to display it, and reference that
 component in the renderer for the `file` and/or `directory` type.
 
 Details on how to configure everything is in the help file at `:h neo-tree` or
@@ -225,10 +242,8 @@ wanted something that was:
 ### Easy to maintain and enhance
 
 This plugin is designed to grow and be flexible. This is accomplished by making
-the code as decoupled and functional as possible. It shouldn't be necessary to
-touch any of the core plumbing to add new functionality. Aside from bug fixes,
-the code outside of the `sources` directory should not be touched to add new
-features. Hopefully new contributors will find it easy to work with.
+the code as decoupled and functional as possible. Hopefully new contributors
+will find it easy to work with.
 
 One big difference between this plugin and the ones that came before it, which
 is also what finally pushed me over the edge into making a new plugin, is that

doc/neo-tree.txt

@@ -465,23 +465,30 @@ require("neo-tree.events.queue").define_event(event_name, {
   setup = <function>,
   seed = <function>,
   teardown = <function>,
-  debounce_frequency = <number>
+  debounce_frequency = <number>,
+  once = <boolean>,
+  cancelled = <boolean>
 })
 
 The setup function is run the first time the event is subscribed to. For an
 autocmd event, this would define the vim autocmd to connect it to fire_event().
 
-The seed function is run at the begining of every event firing. The diagnostics
+The `seed` function is run at the begining of every event firing. The diagnostics
 event uses this to collect the diagnostic information and pass it to all
 subscribers.
 
-The teardown function is used when the last subscriber unsubscribes, and cleans
+The `teardown` function is used when the last subscriber unsubscribes, and cleans
 up. This is like Dispose in other languages.
 
-debounce_frequency is the minimum number of milliseconds between each invocation
+`debounce_frequenc`y is the minimum number of milliseconds between each invocation
 of the event. The first event is gauranteed to fire, as well as the last one, but
 in between events may be dropped if this is set to a number greater than zero.
 
+`once` means to only fire this event handler once then mark it as `cancelled`.
+
+`cancelled` means that this event handler will be skipped in all future event
+fires, and will be discarded on the next cleanup of the queue.
+
 
 ================================================================================
 OTHER SOURCES                                                                  ~

lua/neo-tree.lua

@@ -7,6 +7,7 @@ local events = require("neo-tree.events")
 local log = require("neo-tree.log")
 local popups = require("neo-tree.ui.popups")
 local highlights = require("neo-tree.ui.highlights")
+local manager = require("neo-tree.sources.manager")
 
 -- If you add a new source, you need to add it to the sources table.
 -- Each source should have a defaults module that contains the default values
@@ -19,7 +20,7 @@ local sources = {
 
 local M = {}
 
--- Adding this as a shortcut because the module path is so long.
+-- TODO: DEPRECATED in 1.19, remove in 2.0
 M.fs = require("neo-tree.sources.filesystem")
 
 local normalize_mappings = function(config)
@@ -68,80 +69,89 @@ local define_events = function()
   events_setup = true
 end
 
-local src = function(source_name)
-  if source_name == nil or source_name == "" then
+local check_source = function(source_name)
+  if not utils.truthy(source_name) then
     source_name = M.config.default_source
   end
-  local success, source = pcall(require, "neo-tree.sources." .. source_name)
+  local success, result = pcall(require, "neo-tree.sources." .. source_name)
   if not success then
-    error("Source " .. source_name .. " not found.")
+    error("Source " .. source_name .. " could not be loaded: ", result)
   end
-  source.name = source_name
-  return source
+  return source_name
 end
 
 M.close_all_except = function(source_name)
-  local source = src(source_name)
-  local target_pos = utils.get_value(M, "config." .. source.name .. ".window.position", "left")
+  source_name = check_source(source_name)
+  local target_pos = utils.get_value(M, "config." .. source_name .. ".window.position", "left")
   for _, name in ipairs(sources) do
     if name ~= source_name then
       local pos = utils.get_value(M, "config." .. name .. ".window.position", "left")
       if pos == target_pos then
-        M.close(name)
+        manager.close(source_name)
       end
     end
   end
-  M.close_all("float")
+  renderer.close_all_floating_windows()
 end
 
-M.close = function(source_name)
-  return src(source_name).close()
-end
+M.close = manager.close
 
 M.close_all = function(at_position)
   renderer.close_all_floating_windows()
   if type(at_position) == "string" and at_position > "" then
     for _, name in ipairs(sources) do
       local pos = utils.get_value(M, "config." .. name .. ".window.position", "left")
       if pos == at_position then
-        M.close(name)
+        manager.close(name)
       end
     end
   else
     for _, name in ipairs(sources) do
-      M.close(name)
+      manager.close(name)
     end
   end
 end
 
 M.float = function(source_name, toggle_if_open)
-  source_name = src(source_name).name
+  source_name = check_source(source_name)
   if toggle_if_open then
     if renderer.close_floating_window(source_name) then
       -- It was open, and now it's not.
       return
     end
   end
-  M.close_all("float")
-  M.close(source_name) -- in case this source is open in a sidebar
-  src(source_name).float()
+  renderer.close_all_floating_windows()
+  manager.close(source_name) -- in case this source is open in a sidebar
+  manager.float(source_name)
 end
 
+--TODO: Remove the close_others option in 2.0
 M.focus = function(source_name, close_others, toggle_if_open)
+  source_name = check_source(source_name)
   if toggle_if_open then
-    if M.close(source_name) then
+    if manager.close(source_name) then
       -- It was open, and now it's not.
       return
     end
   end
   if close_others == nil then
     close_others = true
   end
-  local source = src(source_name)
   if close_others then
-    M.close_all_except(source.name)
+    M.close_all_except(source_name)
+  end
+  manager.focus(source_name)
+end
+
+M.reveal_current_file = function(source_name, toggle_if_open)
+  source_name = check_source(source_name)
+  if toggle_if_open then
+    if manager.close(source_name) then
+      -- It was open, and now it's not.
+      return
+    end
   end
-  source.focus()
+  manager.reveal_current_file(source_name)
 end
 
 M.get_prior_window = function()
@@ -199,27 +209,25 @@ M.win_enter_event = function()
   end
 end
 
+--TODO: Remove the do_not_focus and close_others options in 2.0
 M.show = function(source_name, do_not_focus, close_others, toggle_if_open)
+  source_name = check_source(source_name)
   if toggle_if_open then
-    if M.close(source_name) then
+    if manager.close(source_name) then
       -- It was open, and now it's not.
       return
     end
   end
   if close_others == nil then
     close_others = true
   end
-  local source = src(source_name)
   if close_others then
-    M.close_all_except(source.name)
+    M.close_all_except(source_name)
   end
   if do_not_focus then
-    local current_win = vim.api.nvim_get_current_win()
-    source.show(function()
-      vim.api.nvim_set_current_win(current_win)
-    end)
+    manager.show(source_name)
   else
-    source.show()
+    manager.focus(source_name)
   end
 end
 
@@ -308,7 +316,7 @@ M.setup = function(config)
 
   -- setup the sources with the combined config
   for _, source_name in ipairs(sources) do
-    src(source_name).setup(M.config[source_name], M.config)
+    manager.setup(source_name, M.config[source_name], M.config)
   end
 
   local event_handler = {

lua/neo-tree/sources/buffers/commands.lua

@@ -4,41 +4,42 @@ local vim = vim
 local cc = require("neo-tree.sources.common.commands")
 local buffers = require("neo-tree.sources.buffers")
 local utils = require("neo-tree.utils")
+local manager = require("neo-tree.sources.manager")
 
 local M = {}
 
 M.add = function(state)
-  cc.add(state, buffers.refresh)
+  cc.add(state, M.refresh)
 end
 
 M.buffer_delete = function(state)
   local node = state.tree:get_node()
   if node then
     vim.api.nvim_buf_delete(node.extra.bufnr, { force = false, unload = false })
-    buffers.refresh()
+    M.refresh()
   end
 end
 M.close_node = cc.close_node
 
 ---Marks node as copied, so that it can be pasted somewhere else.
 M.copy_to_clipboard = function(state)
-  cc.copy_to_clipboard(state, buffers.redraw)
+  cc.copy_to_clipboard(state, utils.wrap(manager.redraw, "buffers"))
 end
 
 ---Marks node as cut, so that it can be pasted (moved) somewhere else.
 M.cut_to_clipboard = function(state)
-  cc.cut_to_clipboard(state, buffers.redraw)
+  cc.cut_to_clipboard(state, utils.wrap(manager.redraw, "buffers"))
 end
 
 M.show_debug_info = cc.show_debug_info
 
 ---Pastes all items from the clipboard to the current directory.
 M.paste_from_clipboard = function(state)
-  cc.paste_from_clipboard(state, buffers.refresh)
+  cc.paste_from_clipboard(state, M.refresh)
 end
 
 M.delete = function(state)
-  cc.delete(state, buffers.refresh)
+  cc.delete(state, M.refresh)
 end
 
 ---Navigate up one level.
@@ -51,10 +52,10 @@ M.open = cc.open
 M.open_split = cc.open_split
 M.open_vsplit = cc.open_vsplit
 
-M.refresh = buffers.refresh
+M.refresh = utils.wrap(manager.refresh, "buffers")
 
 M.rename = function(state)
-  cc.rename(state, buffers.refresh)
+  cc.rename(state, M.refresh)
 end
 
 M.set_root = function(state)