feat: Getregion function

[Shougo]

Continues of #11579

It is not only for visual mode.

[chrisbra]

I think this is a nice addition. I think we should call it getline_region() so that it comes close to the description of the getline() function.

However, we need tests here. Including testing what happens with invalid positions, multibyte character support, tab handling, and testing failure modes if possible.

[Shougo]

I think this is a nice addition. I think we should call it getline_region() so that it comes close to the description of the getline() function.

Well, the rename is needed?

However, we need tests here. Including testing what happens with invalid positions, multibyte character support, tab handling, and testing failure modes if possible.

Yes. The tests are needed...

[habamax]

Thank you @Shougo and the rest who helped!

[justinmk]

Why doesn't this return a list of positions? Return text is the least useful part about a region. How can plugin authors get the positions that correspond to a visual block region (for example)? That is still an unsolved problem.

getregion() yet it doesn't return a position structure, which means that plugins still have to manually figure out the part of a buffer that corresponds to a region.

[chrisbra]

Why doesn't this return a list of positions? Return text is the least useful part about a region.

The functionality of this function was to be to get the buffer content of whatever those positions would define. Au contraire, getting the buffer content was an unsolved problem before, positions would need to be known before hand so I fail to see how this would be "more useful".

How can plugin authors get the positions that correspond to a visual block region (for example)? That is still an unsolved problem.

You can use getpos() of those positions already. Don't see why this is a problem.

[zeertzjq]

For blockwise Visual selection it'll probably need a combination of getpos(), virtcol() and virtcol2col().

[chrisbra]

correct and visualmode()

[justinmk]

You can use getpos() of those positions already. Don't see why this is a problem.

You cannot easily get the dimensions of the buffer text that is described by a region. This is the code that is currently required to do that: https://github.com/neovim/neovim/blob/d35a8a9bbe385daf808984ba0fc7f07f51a96da0/runtime/lua/vim/_editor.lua#L509-L578

[clason]

(Note that this is not as trivial as it seems once you add multibyte and ambiwidth unicode characters to the mix -- which that code can't handle fully, despite its complexity)

[zeertzjq]

Also ref neovim/neovim#21115 the initial discussion and implementation of this function. For getting text the interface is easy, but when it comes to getting buffer positions the interface gets complicated when 'virtualedit' is concerned.

[Shougo]

Well, I should add the option to return the range feature?

[kuuote]

I think range feature is good. but shouldn't add to getregion().
Should split entry point to another function because determine return type by arguments is hard to understand.

[chrisbra]

correct, there was a single purpose for the getregion() function, which was to retrieve the selected text between 2 different (start and end) positions. Now the discussion moves away to a different usecase. That should be a new vimscript function. However, I still don't understand the need for it:

We are giving already positions to the getrange() function. You are talking about dimensions of positions, which I don't understand. What exactly do you mean by that? Can you please give concrete examples? Why exactly are start and end positions not enough? Can you spell out the help documentation for what this function should do?

[justinmk]

We are giving already positions to the getrange() function. You are talking about dimensions of positions, which I don't understand

For a give region defined by 2 opposite "corners", the actual buffer text bounded by those corners, depends on (1) the buffer text itself, (2) inclusive/exclusive, (3) selection type (v/V/^v), (4) multibyte. Mapping a region to buffer text is non-trivial.

Perhaps name it getregionpos() ?

[chrisbra]

Yes, but you already have those positions. So where do those positions come then from? In other words if you already have the positions, why do you need to use getregionpos()?

BTW: I have for years used a similar approach to this in one of my plugins. Set the marks '< and '> to those positions and then set the selection type. Use norm! gv to reselect those regions. Has worked quite well.

[clason]

Yes, but you already have those positions. So where do those positions come then from?

No we don't; that's exactly what we're asking from here. (We have a hack that works in some situations, but not enough.)

[chrisbra]

Then it's even more curious why you mention it here in the PR for getregion(), since that function already receives the position. Can you please create a new issue with whathever you like to have? Please also mention what the help description should explain.

[clason]

(To be clear, I'm not the one complaining here; just trying to provide some additional context.)

[chrisbra]

sure understood and thanks. (And to be clear, I am just trying to understand the missing pieces)

[clason]

Basically, given a pair of positions (which could be '< and '> -- the main use case, in fact) return an array of positions { line1 = {col_start, col_end}, line2 = {col_start, col_end}} that respects

• setreg-style selection type (char/line/block)
• whether ending column is inclusive/exclusive
• 'virtualedit'
• works with double-width (flag emoji) and amiwidth (thai) unicode
• ...

Basically, convert a visual-block selection to an array of line-wise selections to then, say, apply highlights to. (Main use case here: highlight-on-yank as in https://github.com/machakann/vim-highlightedyank.) Especially the last points basically rely on Vim internals to be guaranteed to be correct

[justinmk]

Basically, convert a visual-block selection to an array of line-wise selections to then, say, apply highlights to.

"to char-wise", right?

(Main use case here: highlight-on-yank as in https://github.com/machakann/vim-highlightedyank.)

To @chrisbra 's point, if nvim_buf_set_extmark accepted {pos1}, {pos2}, {regtype}, {inclusive} parameters, then we wouldn't need getregionpos() for that particular case.

This raises the more general question about how a buffer region is described. Currently in Vim, a buffer region is described by those 4 parameters. So we have 2 choices:

• every API that accepts a "region" has those 4 parameters
• introduce a getregionpos() which returns a list of start/end positions, and then APIs only need to accept start/end parameters, because the caller can use getregionpos() and feed its result into any such API.

Created #14609