nvim-regexplainer

Describe the regular expression under the cursor.

Regexplainer.mov

railroads.webm

Heavily inspired by the venerable atom-regexp-railroad.

👉 NOTE: Requires Neovim 0.11+ 👈

🚚 Installation

vim.pack.add {
  'https://github.com/bennypowers/nvim-regexplainer',
  'https://github.com/edluffy/hologram.nvim', -- for graphical mode
}

Dependencies

nvim-regexplainer requires the regex treesitter parser, as well as the parser for the host language.

Supported languages:

• JavaScript (and TypeScript)
• HTML
• Ruby
• Python
• Go
• Rust
• PHP
• Java
• C#

Run :checkhealth regexplainer to verify your treesitter setup.

🤔 Config

-- defaults
require'regexplainer'.setup {
  -- 'narrative', 'graphical'
  mode = 'narrative',

  -- automatically show the explainer when the cursor enters a regexp
  auto = false,

  -- filetypes in which to activate regexplainer
  filetypes = {
    'html',
    'javascript',
    'javascriptreact',
    'typescript',
    'typescriptreact',
    'ruby',
    'python',
    'go',
    'rust',
    'php',
    'java',
    'cs',
  },

  -- Whether to log debug messages
  debug = false,

  -- 'split', 'popup'
  display = 'popup',

  mappings = {
    toggle = 'gR',
    -- examples, not defaults:
    -- show = 'gS',
    -- hide = 'gH',
    -- show_split = 'gP',
    -- show_popup = 'gU',
  },

  narrative = {
    indendation_string = '> ', -- default '  '
  },

  graphical = {
    width = 800,        -- image width in pixels
    height = 600,       -- image height in pixels  
    python_cmd = nil,   -- python command (auto-detected)
  },

  deps = {
    auto_install = true,    -- automatically install Python dependencies
    python_cmd = nil,       -- python command (auto-detected)
    venv_path = nil,        -- virtual environment path (auto-generated)
    check_interval = 3600,  -- dependency check interval in seconds
  },
}

display

Regexplainer offers a small variety of display modes to suit your preferences.

Split Window

Set to split to display the explainer in a window below the editor. The window will be reused, and has the filetype Regexplainer

Popup Below Cursor

Set to popup (the default) to display the explainer in a popup below the cursor. When the cursor moves, the popup closes. if auto is set, the popup will automatically display whenever the cursor moves inside a regular expression You can call show with your own display type to override your config

require'regexplainer'.show { display = 'split' }

Or use the commands RegexplainerShowSplit or RegexplainerShowPopup. RegexplainerHide and RegexplainerToggle are also available.

You can customize the popup window by specifying options.popup.border. Any options specified for options.popup will also override the defaults.

require'regexplainer'.show {
  display = 'popup',
  popup = {
    border = {
      padding = { 1, 2 },
      style = 'solid',
    },
  },
}

You could use this to, for example, set a different border based on the state of your editor.

Render Options

narrative.indendation_string can be a function taking the current component and returning an indendation indicator string. For example, to show the capture group on each line:

narrative = {
  indentation_string = function(component)
    return component.capture_depth .. '>  '
  end
},

Input:

/zero(one(two(three)))/;

Output:

`zero`
capture group 1:
1>  `one`
1>  capture group 2:
1>  2>  `two`
1>  2>  capture group 3:
1>  2>  3>  `three`

Yank

You can yank the regexplanation into any register with the yank function. The default register is ". This can be useful if you'd like to share the explanation of a regexp with your teammates, or if you'd like to report a mistake in regexplainer. The argument to yank is either a string (the register to yank to) or a table with register: string and options to show (e.g. mode = 'narrative', narrative = {}, etc.).

For example, to copy the regexplanation to your system clipboard, use either of these:

require'regexplainer'.yank'+'

require'regexplainer'.yank { register = '+' }

You can also use the command RegexplainerYank

:RegexplainerYank +

🚂 Graphical Mode

Regexplainer supports displaying regular expressions as visual railroad diagrams, providing an intuitive visual representation of regex patterns that makes complex expressions easier to understand at a glance.

Requirements

• hologram.nvim plugin for image display
• A supported terminal (Kitty, iTerm2, or other hologram-compatible terminals)
• Python 3.7+ (dependencies are managed automatically)

Quick Start

Set the mode to graphical in your configuration:

require'regexplainer'.setup {
  mode = 'graphical',
  -- Both popup and split modes work with graphical display
  display = 'popup', -- or 'split'
  
  graphical = {
    -- Optional: customize image generation
    generation_width = 1200,   -- Initial generation width (default: 1200)
    generation_height = 800,   -- Initial generation height (default: 800)
  },
  
  deps = {
    auto_install = true, -- automatically install Python dependencies
  },
}

Features

• 🎨 Visual railroad diagrams: Convert regex patterns into clear, readable railroad diagrams using the railroad-diagrams library
• 📱 Multiple display modes: Works in both popup windows (with pattern overlay) and split windows
• 🔧 Smart sizing: Images automatically scale to fit your window while preserving aspect ratio
• ⚡ Caching: Generated diagrams are cached for faster subsequent displays
• 🐍 Zero-config Python: Dependencies are automatically managed in an isolated environment
• 📺 Wide terminal support: Works with any terminal supported by hologram.nvim
• 🔄 Graceful fallback: Automatically falls back to narrative mode if graphics are unavailable
• 🚀 Cross-platform: Fully compatible with Windows, macOS, and Linux

Display Modes

Popup Mode (Default)

• Railroad diagram appears in a popup window
• Original regex pattern shown in a separate overlay
• Automatically closes when cursor moves away
• Perfect for quick regex inspection

Split Mode

• Railroad diagram appears in a dedicated split window
• Original pattern remains visible in the main buffer
• Great for complex regex analysis and comparison

Dependency Management

nvim-regexplainer automatically handles all Python dependencies:

• 🔄 Automatic installation: Required packages (railroad-diagrams, Pillow, cairosvg) are installed when first needed
• 🏠 Isolated environment: Uses a virtual environment in the plugin directory
• 🔒 System-safe: Never affects your system Python installation
• 🩺 Health checks: Run :checkhealth regexplainer to verify everything is working

Manual Dependency Management

If you prefer manual control:

require'regexplainer'.setup {
  mode = 'graphical',
  deps = {
    auto_install = false,
    python_cmd = 'python3', -- specify Python executable
    venv_path = '/custom/path', -- custom virtual environment path
  },
}

Then install the required packages:

pip install railroad-diagrams Pillow cairosvg

🗃️ TODO list

• Display Regexp railroad diagrams using ASCII-art
• Display Regexp railroad diagrams via hologram.nvim
• Support both popup and split display modes for graphical diagrams
• Automatic Python dependency management
• Cross-platform compatibility (Windows, macOS, Linux)
• Add sixel protocol support for wider terminal compatibility
• online documentation
• some unit tests or something, i guess