andrewferrier/debugprint.nvim

github github
debugging
stars 374
issues 15
subscribers 4
forks 23
CREATED

2022-08-08

UPDATED

2 days ago


▗▄▄▄ ▗▄▄▄▖▗▄▄▖ ▗▖ ▗▖ ▗▄▄▖▗▄▄▖ ▗▄▄▖ ▗▄▄▄▖▗▖  ▗▖▗▄▄▄▖
▐▌  █▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌   ▐▌ ▐▌▐▌ ▐▌  █  ▐▛▚▖▐▌  █
▐▌  █▐▛▀▀▘▐▛▀▚▖▐▌ ▐▌▐▌▝▜▌▐▛▀▘ ▐▛▀▚▖  █  ▐▌ ▝▜▌  █
▐▙▄▄▀▐▙▄▄▖▐▙▄▞▘▝▚▄▞▘▝▚▄▞▘▐▌   ▐▌ ▐▌▗▄█▄▖▐▌  ▐▌  █

Test status

Overview

debugprint is a NeoVim plugin that simplifies debugging for those who prefer a low-tech approach. Instead of using a sophisticated debugger like nvim-dap, some people prefer using a 'print'-like statement to trace the output during execution. With debugprint, you can insert these statements, including the values of variables, relevant to the language you're editing.

Features

debugprint is inspired by vim-debugstring; updated for the NeoVim generation. It:

  • Supports 38 filetypes/programming languages out-of-the-box, including Python, JavaScript/TypeScript, Java, C/C++ and more. It can also be extended to support other languages or customize existing ones.

  • Includes reference information in each 'print line' such as file names, line 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 or on a 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 will prompt with a sensible default. It understands Treesitter embedded languages (e.g. JavaScript-in-HTML).

  • Provides keymappings for normal, insert, visual, and operator-pending modes. Supports dot-repeat.

  • Provides commands to delete debugging lines added to the current buffer or comment/uncomment those lines.

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

  • Is MIT Licensed.

Demo

Installation

Requires NeoVim 0.9+.

Example for lazy.nvim:

return {
    "andrewferrier/debugprint.nvim",

    -- opts = { … },

    dependencies = {
        "echasnovski/mini.nvim" -- Needed for :ToggleCommentDebugPrints (not needed for NeoVim 0.10+)
    },

    version = "*", -- Remove if you DON'T want to use the stable version
}

(Examples for other package managers here.)

The sections below detail the allowed options that can appear in the opts object. There is also a showcase of example and advanced debugprint configurations here which can be dropped into your configuration files to further enhance your use of debugprint.

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 for use 'out of the box'. 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.

Mode Default Key / Cmd Purpose Above/Below Line
Normal g?p Plain debug Below
Normal g?P Plain debug Above
Normal g?v Variable debug Below
Normal g?V Variable debug Above
Normal None Variable debug (always prompt for variable) Below
Normal None Variable debug (always prompt for variable) Above
Normal None Delete debug lines in buffer -
Normal None Comment/uncomment debug lines in buffer -
Insert Ctrl-G p Plain debug In-place
Insert Ctrl-G v Variable debug (always prompt for variable) In-place
Visual g?v Variable debug Below
Visual g?V Variable debug Above
Op-pending g?o Variable debug Below
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 configuration of debugprint. For example, if configuring via lazy.nvim, it might look like this:

return {
    "andrewferrier/debugprint.nvim",
    opts = {
        keymaps = {
            normal = {
                plain_below = "g?p",
                plain_above = "g?P",
                variable_below = "g?v",
                variable_above = "g?V",
                variable_below_alwaysprompt = "",
                variable_above_alwaysprompt = "",
                textobj_below = "g?o",
                textobj_above = "g?O",
                toggle_comment_debug_prints = "",
                delete_debug_prints = "",
            },
            insert = {
                plain = "<C-G>p",
                variable = "<C-G>v",
            },
            visual = {
                variable_below = "g?v",
                variable_above = "g?V",
            },
        },
        commands = {
            toggle_comment_debug_prints = "ToggleCommentDebugPrints",
            delete_debug_prints = "DeleteDebugPrints",
            reset_debug_prints_counter = "ResetDebugPrintsCounter",
        },
        -- … Other options
    },
}

You only need to include the keys / commands which you wish to override, others will default as shown above. Setting any key or command to "" or false will skip it.

The default keymappings are chosen specifically because ordinarily in NeoVim they are used to convert sections to ROT-13, which most folks don't use.

Mapping Deprecation

[!WARNING] Note: as of version 2.0.0, the old mechanism of configuring keymaps/commands which specifically allowed for mapping directly to require('debugprint').debugprint(...) is no longer officially supported or documented. This is primarily because of confusion 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 reason, please open an issue.

Other Options

debugprint supports the following options in its global opts object:

Option Default Purpose
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. (If you want to customize this counter, or make it non-persistent, see instructions in the showcase 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) Custom filetypes - see showcase
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

Known Limitations

  • debugprint does not handle deleting reformatted debug lines where a formatter has split them across multiple lines. If you want to be able to easily delete your debug lines using DeleteDebugPrints or similar, don't format your file between inserting them and running this command. See this issue for discussion on this.

