[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]

Why

Added support for around snake_case, kebab-case.

Tip

I 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.

Around first (preferred)

Note

End subwords with numbers.

New!

custom_textobjects = {
  e = function(ai_type, id, opts)
    if ai_type == "a" then
      return {
        {
          -- pattern, [^_]pattern_*
          "%f[%a_%-]%l+%d*[_%-]*",
          "%f[%w_%-]%d+[_%-]*",
          "%f[%u_%-]%u%f[%A]%d*[_%-]*",
          "%f[%u_%-]%u%l+%d*[_%-]*",
          "%f[%u_%-]%u%u+%d*[_%-]*",
          -- __pattern
          "%f[_%-][_%-]+%l+%d*",
          "%f[_%-][_%-]+%d+",
          "%f[_%-][_%-]+%u%f[%A]%d*",
          "%f[_%-][_%-]+%u%l+%d*",
          "%f[_%-][_%-]+%u%u+%d*",
          -- __pattern|__
          "[_%-]()()%l+%d*[_%-]+()()",
          "[_%-]()()%d+[_%-]+()()",
          "[_%-]()()%u%f[%A]%d*[_%-]+()()",
          "[_%-]()()%u%l+%d*[_%-]+()()",
          "[_%-]()()%u%u+%d*[_%-]+()()",
        },
      }
    end
    if ai_type == "i" then
      local reg = MiniAi.find_textobject("a", id, opts)
      if reg then
        local line = vim.fn.getline(reg.from.line)
        local _, s = line:find("^[_%-]*.", reg.from.col)
        local e = line:sub(1, reg.to.col):find(".[_%-]*$")
        return vim.tbl_deep_extend("force", reg, { from = { col = s }, to = { col = e } })
      end
    end
  end,
},

Hybrid

Warning

Known issue: the separator isn’t recognized as part of a subword, so the cursor should not be placed on the separator in certain edge cases.

Separate keymap

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 around_subword = function(reg)
  reg = vim.deepcopy(reg)
  local SEP = "[_%-]+"
  local line = vim.fn.getline(reg.from.line)
  local left = line:sub(1, reg.from.col - 1):find(SEP .. "$")
  local _, right = line:find("^" .. SEP, reg.to.col + 1)
  if left then
    reg.from.col = left
  elseif right then
    reg.to.col = right
  end
  return reg
end
vim.keymap.set({ "x", "o" }, "ae", function()
  local reg = MiniAi.find_textobject("i", "e")
  if reg then
    MiniAi.config.custom_textobjects["Virt"] = around_subword(reg)
    MiniAi.select_textobject("i", "Virt")
  end
end)

Pattern only

Caution

Pattern only approach has collisions, see #1434 (comment).

Hide (bad)

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]

@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]

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*",
  },
}

[drowning-cat]

For the pattern

e = { { "%f[%a]%l+%d*" } }

e = { { "%l" } }

and the string

i_next

the behavior changes with die/cie/yie compared to vie:

• With cie, |i_next + cie results in |_next (i is replaced)
• With vie, |i_next + vie results in i_[next] (i stays, and next is selected)

[echasnovski]

I would assume this happens with search_method = 'cover_or_next'? That's probably expected because a single v already selects the whole textobject. And since there is no covering, it selects next. This is a "side effect" of consecutive application (like va)a) can "grow" the selection) of a textobject in Visual mode.

[drowning-cat]

Yes, I used the default search_method. Just thought I’d share in case it’s something you weren’t aware of. It makes sense though, so not a big deal. Thanks :0