nvim-regexplainer

Describe the regular expression under the cursor.

https://user-images.githubusercontent.com/1466420/156946492-a05600dc-0a5b-49e6-9ad2-417a403909a8.mov

Heavily inspired by the venerable atom-regexp-railroad.

👉 NOTE: Requires Neovim 0.7 👈

🚚 Installation

use { 'bennypowers/nvim-regexplainer',
      config = function() require'regexplainer'.setup() end,
      requires = {
        'nvim-treesitter/nvim-treesitter',
        'MunifTanjim/nui.nvim',
      } }

You need to install regex with nvim-treesitter

:TSInstall regex

🤔 Config

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

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

  -- filetypes (i.e. extensions) in which to run the autocommand
  filetypes = {
    'html',
    'js',
    'cjs',
    'mjs',
    'ts',
    'jsx',
    'tsx',
    'cjsx',
    'mjsx',
  },

  -- Whether to log debug messages
  debug = false, 

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

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

  narrative = {
    separator = '\n',
  },
}

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, which is a table of popup options from nui. 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.

Pasteboard

The pasteboard display mode copies the regexplanation to your system pasteboard. 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.

require'regexplainer'.show { display = "pasteboard" }

Render Options

narrative.separator can also be a function taking the current component and returning a string clause separator. For example, to separate clauses by a new line, followed by > for each level of capture-group depth, define the following function:

narrative = {
  separator = function(component)
    local sep = '\n';
    if component.depth > 0 then
      for _ = 1, component.depth do
        sep = sep .. '> '
      end
    end
    return sep
  end
},

Input:

/zero(one(two(?<inner>three)))/;

Output:

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

A Note about Lookbehinds

While https://github.com/tree-sitter/tree-sitter-regex/issues/13 is still open, lookbehind support is partial, and results may not be accurate, especially if the term in the lookbehind is complex, e.g.

/(?<!http|https:\/\/)www\.regex101\.com/;

🗃️ TODO list

• [ ] Display Regexp railroad diagrams using ASCII-art
• [ ] Display Regexp railroad diagrams via hologram and kitty image protocol
• [ ] online documentation
• [x] some unit tests or something, i guess