fix!: Deprecation warning calling debugprint() directly - closes #99

Author: andrewferrier

README.md

@@ -176,12 +176,14 @@ they are used to convert sections to ROT-13, which most folks don't use.
 
 > [!WARNING]
 > *Note*: as of version 2.0.0, the old mechanism of configuring keymaps/commands
-> which specifically allowed for mapping directly to
+> which specifically allowed for creating your own keymaps using
+> `vim.keymap.set()` directly to
 > `require('debugprint').debugprint(...)` is no longer officially supported or
 > documented. This is primarily because of [confusion](https://github.com/andrewferrier/debugprint.nvim/issues/44#issuecomment-1896405231) which arose over how to do
-> this mapping. Existing mappings performed this way are likely to continue to
-> work for some time. You should, however, migrate over to the new method outlined
-> above. If this doesn't give you the flexibility to map how you wish for some
+> this mapping. Existing mappings performed this way may continue to work but
+> will produce a deprecation warning.
+> You should migrate to the new configuration-based method outlined
+> [above](https://github.com/andrewferrier/debugprint.nvim?tab=readme-ov-file#keymappings-and-commands). If this doesn't give you the flexibility to map how you wish for some
 > reason, please open an
 > [issue](https://github.com/andrewferrier/debugprint.nvim/issues/new).
 

lua/debugprint/options.lua

@@ -207,6 +207,13 @@ M.get_and_validate_function_opts = function(opts)
     assert(not (func_opts.motion and func_opts.insert))
     assert(not (func_opts.motion and func_opts.variable))
 
+    if not func_opts._skip_warning then
+        vim.notify_once(
+            "debugprint.nvim: mapping directly to the debugprint() function is deprecated and no longer supported. You are *STRONGLY RECOMMENDED* to use the inbuilt mapping approach: https://github.com/andrewferrier/debugprint.nvim?tab=readme-ov-file#mapping-deprecation",
+            vim.log.levels.WARN
+        )
+    end
+
     return func_opts
 end
 

lua/debugprint/setup.lua

@@ -27,28 +27,29 @@ end
 M.map_keys_and_commands = function(global_opts)
     map_key("n", global_opts.keymaps.normal.plain_below, {
         callback = function()
-            debugprint.debugprint({})
+            debugprint.debugprint({ _skip_warning = true })
         end,
         desc = "Plain debug below current line",
     })
 
     map_key("n", global_opts.keymaps.normal.plain_above, {
         callback = function()
-            debugprint.debugprint({ above = true })
+            debugprint.debugprint({ _skip_warning = true, above = true })
         end,
         desc = "Plain debug above current line",
     })
 
     map_key("n", global_opts.keymaps.normal.variable_below, {
         callback = function()
-            debugprint.debugprint({ variable = true })
+            debugprint.debugprint({ _skip_warning = true, variable = true })
         end,
         desc = "Variable debug below current line",
     })
 
     map_key("n", global_opts.keymaps.normal.variable_above, {
         callback = function()
             debugprint.debugprint({
+                _skip_warning = true,
                 above = true,
                 variable = true,
             })
@@ -59,6 +60,7 @@ M.map_keys_and_commands = function(global_opts)
     map_key("n", global_opts.keymaps.normal.variable_below_alwaysprompt, {
         callback = function()
             debugprint.debugprint({
+                _skip_warning = true,
                 variable = true,
                 ignore_treesitter = true,
             })
@@ -69,6 +71,7 @@ M.map_keys_and_commands = function(global_opts)
     map_key("n", global_opts.keymaps.normal.variable_above_alwaysprompt, {
         callback = function()
             debugprint.debugprint({
+                _skip_warning = true,
                 above = true,
                 variable = true,
                 ignore_treesitter = true,
@@ -79,7 +82,10 @@ M.map_keys_and_commands = function(global_opts)
 
     map_key("n", global_opts.keymaps.normal.textobj_below, {
         callback = function()
-            return debugprint.debugprint({ motion = true })
+            return debugprint.debugprint({
+                _skip_warning = true,
+                motion = true,
+            })
         end,
         expr = true,
         desc = "Text-obj-selected variable debug below current line",
@@ -88,6 +94,7 @@ M.map_keys_and_commands = function(global_opts)
     map_key("n", global_opts.keymaps.normal.textobj_above, {
         callback = function()
             return debugprint.debugprint({
+                _skip_warning = true,
                 motion = true,
                 above = true,
             })
@@ -98,14 +105,15 @@ M.map_keys_and_commands = function(global_opts)
 
     map_key("i", global_opts.keymaps.insert.plain, {
         callback = function()
-            debugprint.debugprint({ insert = true })
+            debugprint.debugprint({ _skip_warning = true, insert = true })
         end,
         desc = "Plain debug in-place",
     })
 
     map_key("i", global_opts.keymaps.insert.variable, {
         callback = function()
             debugprint.debugprint({
+                _skip_warning = true,
                 insert = true,
                 variable = true,
                 ignore_treesitter = true,
@@ -116,14 +124,15 @@ M.map_keys_and_commands = function(global_opts)
 
     map_key("x", global_opts.keymaps.visual.variable_below, {
         callback = function()
-            debugprint.debugprint({ variable = true })
+            debugprint.debugprint({ _skip_warning = true, variable = true })
         end,
         desc = "Variable debug below current line",
     })
 
     map_key("x", global_opts.keymaps.visual.variable_above, {
         callback = function()
             debugprint.debugprint({
+                _skip_warning = true,
                 above = true,
                 variable = true,
             })

tests/debugprint.lua

@@ -2169,6 +2169,38 @@ describe("handle deprecated options, create_keymaps=true", function()
     end)
 end)
 
+describe("handle deprecated options, direct mapping", function()
+    before_each(function()
+        debugprint.setup()
+
+        vim.keymap.set("n", "g?t", function()
+            debugprint.debugprint({})
+        end)
+    end)
+
+    after_each(teardown)
+
+    it("basic", function()
+        local filename = init_file({
+            "foo",
+            "bar",
+        }, "lua", 1, 0)
+
+        feedkeys("g?t")
+
+        check_lines({
+            "foo",
+            "print('DEBUGPRINT[1]: " .. filename .. ":1 (after foo)')",
+            "bar",
+        })
+
+        print(notify_message)
+
+        assert.True(notify_message:find("mapping directly") > 0)
+        assert.True(notify_message:find("is deprecated") > 0)
+    end)
+end)
+
 describe("unmodifiable buffer", function()
     before_each(function()
         debugprint.setup()