[mini.ai] The perfect mini-word textobject

[Bvngee]

In the mini.ai help file, there's this custom textobject example:

-- Word with camel case support:
{
  {
    '%u[%l%d]+%f[^%l%d]',
    '%f[%S][%l%d]+%f[^%l%d]',
    '%f[%P][%l%d]+%f[^%l%d]',
    '^[%l%d]+%f[^%l%d]',
  },
  '^().*()$'
}

I absolutely love this textobject and use it to rename variables/functions all the time. However, it has problems:

• breaks with SNAKE_CASE_IN_UPPERCASE
• doesn't work with some instances of Snake_Case_Titlecase (i.e. single-letter words)
• supports regular standalone lowercase words, but not uppercase ones
• worst of all: There's no comments or explanations and it looks like Egyptian hieroglyphics.

So, here's my updated version that fixes these issues with sufficient comments. It supports, as far as I can tell, all text cases and capitalizations:

-- snake_case, camelCase, PascalCase, etc; all capitalizations
{
  -- Lua 5.1 character classes and the undocumented frontier pattern:
  -- https://www.lua.org/manual/5.1/manual.html#5.4.1
  -- http://lua-users.org/wiki/FrontierPattern
  -- note: when I say "letter" I technically mean "letter or digit"
  {
    -- Matches a single uppercase letter followed by 1+ lowercase letters.
    -- This covers:
    -- - PascalCaseWords (or the latter part of camelCaseWords)
    '%u[%l%d]+%f[^%l%d]', -- An uppercase letter, 1+ lowercase letters, to end of lowercase letters

    -- Matches lowercase letters up until not lowercase letter.
    -- This covers:
    -- - start of camelCaseWords (just the `camel`)
    -- - snake_case_words in lowercase
    -- - regular lowercase words
    '%f[^%s%p][%l%d]+%f[^%l%d]', -- after whitespace/punctuation, 1+ lowercase letters, to end of lowercase letters
    '^[%l%d]+%f[^%l%d]', -- after beginning of line, 1+ lowercase letters, to end of lowercase letters

    -- Matches uppercase or lowercase letters up until not letters.
    -- This covers:
    -- - SNAKE_CASE_WORDS in uppercase
    -- - Snake_Case_Words in titlecase
    -- - regular UPPERCASE words
    -- (it must be both uppercase and lowercase otherwise it will
    -- match just the first letter of PascalCaseWords)
    '%f[^%s%p][%a%d]+%f[^%a%d]', -- after whitespace/punctuation, 1+ letters, to end of letters
    '^[%a%d]+%f[^%a%d]', -- after beginning of line, 1+ letters, to end of letters 
  },
  '^().*()$',
}

Trust me, you will not regret this. This is one of the biggest quality-of-life improvements I've had with vim editing yet. Take a look:

perfect-textobj.mp4

[Bvngee]

I'd be interested to hear if anyone thinks the regex can be simplified. It took me quite a while to understand what it was doing (especially the %f pattern) but I could very likely be missing some opportunity for further improvement.

[echasnovski]

I'd be interested to hear if anyone thinks the regex can be simplified. It took me quite a while to understand what it was doing (especially the %f pattern) but I could very likely be missing some opportunity for further improvement.

One thing comes to mind: [%a%d] set (all letters and digits) is quite literally %w (all alphanumeric characters).

[echasnovski]

Nice job of "translating" Lua patterns into regular English :) As with any regex-like systems, first time encountering them can be daunting. It gets easier with time.

The example was mostly added as a demo of capabilities for what looks like a popular textobject. I personally don't like using it as it feels "too magical". Regular Vim/Neovim operators textobjects together with a_ / i_ from 'mini.ai' feels enough for me. But everyone is different :)

[JeanMertz]

Thank you for this. I've been playing around with this and it does work great. One thing I cannot get to work: select multiple subwords.

For example, given this:

*FooBarBaz

How would I make a selection:

<FooBar>Baz

Here's what works for a single inner word for me:

v(isual)i(nner)s(ubword)
<Foo>BarBaz

All of these don't work

-- not sure what happens here, even `FooBarBazQux` extends the entire word,
-- so I assume some other motion is triggered.
--
-- I *assume* this should be the correct textobject motion to get what I want, but
-- it's not working.
v2is 
<FooBarBaz>

2vis
<Foo>BarBaz

-- Errors (as expected, `2` is not a valid configured selection target).
vi2s

-- I understand `next` and `last` skip over existing text before applying the selection
-- So this is applying the correct motion before selection, added for completion.
vins
Foo<Bar>Baz

-- Again, working as expected.
v2ins
FooBar<Baz>

[drowning-cat]

Pattern only

Added support for around snake_case, kebab-case:

Note

I won't even pretend that you'll be able to understand this, but I hope there's a way to turn it into something more comprehensible.

Warning

The query is intentionally implemented this way to prefer left-handed underscores over right-handed ones. It can be useful when using subword motion plugins like chrisgrieser/nvim-spider. Use t instead of f to find the next position to paste the yanked subword.