Feature Comparison with Similar Plugins

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

Feature debugprint.nvim timber.nvim nvim-chainsaw printer.nvim refactoring.nvim vim-printer logsitter
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: :+1: :x: :x: :x: :x:
Use treesitter to intelligently insert log lines :x: :+1: :+1: :x: :x: :x: :x:
Enter variables/expressions using prompts :+1: :x: :x: :x: :x: :x: :x:
Fallback to variables using current word/heuristic :+1: :x: :+1: :x: :x: :+1: :x:
Print variables using motions/operator :+1: :+1: :x: :+1: :x: :x: :x:
Add plain or variable debug lines in insert mode :+1: :x: :x: :x:: :x: :x: :x:
Add variable debug lines in visual mode :+1: :+1: :+1: :+1: :+1: :+1: :x:
Print assertions :x: :+1: (via user config) :+1: :x: :x: :x: :x:
Print stack traces :x: :+1: (via user config) :+1: :x: :x: :x: :x:
Add time-tracking logic :x: :+1: (via user config) :+1: :x: :x: :x: :x:
Add debugging breakpoints :x: :+1: (via user config) :+1: :x: :x: :x: :x:
Print debug lines above/below current line :+1: :+1: :x: (via global config) :x: :+1: :x:
Supports dot-repeat :+1: :+1: :+1: :x: :x: :x: :x:
Can control whether to move to inserted lines :+1: :x: :x: :x: :x: :x: :x:
Clean up all debug lines :+1: :x: :+1: :x: :x: :x: :x:
Comment/uncomment all debug lines :+1: :x: :x: :x: :x: :x: :x:
Can put debugprint text into default register :x: :x: :x: :+1: :x: :x: :x:
Extra visual emphasis of log statements :x: Flashes to highlight lines when inserted status line counter, signcolumn, line-highlight, scrollbar :x: :x: :x: :x:
Can insert logs in batches :x: :+1: :x: :x: :x: :x: :x:
Log watcher mechanism :x: :+1: :x: :x: :x: :x: :x:
Completely customizable log lines :x: :+1: :+1: :+1: :x: :x: :x:
Built-in support for: - - - - - - -
Apex (Salesforce) :+1: :x: :x: :x: :x: :x: :x:
AppleScript :+1: :x: :+1: :x: :x: :x: :x:
bash/sh :+1: :x: :+1: :+1: :x: :+1: :x:
C :+1: :x: :x: :x: :x: :x: :x:
C# :+1: :x: :x: :x: :x: :x: :x:
C++ :+1: :x: :x: :+1: :+1: :+1: :x:
CMake :+1: :x: :x: :x: :x: :x: :x:
Cobol :+1: :x: :x: :x: :x: :x: :x:
dart :+1: :x: :x: :x: :x: :x: :x:
Docker :+1: :x: :x: :x: :x: :x: :x:
DOS/Windows Batch :+1: :x: :x: :x: :x: :x: :x:
Elixir :+1: :+1: :x: :x: :x: :x: :x:
fish :+1: :x: :x: :x: :x: :x: :x:
Fortran :+1: :x: :x: :x: :x: :+1: :x:
Golang :+1: :+1: :+1: :+1: :+1: :+1: :+1:
Haskell :+1: :x: :x: :x: :x: :x: :x:
Java :+1: :x: :x: :+1: :+1: :+1: :x:
Javascript/Typescript :+1: :+1: :+1: :+1: :+1: :+1: :+1:
Kotlin :+1: :x: :x: :x: :x: :x: :x:
lean :+1: :x: :x: :x: :x: :x: :x:
Lisp :+1: :x: :x: :x: :x: :x: :x:
lua :+1: :+1: :+1: :+1: :+1: :+1: :+1:
GNU Make :+1: :x: :x: :x: :x: :x: :x:
Perl :+1: :x: :x: :x: :x: :x: :x:
PHP :+1: :x: :x: :x: :+1: :x: :x:
Powershell/ps1 :+1: :x: :x: :x: :x: :x: :x:
Python :+1: :x: :+1: :+1: :+1: :+1: :x:
R :+1: :x: :x: :x: :x: :x: :x:
React :+1: :x: :+1: :x: :x: :x: :x:
Ruby :+1: :+1: :+1: :x: :+1: :x: :x:
Rust :+1: :+1: :+1: :+1: :x: :+1: :x:
Swift :+1: :x: :x: :x: :x: :x: :x:
Svelte :+1: :x: :+1: :x: :x: :x: :x:
tcl :+1: :x: :x: :x: :x: :x: :x:
VimL (vimscript) :+1: :x: :x: :+1: :x: :+1: :x:
Vue :+1: :x: :+1: :x: :x: :x: :x:
Zig :+1: :x: :x: :x: :x: :x: :x:
zsh :+1: :x: :+1: :+1: :x: :+1: :x:
Add custom filetypes :+1: :+1: :+1: :+1: :x: :x: :+1:
Implemented in Lua Lua Lua Lua Lua VimL Lua

There is also a similar table in the nvim-chainsaw documentation.

Other similar plugins (less popular or unmaintained):