feat!: Use persistent counter - closes #143

This change introduces a persistent counter value, so that it persists
between NeoVim invocations and even between multiple NeoVim instances
open at the same time. This is done by storing a small state file in
NeoVim's data directory.

If you don't like this behaviour, you can revert back to the old
behaviour by using a custom `display_counter` option, as shown in the
showcase: https://github.com/andrewferrier/debugprint.nvim/blob/main/SHOWCASE.md#restoring-non-persistent-display_counter-counter

Author: andrewferrier

README.md

@@ -31,9 +31,10 @@ the NeoVim generation. It:
     support other languages or customize existing ones](SHOWCASE.md).
 
 *   Includes reference information in each 'print line' such as file names, line
-    numbers, a counter, and snippets of other lines to make it easier to
-    cross-reference them in output (each of these can be optionally
-    disabled [globally](#other-options) or [on a per-filetype basis](SHOWCASE.md#setting-display_-options-on-per-filetype-basis)).
+    numbers, a counter (which persists between NeoVim sessions), and snippets of
+    other lines to make it easier to cross-reference them in output (each of these
+    can be optionally disabled [globally](#other-options) or [on a per-filetype
+    basis](SHOWCASE.md#setting-display_-options-on-per-filetype-basis)).
 
 *   Can output the value of variables (or in some cases, expressions) - it will
     detect a variable name under the cursor for some languages using Treesitter, or
@@ -114,6 +115,7 @@ following table.
 | Op-pending | `g?O`                       | Variable debug                              | Above            |
 | Command    | `:DeleteDebugPrints`        | Delete debug lines in buffer                | -                |
 | Command    | `:ToggleCommentDebugPrints` | Comment/uncomment debug lines in buffer     | -                |
+| Command    | `:ResetDebugPrintsCounter`  | Reset debug print persistent counter (only for built-in counter implementation) | -         |
 
 The keys and commands outlined above can be specifically overridden using the
 `keymaps` and `commands` objects inside the `opts` object used above during
@@ -149,6 +151,7 @@ return {
         commands = {
             toggle_comment_debug_prints = "ToggleCommentDebugPrints",
             delete_debug_prints = "DeleteDebugPrints",
+            reset_debug_prints_counter = "ResetDebugPrintsCounter",
         },
         -- … Other options
     },
@@ -183,7 +186,7 @@ they are used to convert sections to ROT-13, which most folks don't use.
 | ------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `move_to_debugline` | `false`                      | When adding a debug line, moves the cursor to that line                                                                                                                                                                                                                                        |
 | `display_location`  | `true`                       | Include the filename and linenumber of the line being debugged in the debug message                                                                                                                                                                                                            |
-| `display_counter`   | `true`                       | Include the increasing integer counter in the debug message. (Can also be set to a function to customize, see the [showcase](SHOWCASE.md#use-a-custom-display_counter-counter)) for an example                                                                                                                                       |
+| `display_counter`   | `true`                       | Include the increasing integer counter in the debug message. (Can also be set to a function to customize, see the [showcase](SHOWCASE.md#restoring-non-persistent-display_counter-counter)) for an example                                                                                                                                       |
 | `display_snippet`   | `true`                       | Include a snippet of the line above/below in the debug message (plain debug lines only) for context                                                                                                                                                                                            |
 | `filetypes`         | See ([the code](lua/debugprint/filetypes.lua))  | Custom filetypes - see [showcase](SHOWCASE.md)                                                                                                                                                                                                                                                 |
 | `print_tag`         | `DEBUGPRINT`                 | The string inserted into each print statement, which can be used to uniquely identify statements inserted by `debugprint`. If you set this to `''` (the empty string), no print tag will be included, but this will disable the ability to delete or comment print statements via `debugprint` |
@@ -205,6 +208,7 @@ they are used to convert sections to ROT-13, which most folks don't use.
 | ------------------------------------------------------------------- | ----------------- | ------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------- |
 | Include line numbers in log lines                                   | :+1:              | :+1: (via user config)                                  | :+1: (via user config)                                         | :+1:                                                      | :+1:                                                                 | :x:                                                 | :+1:                                                  |
 | Include other location information in log lines                     | :+1:              | :x:                                                     | :+1: (via user config)                                         | :+1:                                                      | :+1:                                                                 | :x:                                                 | :+1:                                                  |
+| Persistent location counter between NeoVim sessions                 | :+1:              | :x:                                                     | :x:                                                            | :x:                                                       | :x:                                                                  | :x:                                                 | :x:                                                   |
 | Print plain debug lines                                             | :+1:              | :+1: (via user config)                                  | :+1:                                                           | :x:                                                       | :+1:                                                                 | :x:                                                 | :x:                                                   |
 | Print variables using treesitter                                    | :+1:              | :+1:                                                    | :+1:                                                           | :x:                                                       | :+1:                                                                 | :x:                                                 | :x:                                                   |
 | Use treesitter to locate log targets                                | (some languages)  | :+1:                                                    | :x:                                                            | :x:                                                       | :x:                                                                  | :x:                                                 | :x:                                                   |

SHOWCASE.md

@@ -126,9 +126,9 @@ return {
 }
 ```
 
-## Use a custom `display_counter` counter
+## Restoring non-persistent `display_counter` counter
 
-The `display_counter` option can be set to a custom callback function to implement custom counter logic. In this case you are responsible for implementing your own counter. For example, this logic will implement essentially the same as the default counter:
+In older versions, `debugprint` used a `display_counter` which was only local to a particular NeoVim session; it was reset when exiting NeoVim and wasn't common between NeoVim sessions in different terminals. If you don't like the new 'persistent' counter, you can restore this old behaviour by setting a custom `display_counter`. This will recreate the old logic:
 
 ```lua
 local counter = 0
@@ -141,6 +141,8 @@ end
 debugprint.setup({display_counter = counter_func})
 ```
 
+You can also set `display_counter` to any other function you wish.
+
 ## Using package managers other than lazy.nvim
 
 Example for [`packer.nvim`](https://github.com/wbthomason/packer.nvim):

lua/debugprint/counter.lua

@@ -0,0 +1,42 @@
+local M = {}
+
+local default_counter
+
+local DATA_PATH = vim.fs.joinpath(vim.fn.stdpath("data"), "debugprint")
+local COUNTER_FILE = vim.fs.joinpath(DATA_PATH, "counter")
+
+---@return string
+M.default_display_counter = function()
+    if vim.fn.mkdir(DATA_PATH, "p") == 1 then
+        if vim.fn.filereadable(COUNTER_FILE) == 1 then
+            local counter_lines = vim.fn.readfile(COUNTER_FILE)
+
+            if #counter_lines == 1 then
+                default_counter = tonumber(counter_lines[1])
+            end
+        end
+    end
+
+    if default_counter == nil then
+        default_counter = 0
+    end
+
+    default_counter = default_counter + 1
+
+    if vim.fn.filewritable(DATA_PATH) == 2 then
+        vim.fn.writefile({ default_counter }, COUNTER_FILE)
+    end
+
+    return "[" .. tostring(default_counter) .. "]"
+end
+
+---@return nil
+M.reset_debug_prints_counter = function()
+    if vim.fn.filewritable(COUNTER_FILE) == 1 then
+        vim.fs.rm(COUNTER_FILE)
+    end
+
+    default_counter = nil
+end
+
+return M

lua/debugprint/init.lua

@@ -6,13 +6,6 @@ local utils_errors = require("debugprint.utils.errors")
 local utils_operator = require("debugprint.utils.operator")
 
 local global_opts
-local default_counter = 0
-
----@return string
-local default_display_counter = function()
-    default_counter = default_counter + 1
-    return "[" .. tostring(default_counter) .. "]"
-end
 
 ---@param display_counter? boolean|function
 ---@return string
@@ -24,7 +17,8 @@ local get_debugline_tag_and_counter = function(display_counter)
     end
 
     if display_counter == true then
-        tag_and_counter = tag_and_counter .. default_display_counter()
+        tag_and_counter = tag_and_counter
+            .. require("debugprint.counter").default_display_counter()
     elseif type(display_counter) == "function" then
         tag_and_counter = tag_and_counter .. tostring(display_counter())
     end
@@ -400,9 +394,6 @@ M.setup = function(opts)
         require("debugprint.options").get_and_validate_global_opts(opts)
 
     require("debugprint.setup").map_keys_and_commands(global_opts)
-
-    -- Because we want to be idempotent, re-running setup() resets the counter
-    default_counter = 0
 end
 
 ---@param filetypes DebugprintFileTypeConfig[]

lua/debugprint/options.lua

@@ -27,6 +27,7 @@ local GLOBAL_OPTION_DEFAULTS = {
     commands = {
         toggle_comment_debug_prints = "ToggleCommentDebugPrints",
         delete_debug_prints = "DeleteDebugPrints",
+        reset_debug_prints_counter = "ResetDebugPrintsCounter",
     },
     display_counter = true,
     display_location = true,
@@ -65,6 +66,11 @@ local validate_global_opts = function(o)
             o.commands.toggle_comment_debug_prints,
             STRING_FALSE_NIL,
         },
+
+        commands_reset_debug_prints_counter = {
+            o.commands.reset_debug_prints_counter,
+            STRING_FALSE_NIL,
+        },
     })
 
     local normal = o.keymaps.normal

lua/debugprint/setup.lua

@@ -186,6 +186,14 @@ M.map_keys_and_commands = function(global_opts)
             desc = "Comment/uncomment all debugprint statements in the current buffer",
         }
     )
+
+    create_command(
+        global_opts.commands.reset_debug_prints_counter,
+        require("debugprint.counter").reset_debug_prints_counter,
+        {
+            desc = "Reset the debugprint counter to 0",
+        }
+    )
 end
 
 return M

lua/debugprint/types.lua

@@ -54,6 +54,7 @@
 ---@class DebugprintCommandOptions
 ---@field delete_debug_prints? string|false
 ---@field toggle_comment_debug_prints? string|false
+---@field reset_debug_prints_counter? string|false
 
 ---@class DebugprintFunctionOptions
 ---@field above? boolean

tests/debugprint.lua

@@ -77,7 +77,12 @@ vim.notify = function(msg, _)
     notify_message = msg
 end
 
-local teardown = function()
+local DATA_PATH = vim.fs.joinpath(vim.fn.stdpath("data"), "debugprint")
+local COUNTER_FILE = vim.fs.joinpath(DATA_PATH, "counter")
+
+local teardown = function(opts)
+    opts = vim.tbl_extend("keep", opts or {}, { reset_counter = true })
+
     notify_message = nil
     pcall(vim.keymap.del, "n", "g?p")
     pcall(vim.keymap.del, "n", "g?P")
@@ -88,6 +93,10 @@ local teardown = function()
     pcall(vim.api.nvim_del_user_command, "DeleteDebugPrints")
     pcall(vim.api.nvim_del_user_command, "ToggleCommentDebugPrints")
     vim.cmd("set modifiable")
+
+    if opts.reset_counter then
+        require("debugprint.counter").reset_debug_prints_counter()
+    end
 end
 
 ---@param name string
@@ -2595,3 +2604,51 @@ describe("can disable built-in keymaps/commands", function()
         assert.equals(command_exists("DeleteDebugPrints"), false)
     end)
 end)
+
+describe("check that counter persistence works", function()
+    before_each(function()
+        debugprint.setup()
+    end)
+
+    after_each(function()
+        teardown({ reset_counter = false })
+    end)
+
+    it("statement 1", function()
+        assert.equals(vim.fn.filereadable(COUNTER_FILE), 0)
+
+        local filename = init_file({
+            "foo",
+            "bar",
+        }, "lua", 1, 0)
+
+        feedkeys("g?p")
+
+        check_lines({
+            "foo",
+            "print('DEBUGPRINT[1]: " .. filename .. ":1 (after foo)')",
+            "bar",
+        })
+
+        assert.equals(vim.fn.filereadable(COUNTER_FILE), 1)
+    end)
+
+    it("statement 2", function()
+        assert.equals(vim.fn.filereadable(COUNTER_FILE), 1)
+
+        local filename = init_file({
+            "foo",
+            "bar",
+        }, "lua", 1, 0)
+
+        feedkeys("g?P")
+
+        check_lines({
+            "print('DEBUGPRINT[2]: " .. filename .. ":1 (before foo)')",
+            "foo",
+            "bar",
+        })
+
+        assert.equals(vim.fn.filereadable(COUNTER_FILE), 1)
+    end)
+end)