debugprint.nvim

Overview

debugprint is a plugin for NeoVim that simplifies debugging for those who prefer a low-tech approach. While using a real debugger like nvim-dap is the gold standard for debugging a script or program, some prefer the use of the 'print' statement to trace the output during execution. debugprint allows quick insertion of appropriate 'print' statements based on the language being edited.

debugprint also inserts into the 'print' statements the file name and line numbers where debug lines are inserted, as well as a snippet of the previous or following line and a unique counter value from the current NeoVim session to help identify lines in debug output. Optionally it can also output variable values.

debugprint supports the following filetypes/programming languages out-of-the-box:

• bash
• c
• cpp (C++)
• cs (C#)
• dart
• dockerfile
• go
• java
• javascript
• lua
• make
• php
• python
• ruby
• rust
• sh (Sh/Bash)
• typescript
• vim
• zsh

It can also be extended to support more.

debugprint is inspired by vim-debugstring, which I've used for several years, but is updated and refreshed for the NeoVim generation. It provides various improvements:

• Its configuration system is more 'NeoVim-like' and it is easier to add custom languages in your configuration.

• It dot-repeats with NeoVim.

• It can pick up a variable name from under the cursor.

• It provides keymappings for visual mode, so you can select a variable visually and print it out.

• It provides keymappings for operator-pending mode, so you can select a variable using a motion.

• It indents the lines it inserts more accurately.

• The output when printing a 'plain' debug line, or a variable, is more consistent.

• It provides a command to delete all debugging lines added to the current buffer.

• Able to optionally move to the inserted line (or not).

Demo

Installation

Requires NeoVim 0.8+.

Optional dependency for NeoVim 0.8 only: nvim-treesitter. If this is not installed, debugprint will not find variable names under the cursor and will always prompt for a variable name. For NeoVim 0.9+, this dependency is never needed.

Example for lazy.nvim:

return {
    url = "andrewferrier/debugprint.nvim",
    opts = { ... },
    -- Dependency only needed for NeoVim 0.8
    dependencies = {
        "nvim-treesitter/nvim-treesitter"
    }
    -- Remove the following line to use development versions,
    -- not just the formal releases
    version = "*"
}

Example for packer.nvim:

packer.startup(function(use)

    ...

    use({
        "andrewferrier/debugprint.nvim",
        config = function()
            opts = { ... }
            require("debugprint").setup(opts)
        end,
    })

    ...

end)

The sections below detail the allowed options that can appear in the opts object.

Please subscribe to this GitHub issue to be notified of any breaking changes to debugprint.

Keymappings and Commands

By default, the plugin will create some keymappings and commands, which are the standard way to use it. There are also some function invocations which are not mapped to any keymappings or commands by default, but could be. This is all shown in the following table.

The keymappings are chosen specifically because by default in NeoVim they are used to convert sections to ROT-13, which most folks don't use. You can disable the defaults above from being created by setting create_keymaps and/or create_commands, and map them yourself to something else if you prefer:

opts = {
    create_keymaps = false,
    create_commands = false
    ...
}

require("debugprint").setup(opts)

vim.keymap.set("n", "<Leader>d", function()
    -- Note: setting `expr=true` and returning the value are essential
    return require('debugprint').debugprint()
end, {
    expr = true,
})
vim.keymap.set("n", "<Leader>D", function()
    -- Note: setting `expr=true` and returning the value are essential
    return require('debugprint').debugprint({ above = true })
end, {
    expr = true,
})
vim.keymap.set("n", "<Leader>dq", function()
    -- Note: setting `expr=true` and returning the value are essential
    return require('debugprint').debugprint({ variable = true })
end, {
    expr = true,
})
vim.keymap.set("n", "<Leader>Dq", function()
    -- Note: setting `expr=true` and returning the value are essential
    return require('debugprint').debugprint({ above = true, variable = true })
end, {
    expr = true,
})
vim.keymap.set("n", "<Leader>do", function()
    -- Note: setting `expr=true` and returning the value are essential
    -- It's also important to use motion = true for operator-pending motions
    return require('debugprint').debugprint({ motion = true })
end, {
    expr = true,
})

vim.api.nvim_create_user_command("DeleteDebugs", function(opts)
    -- Note: you must set `range=true` and pass through opts for ranges to work
    M.deleteprints(opts)
end, {
    range = true})
end)
...

or, to have a keymapping instead for deleting debug lines (this will only affect the entire buffer, visual and operator-pending modes will not work):

vim.keymap.set("n", "g?d", function()
    M.deleteprints()
end)

Other Options

debugprint supports the following options in its global opts object:

Add Custom Filetypes

Note: Since debugprint.nvim is still relatively new, if you work out a configuration for a filetype not supported out-of-the-box, it would be really appreciated if you can open an issue to have it supported out-of-the-box in debugprint so others can benefit from it. Similarly, if you spot any issues with, or improvements to, the language configurations out-of-the-box, please open an issue also.

If debugprint doesn't support your filetype, you can add it as a custom filetype in one of two ways:

• In the opts.filetypes object in setup().

• Using the require('debugprint').add_custom_filetypes() method (designed for use from ftplugin/ directories, etc.

In either case, the format is the same. For example, if adding via setup():

local my_fileformat = {
    left = 'print "',
    right = '"',
    mid_var = "${",
    right_var = '}"',
}

require('debugprint').setup({ filetypes = { my_fileformat, another_of_my_fileformats, ... }})

or add_custom_filetypes():

require('debugprint').add_custom_filetypes({ my_fileformat, ... })

Your new file format will be merged in with those that already exist. If you pass in one that already exists, your configuration will override the built-in configuration.

The keys in the configuration are used like this:

If it helps to understand these, you can look at the built-in configurations in filetypes.lua.

Known Limitations

• debugprint only supports variable names or simple expressions when using g?v/g?V - in particular, it does not make any attempt to escape expressions, and may generate invalid syntax if you try to be too clever. There's an issue to look at ways of improving this.

Alternative Feature Comparison

(This table is quite wide, you may need to scroll horizontally)