local ai = require 'mini.ai'
ai.setup {
  custom_textobjects = {
    e = {
      {
        -- __-1, __-U, __-l, __-1_, __-U_, __-l_
        '[^_%-]()[_%-]+()%w()()[%s%p]',
        '^()[_%-]+()%w()()[%s%p]',
        -- __-123SNAKE
        '[^_%-]()[_%-]+()%d+%u[%u%d]+()()',
        '^()[_%-]+()%d+%u[%u%d]+()()',
        -- __-123snake
        '[^_%-]()[_%-]+()%d+%l[%l%d]+()()',
        '^()[_%-]+()%d+%l[%l%d]+()()',
        -- __-SNAKE, __-SNAKE123
        '[^_%-]()[_%-]+()%u[%u%d]+()()',
        '^()[_%-]+()%u[%u%d]+()()',
        -- __-snake, __-Snake, __-snake123, __-Snake123
        '[^_%-]()[_%-]+()%a[%l%d]+()()',
        '^()[_%-]+()%a[%l%d]+()()',
        -- UPPER, UPPER123, UPPER-__, UPPER123-__
        -- No support: 123UPPER
        '[^_%-%u]()()%u[%u%d]+()[_%-]*()',
        '^()()%u[%u%d]+()[_%-]*()',
        -- UPlower, UPlower123, UPlower-__, UPlower123-__
        '%u%u()()[%l%d]+()[_%-]*()',
        -- lower, lower123, lower-__, lower123-__
        '[^_%-%w]()()[%l%d]+()[_%-]*()',
        '^()()[%l%d]+()[_%-]*()',
        -- Camel, Camel123, Camel-__, Camel123-__
        '[^_%-%u]()()%u[%l%d]+()[_%-]*()',
        '^()()%u[%l%d]+()[_%-]*()',
      },
    },
  },
}

[drowning-cat]

Hybrid

Note

Added support for around snake_case, kebab-case.

Note

End subwords with numbers.

local MiniAi = require 'mini.ai'
MiniAi.setup {
  custom_textobjects = {
    -- NOTE: Use any subword pattern you like, just ignore separators
    e = {
      {
        "%f[%a]%l+%d*",
        "%f[%w]%d+",
        "%f[%u]%u%f[%A]%d*",
        "%f[%u]%u%l+%d*",
        "%f[%u]%u%u+%d*",
      },
    },
  },
}
local expand_separator = function(range, edge)
  local from, to = range.from, range.to
  local line = function(r)
    return assert(vim.api.nvim_buf_get_lines(0, r.line - 1, r.line, true)[1])
  end
  local left = line(from):sub(1, from.col - 1):find("[_%-]+$")
  local _, right = line(to):find("^[_%-]+", to.col + 1)
  -- stylua: ignore start
  if left then from.col = left elseif right then to.col = right end
  return from, to
end
vim.keymap.set("o", "ae", function()
  local range = MiniAi.find_textobject("i", "e")
  if range then
    local from, to = expand_separator(range)
    vim.api.nvim_win_set_cursor(0, { from.line, from.col - 1 })
    vim.cmd("normal! v")
    vim.api.nvim_win_set_cursor(0, { to.line, to.col - 1 })
  end
end)

---

@echasnovski,

There’s only one small problem with defining patterns as in the provided example: the first matching pattern always wins, not necessarily the most relevant one. For example, my pattern groups collide on the string lowerUPPER. If the cursor is on the letter U, the match is still lower. Ideally, if there is only an inner group, it should define the winning result:

"[^%u%l]()%l%l+%d*()[^%l%d]"
          ^^^^^^^^

Example pattern:

e = {
  {
    -- lower123
    '[^%u%l]()%l%l+%d*()[^%l%d]',
    -- UPPER123
    '[^%u]()%u%u+%d*()%u%l',
    '[^%u]()%u%u+%d*()[^%d]',
    -- Camel123NAME4
    '()%u%l+%d*()[^%d]',
    -- U, l, 1
    '[^%u]()%u()[^%u%l]',
    '[^%l]()%l()[^%l]',
    '[^%d]()%d()[^%d]',
    -- 123|UPPER, 123|lower, 123|Camel
    '[%s%p]()%d+()[^%d]',
  },
},

[echasnovski]

There’s only one small problem with defining patterns as in the provided example: the first matching pattern always wins, not necessarily the most relevant one.

I don't think this is the case. The "best" pattern wins, with definition of "best" depending on search method. What might be happening, is that for overlapping matched regions the one with smaller width wins.

For example, my pattern groups collide on the string lowerUPPER. If the cursor is on the letter U, the match is still lower. Ideally, if there is only an inner group, it should define the winning result:

I can not reproduce. Here are the steps:

• Use the following setup:

  require('mini.ai').setup({
    custom_textobjects = {
      e = {
        {
          -- lower123
          '[^%u%l]()%l%l+%d*()[^%l%d]',
          -- UPPER123
          '[^%u]()%u%u+%d*()%u%l',
          '[^%u]()%u%u+%d*()[^%d]',
          -- Camel123NAME4
          '()%u%l+%d*()[^%d]',
          -- U, l, 1
          '[^%u]()%u()[^%u%l]',
          '[^%l]()%l()[^%l]',
          '[^%d]()%d()[^%d]',
          -- 123|UPPER, 123|lower, 123|Camel
          '[%s%p]()%d+()[^%d]',
        },
      },
    },
  })

• In fresh session, open a buffer and type lowerUPPER.

• With cursor on U, press vie. It selects UPPER.

[drowning-cat]

Video

cie.mp4

You're right. It works in a new buffer without spaces. I probably need to explicitly specify the spaces for patterns.

[echasnovski]

You're right. It works in a new buffer without spaces. I probably need to explicitly specify the spaces for patterns.

As suspected, this seems to be the case of overlapping regions:

• -- lowerUPPER selects lower with cursor on U.
• -- lowerrUPPER select UPPER with cursor on U.

[drowning-cat]

Okay, I reworked the pattern. The main idea is to end words with numbers:

-- Camel123|lower123|UPPER123|UPPER ...
-- 123|l|U U123

e = {
  {
    "%f[%a]%l+%d*",
    "%f[%w]%d+",
    "%f[%u]%u%f[%A]%d*",
    "%f[%u]%u%l+%d*",
    "%f[%u]%u%u+%d*",
  },
}