README.md

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

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 34 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, 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

211196425-2b371442-54f9-43d7-9187-a29185d43586.mp4

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	-

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 = nil,
                variable_above_alwaysprompt = nil,
                textobj_below = "g?o",
                textobj_above = "g?O",
                toggle_comment_debug_prints = nil,
                delete_debug_prints = nil,
            },
            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",
        },
        -- … 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 nil 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. (Can also be set to a function to customize, see 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	👍	👍 (via user config)	👍 (via user config)	👍	👍	❌	👍
Include other location information in log lines	👍	❌	👍 (via user config)	👍	👍	❌	👍
Print plain debug lines	👍	👍 (via user config)	👍	❌	👍	❌	❌
Print variables using treesitter	👍	👍	👍	❌	👍	❌	❌
Use treesitter to locate log targets	(some languages)	👍	❌	❌	❌	❌	❌
Use treesitter to intelligently insert log lines	❌	👍	❌	❌	❌	❌	❌
Enter variables/expressions using prompts	👍	❌	❌	❌	❌	❌	❌
Fallback to variables using current word/heuristic	👍	❌	👍	❌	❌	👍	❌
Print variables using motions/operator	👍	👍	❌	👍	❌	❌	❌
Add plain or variable debug lines in insert mode	👍	❌	❌	❌:	❌	❌	❌
Add variable debug lines in visual mode	👍	👍	👍	👍	👍	👍	❌
Print assertions	❌	👍 (via user config)	👍	❌	❌	❌	❌
Print stack traces	❌	👍 (via user config)	👍	❌	❌	❌	❌
Add time-tracking logic	❌	👍 (via user config)	👍	❌	❌	❌	❌
Add debugging breakpoints	❌	👍 (via user config)	👍	❌	❌	❌	❌
Print debug lines above/below current line	👍	👍	❌	(via global config)	❌	👍	❌
Supports dot-repeat	👍	👍	👍	❌	❌	❌	❌
Can control whether to move to inserted lines	👍	❌	❌	❌	❌	❌	❌
Clean up all debug lines	👍	❌	👍	❌	❌	❌	❌
Comment/uncomment all debug lines	👍	❌	❌	❌	❌	❌	❌
Can put debugprint text into default register	❌	❌	❌	👍	❌	❌	❌
Flashes to highlight lines when inserted	❌	👍	❌	❌	❌	❌	❌
Can insert logs in batches	❌	👍	❌	❌	❌	❌	❌
Built-in support for:	-	-	-	-	-	-	-
Apex (Salesforce)	👍	❌	❌	❌	❌	❌	❌
AppleScript	👍	❌	👍	❌	❌	❌	❌
bash/sh	👍	❌	👍	👍	❌	👍	❌
C	👍	❌	❌	❌	❌	❌	❌
C#	👍	❌	❌	❌	❌	❌	❌
C++	👍	❌	❌	👍	👍	👍	❌
CMake	👍	❌	❌	❌	❌	❌	❌
dart	👍	❌	❌	❌	❌	❌	❌
Docker	👍	❌	❌	❌	❌	❌	❌
DOS/Windows Batch	👍	❌	❌	❌	❌	❌	❌
Elixir	👍	👍	❌	❌	❌	❌	❌
fish	👍	❌	❌	❌	❌	❌	❌
Fortran	👍	❌	❌	❌	❌	👍	❌
Golang	👍	👍	👍	👍	👍	👍	👍
Haskell	👍	❌	❌	❌	❌	❌	❌
Java	👍	❌	❌	👍	👍	👍	❌
Javascript/Typescript	👍	👍	👍	👍	👍	👍	👍
Kotlin	👍	❌	❌	❌	❌	❌	❌
lean	👍	❌	❌	❌	❌	❌	❌
Lisp	👍	❌	❌	❌	❌	❌	❌
lua	👍	👍	👍	👍	👍	👍	👍
GNU Make	👍	❌	❌	❌	❌	❌	❌
Perl	👍	❌	❌	❌	❌	❌	❌
PHP	👍	❌	❌	❌	👍	❌	❌
Powershell/ps1	👍	❌	❌	❌	❌	❌	❌
Python	👍	❌	👍	👍	👍	👍	❌
R	👍	❌	❌	❌	❌	❌	❌
Ruby	👍	👍	👍	❌	👍	❌	❌
Rust	👍	👍	👍	👍	❌	👍	❌
Swift	👍	❌	❌	❌	❌	❌	❌
tcl	👍	❌	❌	❌	❌	❌	❌
VimL (vimscript)	👍	❌	❌	👍	❌	👍	❌
Zig	👍	❌	❌	❌	❌	❌	❌
zsh	👍	❌	👍	👍	❌	👍	❌
Add custom filetypes	👍	👍	👍	👍	❌	❌	👍
Customizable callback formatter	❌	❌	❌	👍	❌	❌	❌
Implemented in	Lua	Lua	Lua	Lua	Lua	VimL	Lua

Other similar plugins (less popular or unmaintained):

• my-neovim-pluglist
• vim-debugstring
• vim-printf