cleaning up unneeded files - telescope, util/ft, etc.

Author: clpi

doc/down.txt

@@ -7,11 +7,11 @@
 ---@tags markdown, org-mode, note-taking, knowledge-management, developer-tools, productivity
 ---
 ---@brief The Neovim plugin for the *down* _markdown_ developer-focused
----@briefnote-taking and knowledge management environment, offering the comfort familiarity, and compatibility of a traditional markdown note-taking environment with the power of org-mode.
+---@brief note-taking and knowledge management environment, offering the comfort familiarity, and compatibility of a traditional markdown note-taking environment with the power of org-mode.
 
 --- The main entry point for the down plugin
 ---@class down.Down
-local Down = {
+Down = {
   --- The configuration for the plugin
   config = require("down.config"),
   --- The module logic for the plugin
@@ -34,7 +34,7 @@ Down.setup = function(user, ...)
   Down:start()
 end
 
---- Start the plugin
+--- *Start* the ^down.nvim^ plugin
 --- Load the workspace and user modules
 function Down:start()
   self.util.log.trace("Setting up down")
@@ -54,7 +54,7 @@ end
 function Down:after()
   self.config:after()
   for _, l in pairs(self.mod.mods) do
-    self.event.load_cb(l)
+    self.event.load_callback(l)
     l.after()
   end
   self:broadcast("started")

lua/down.lua

@@ -0,0 +1,4 @@
+--- Autocmd module.
+local Autocmd = {}
+
+return Autocmd

lua/down/event/autocmd.lua

@@ -0,0 +1,3 @@
+local Callback = {}
+
+return Callback

lua/down/event/callback.lua

@@ -33,9 +33,10 @@ local Event = {
   },
 }
 
+--- Callback
 --- @class down.Callback
----   @field callbacks table<string, { [1]: fun(event: down.Event, content: table|any), [2]?: fun(event: down.Event): boolean }>
-local Cb = {
+---   @field cb table<string, { [1]: fun(event: down.Event, content: table|any), [2]?: fun(event: down.Event): boolean }>
+local Callback = {
   ---@type table<string, { [1]: fun(event: down.Event, content: table|any), [2]?: fun(event: down.Event): boolean }>
   cb = {},
 
@@ -44,9 +45,9 @@ local Cb = {
 }
 
 --- @param ty? string
---- @return { [1]: fun(event: down.Event, content: table|any)> }
+--- @return { [1]: fun(event: down.Event, content: table|any) }
 function Event:get_cb(ty)
-  return Cb.cb[ty or self.id]
+  return Callback.cb[ty or self.id]
 end
 
 --- Triggers a new callback to execute whenever an event of the requested type is executed.
@@ -55,21 +56,21 @@ end
 --- @param filt? fun(event: down.Event): boolean # A filtering function to test if a certain event meets our expectations.
 function Event.callback(self, cb, filt)
   local ty = (self and self.id) or self
-  Cb.cb[ty] = Cb.cb[ty] or {}
-  table.insert(Cb.cb[ty], { cb, filt })
+  Callback.cb[ty] = Callback.cb[ty] or {}
+  table.insert(Callback.cb[ty], { cb, filt })
 end
 
 --- @param cb? fun(event: down.Event, content: table|any)
 function Event.set_callback(self, cb)
-  Cb.cb[self.id] = Cb.cb[self.id] or {}
-  table.insert(Cb.cb[self.id], cb)
+  Callback.cb[self.id] = Callback.cb[self.id] or {}
+  table.insert(Callback.cb[self.id], cb)
 end
 
 --- Used internally by down to call all C with an event.
 --- @param self down.Event
 function Event.handle(self)
   log.trace("Event.handle: Handling ", self.id)
-  local cbentry = Cb.cb[self.id]
+  local cbentry = Callback.cb[self.id]
   if cbentry then
     for _, cb in ipairs(cbentry) do
       if not cb[2] or cb[2](self) then
@@ -79,7 +80,9 @@ function Event.handle(self)
   end
 end
 
-function Event.load_cb(m)
+--- Load callback
+--- @param m down.Mod.Mod
+function Event.load_callback(m)
   for hk, ht in pairs(m.handle) do
     for ck, ct in pairs(ht) do
       if type(ct) == "function" then
@@ -89,8 +92,11 @@ function Event.load_cb(m)
   end
 end
 
----@type fun(module: down.Mod.Mod, name: string, body?: any): down.Event
----@return down.Event
+--- Define a new event
+---@param module down.Mod.Mod The module
+---@param name string The name of the event
+---@param body any? The body payload
+---@return down.Event event The result event
 Event.define = function(module, name, body)
   local mn = ""
   if type(module) == "table" then
@@ -116,8 +122,9 @@ Event.define = function(module, name, body)
   }
 end
 
+--- Split id
 --- @param id string The full path of a init event
---- @return string[]?
+--- @return string[]? splitid id
 function Event.split_id(id)
   local sa, sb = id:find("%.events%.")
   local sp_id = { id:sub(0, sa - 1), id:sub(sb + 1) }
@@ -202,6 +209,7 @@ function Event.broadcast_to(self, mods)
   end
 end
 
+--- Send an event
 --- @param recv down.Mod.Mod The name of a loaded init that will be the recipient of the event.
 --- @return nil
 --- @param self down.Event

lua/down/event/init.lua

@@ -149,8 +149,8 @@ Mod.new = function(nm, im)
       if not Mod.load_mod(fp) then
         log.error(
           "Unable to load import '"
-          .. fp
-          .. "'! An error  (see traceback below):"
+            .. fp
+            .. "'! An error  (see traceback below):"
         )
         assert(false)
       end
@@ -167,8 +167,8 @@ Mod.delete = function(mod)
 end
 
 --- @param m down.Mod.Mod The actual mod to load.
---- @return down.Mod|nil # Whether the mod successfully loaded.
-Mod.load_mod_from_table = function(m, cfg)
+--- @return down.Mod.Mod|nil # Whether the mod successfully loaded.
+Mod.from_table = function(m, cfg)
   if Mod.mods[m.id] ~= nil then
     return Mod.mods[m.id]
   end
@@ -205,22 +205,22 @@ Mod.load_mod_from_table = function(m, cfg)
 end
 
 --- @param n string
---- @return down.config.Mod?
+--- @return down.Mod.Mod
 function Mod.check_mod(n)
   local modl = require("down.mod." .. n)
   if not modl then
     log.error("Mod.load_mod: could not load mod " .. n)
     return nil
   elseif modl == true then
-    log.error("did not return valid mod: " .. n)
+    log.error("Mod.load_mod: could not load mod " .. n)
     return nil
   end
   return modl
 end
 
 --- @param modn string A path to a mod on disk. A path in down is '.', not '/'.
 --- @param cfg table? A config that reflects the structure of `down.config.user.setup["mod.id"].config`.
---- @return down.Mod|nil # Whether the mod was successfully loaded.
+--- @return down.Mod.Mod|nil # Whether the mod was successfully loaded.
 function Mod.load_mod(modn, cfg)
   if Mod.mods[modn] then
     if cfg ~= nil then
@@ -235,30 +235,7 @@ function Mod.load_mod(modn, cfg)
   if cfg and not vim.tbl_isempty(cfg) then
     modl.config = util.extend(modl.config, cfg)
   end
-  return Mod.load_mod_from_table(modl)
-end
-
---- Has the same principle of operation as load_mod_from_table(), except it then sets up the parent mod's "dep" table, allowing the parent to access the child as if it were a dependency.
---- @param md down.Mod A valid table as returned by mod.new()
---- @param parent_mod string|down.Mod If a string, then the parent is searched for in the loaded mod. If a table, then the mod is treated as a valid mod as returned by mod.new()
-function Mod.load_mod_as_dependency_from_table(md, parent_mod)
-  if Mod.load_mod_from_table(md) then
-    if type(parent_mod) == "string" then
-      Mod.mods[parent_mod].dep[md.id] = md
-    elseif type(parent_mod) == "table" then
-      parent_mod.dep[md.id] = md
-    end
-  end
-end
-
---- Normally loads a mod, but then sets up the parent mod's "dep" table, allowing the parent mod to access the child as if it were a dependency.
---- @param modn string A path to a mod on disk. A path  in down is '.', not '/'
---- @param parent_mod string The name of the parent mod. This is the mod which the dependency will be attached to.
---- @param cfg? table A config that reflects the structure of down.config.user.setup["mod.id"].config
-function Mod.load_mod_as_dependency(modn, parent_mod, cfg)
-  if Mod.load_mod(modn, cfg) and Mod.is_loaded(parent_mod) then
-    Mod.mods[parent_mod].dep[modn] = Mod.mod_config(modn)
-  end
+  return Mod.from_table(modl)
 end
 
 --- Returns the mod.config table if the mod is loaded
@@ -268,8 +245,8 @@ function Mod.mod_config(modn)
   if not Mod.is_loaded(modn) then
     log.trace(
       "Attempt to get mod config with name"
-      .. modn
-      .. "failed - mod is not loaded."
+        .. modn
+        .. "failed - mod is not loaded."
     )
     return
   end
@@ -326,14 +303,16 @@ function Mod.load_kind(mk, kt)
   end
 end
 
----@param m down.Mod
+--- Load the opts for the mod
+---@param m down.Mod.Mod
 function Mod.load_opts(m)
   Mod.load_kind(m.opts, function(k, v)
     vim.bo[k] = v
   end)
 end
 
----@param m down.Mod
+--- Load the maps for the mod
+---@param m down.Mod.Mod
 function Mod.load_maps(m)
   Mod.load_kind(m.maps, function(_, v)
     local opts = {
@@ -352,11 +331,12 @@ function Mod.load_maps(m)
   end)
 end
 
----@param m down.Mod
+--- Perform initialization for the mod
+---@param m down.Mod.Mod
 function Mod.mod_load(m)
   Mod.load_maps(m)
   Mod.load_opts(m)
-  Event.load_cb(m)
+  Event.load_callback(m)
   if m.load then
     m.load()
   end
@@ -372,7 +352,7 @@ Mod.get = function(m)
   end
 end
 --- @param ms? table<any, string> list of modules to load
---- @return table<integer, down.Mod>
+--- @return down.Mod.Mod[]
 Mod.modules = function(ms)
   local modmap = {}
   for mname, module in pairs(ms or Mod.default.mods) do
@@ -381,7 +361,7 @@ Mod.modules = function(ms)
   return modmap
 end
 
----@param m down.Mod
+---@param m down.Mod.Mod
 Mod.test = function(m)
   log.info("Mod.test: Performing tests for ", m.id, ": ")
   if m.tests then
@@ -401,8 +381,10 @@ Mod.unloaded = modutil.ids
 --- @param m down.Mod.Id
 --- @return nil
 Mod.unload = function(m)
-  if Mod.mods[m] ~= nil then
+  local old = vim.deepcopy(Mod.mods[m])
+  if old ~= nil then
     Mod.mods[m] = nil
+    return old
   else
     if Mod.check_id(m) then
       log.warn("Mod.unload: Attempt to unload unloaded mod ", m)
@@ -421,24 +403,29 @@ Mod.reload = function(m)
 end
 
 --- Syncs the unloaded modules with the loaded modules
-Mod.sync_unloaded = function()
+Mod.sync = function()
   for _, i in ipairs(Mod.util.ids) do
     if not vim.list_contains(vim.tbl_keys(Mod.mods), i) then
       Mod.unloaded[i] = Mod.get(i)
     end
   end
 end
 
+Mod.sync_unloaded = Mod.sync
+
 ---@param cmds down.Command[]
+---@param self down.Mod.Mod
+---@param e down.Event
+---@param cmd string
 ---@return boolean
 Mod.handle_cmd = function(self, e, cmd, cmds, ...)
   log.trace("Mod.handle_cmd: Handling cmd ", cmd, " for mod ", self.id)
   if not cmds or type(cmds) ~= "table" or not cmds[cmd] then
     return false
   end
-  if cmds.enabled ~= nil and cmds.enabled == false then
-    return false
-  end
+  -- if cmds.enabled ~= nil and cmds.enabled == false then
+  --   return false
+  -- end
   local cc = cmds[cmd]
   if cc.enabled ~= nil and cc.enabled == false then
     return false
@@ -461,16 +448,17 @@ Mod.handle_cmd = function(self, e, cmd, cmds, ...)
   return false
 end
 
+--- Handles an event for a mod.
 --- @param e down.Event
---- @param self down.Mod
+--- @param self down.Mod.Mod
 --- @param ... any
 --- @return boolean
 Mod.handle_event = function(self, e, ...)
   log.trace("Mod.handle_event: Handling event ", e.id, " for mod ", self.id)
   if
-      self.handle
-      and self.handle[e.split[1]]
-      and self.handle[e.split[1]][e.split[2]]
+    self.handle
+    and self.handle[e.split[1]]
+    and self.handle[e.split[1]][e.split[2]]
   then
     self.handle[e.split[1]][e.split[2]](e)
     return true
@@ -507,14 +495,14 @@ function Mod.broadcast(e)
 end
 
 --- Returns an event template defined in `mod.events`.
---- @param m down.Mod.Mod A reference to the mod invoking the function
+--- @param self down.Mod.Mod A reference to the mod invoking the function
 --- @param id string A full path to a valid event type (e.g. `mod.events.some_event`)
 --- @return down.Event?
 function Mod.get_event(self, id)
   local split = Event.split_id(id)
   if not split then
     log.warn(
-      "Unable to get event template for event" .. tid .. "and mod" .. self.id
+      "Unable to get event template for event" .. id .. "and mod" .. self.id
     )
     return
   end