feat: config and debug

lua/your-plugin-name/config.lua

@@ -1,3 +1,5 @@
+local D = require("your-plugin-name.util.debug")
+
 local YourPluginName = {}
 
 --- Your plugin configuration with its default values.
@@ -9,15 +11,42 @@ YourPluginName.options = {
     debug = false,
 }
 
+---@private
+local defaults = vim.deepcopy(YourPluginName.options)
+
+--- Defaults YourPluginName options by merging user provided options with the default plugin values.
+---
+---@param options table Module config table. See |YourPluginName.options|.
+---
+---@private
+function YourPluginName.defaults(options)
+    local tde = function(t1, t2)
+        return vim.deepcopy(vim.tbl_deep_extend("keep", t1 or {}, t2 or {}))
+    end
+
+    YourPluginName.options = tde(options, defaults)
+
+    -- let your user know that they provided a wrong value, this is reported when your plugin is executed.
+    assert(
+        type(YourPluginName.options.debug) == "boolean",
+        "`debug` must be a boolean (`true` or `false`)."
+    )
+
+    return YourPluginName.options
+end
+
 --- Define your your-plugin-name setup.
 ---
 ---@param options table Module config table. See |YourPluginName.options|.
 ---
 ---@usage `require("your-plugin-name").setup()` (add `{}` with your |YourPluginName.options| table)
 function YourPluginName.setup(options)
-    options = options or {}
+    YourPluginName.options = YourPluginName.defaults(options or {})
+
+    -- Useful for later checks that requires nvim 0.9 features at runtime.
+    YourPluginName.options.hasNvim9 = vim.fn.has("nvim-0.9") == 1
 
-    YourPluginName.options = vim.tbl_deep_extend("keep", options, YourPluginName.options)
+    D.warnDeprecation(YourPluginName.options)
 
     return YourPluginName.options
 end

lua/your-plugin-name/util/debug.lua

@@ -11,50 +11,45 @@ function D.log(scope, str, ...)
         return
     end
 
-    local info = debug.getinfo(2, "Sl")
-    local line = ""
-
-    if info then
-        line = "L" .. info.currentline
-    end
-
     print(
         string.format(
-            "[your-plugin-name:%s %s in %s] > %s",
-            os.date("%H:%M:%S"),
-            line,
+            "[your-plugin-name@%s in '%s'] > %s",
+            os.date("%X"),
             scope,
             string.format(str, ...)
         )
     )
 end
 
----prints the table if debug is true.
+---analyzes the user provided `setup` parameters and sends a message if they use a deprecated option, then gives the new option to use.
 ---
----@param table table: the table to print.
----@param indent number?: the default indent value, starts at 0.
+---@param options table: the options provided by the user.
 ---@private
-function D.tprint(table, indent)
-    if _G.YourPluginName.config ~= nil and not _G.YourPluginName.config.debug then
-        return
-    end
-
-    if not indent then
-        indent = 0
+function D.warnDeprecation(options)
+    local usesDeprecatedOption = false
+
+    local notice = "is now deprecated, use `%s` instead."
+    local rootDeprecated = {
+        foo = "bar",
+        bar = "baz",
+    }
+
+    for name, warning in pairs(rootDeprecated) do
+        if options[name] ~= nil then
+            usesDeprecatedOption = true
+            print(
+                string.format(
+                    "[your-plugin-name.nvim] `%s` %s",
+                    name,
+                    string.format(notice, warning)
+                )
+            )
+        end
     end
 
-    for k, v in pairs(table) do
-        local formatting = string.rep("  ", indent) .. k .. ": "
-        if type(v) == "table" then
-            print(formatting)
-            D.tprint(v, indent + 1)
-        elseif type(v) == "boolean" then
-            print(formatting .. tostring(v))
-        elseif type(v) == "function" then
-            print(formatting .. "FUNCTION")
-        else
-            print(formatting .. v)
-        end
+    if usesDeprecatedOption then
+        print("[your-plugin-name.nvim]     sorry to bother you with the breaking changes :(")
+        print("[your-plugin-name.nvim]     use `:h YourPluginName.options` to read more.")
     end
 end