rep node seems to reset the count

[danielo515]

Hello, first of all, thanks for the most impressive snippet engine I ever used, period.
I may be wrong, but I think I noticed an undocumented (and for me unexpected) behavior.
It seems that the rep node is skipt in the node count. So, to give you an example, this snippet is correct:

  s({ trig = "test", dscr = "just a test" }, fmt("{} {} {}", { i(1, "x"), rep(1), i(2, "y") })),

Note that, despite being three nodes, and 3 items in the list the last insert node must refer to the 2 position. While it can make sense if you know it, this is a bit confusing and I think it should at least be documented.

It becomes even weirder when you put it in first place, because you say it should repeat the first node, then the next is the first node, and it seems to produce very strange behaviours too:

  s( "test", fmt("{} {} {}", { rep(1), i(1, "x"), i(2, "y") })),

For example, for some reason it exits my insert mode, so the next thing I type is often interpreted as a vim command, however this is not always the case, and not all keys behaves like this, very strange...

[L3MON4D3]

Hello, first of all, thanks for the most impressive snippet engine I ever used, period.

:D

I think the main problem here is that we don't make it extremely clear that the positions in fmt have absolutely nothing to do with the jump-index of the nodes.
I can see how this misconception arises, with fmt being very close to lsp-syntax.
The current "fmt can be used to create snippets in a more readable way" could definitely be more detailed.

[L3MON4D3]

quick pr in #551, is it clearer this way? (Doc here)

[danielo515]

Hello, and thanks for your reply. That makes easier to understand how fmt works internally and clarifies things a bit, but it still does not explain how that influences the rest of the luasnip semantics. What does it mean that each occurrence of a insertion pair is replaced by a node from the provided table? My understanding is that we will end with a list of nodes, just like we were not using fmt at all, but how does that influence the way you have to configure those nodes ( AKA the arguments you pass to them)? I think my main confusion comes from what indexes are in the context of lua snip. I thought that the indexes you pass to the various nodes (insert, repeat, function node) are the actual indexes of the other nodes in the table. So if you have a table with `t, i(1), t, i(2)` the index 1 will be a text node, but re-reading the documentation it seems that everything always refers to the indexes of the insertion nodes? Is insertion node AND jump position equivalent? So, if I have an snippet that refers to any other node (let's say, `rep(1)`) but I don't have any insert node, will that result in an error? I think this is a key concept to understand the whole luasnip concept. The fact that indexes, jump positions and insert nodes seems to be used interchangeably doesn't help, specially because the concept of index is so broad and generic that can be wrongly interpreted (like I think I did). Thank you for putting the effort and time into making the documentation clearer and better.

…

On Fri, Aug 26, 2022 at 12:26 PM L3MON4D3 ***@***.***> wrote: quick pr in #551 <#551>, is it clearer this way? (Doc here <https://github.com/L3MON4D3/LuaSnip/blob/fmt_doc_improve/DOC.md#fmt>) — Reply to this email directly, view it on GitHub <#550 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARKJWLZRHYNDQCYOBA2RLTV3CLUNANCNFSM57VXVCKA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

-- --- https://danielorodriguez.com

[L3MON4D3]

but re-reading the documentation it seems that everything always refers to the indexes of the insertion nodes

Yes, that's it exactly.

Is insertion node AND jump position equivalent?

In general not (insertNode is just the node, jump position determines when the node is jumped to), but it's possible that they're used interchangeably 😅

So, if I have an snippet that refers to any other node (let's say, rep(1)) but I don't have any insert node, will that result in an error?

Yup, basically (not an error to be precise, the rep(1) just won't be evaluated)

The fact that indexes, jump positions and insert nodes seems to be used interchangeably doesn't help, specially because the concept of index is so broad and generic that can be wrongly interpreted (like I think I did).

Ouh, I hadn't thought of that, but makes perfect sense.
I think the reason they're all used is that I'm not really happy with any of them.
Thinking on it, jump-index is the least misleading name. position indicates that the 1,2,3,... somehow determine the position of the jump.
I'll look into making the doc more uniform in that regard

[danielo515]

Thanks again for keeping making the docs better and an open mind on it

Ouh, I hadn't thought of that, but makes perfect sense.
I think the reason they're all used is that I'm not really happy with any of them.

I know what you are talking about. Naming is hard, and when you're in doubt some days you feel one name is right, so you use that name for the piece of documentation you are writing and then you are happy with that. Next day, it can be different and that accumulates over the months 😄

Thinking on it, jump-index is the least misleading name. position indicates that the 1,2,3,... somehow determine the position of the jump.

Yes, that is probably the less ambiguous name, harder to misinterpret.
It is worth mentioning that, the mood I usually came to the Luasnip docs is not the best: I am doing something else, and I have the feeling for a great snippet, then I just jump directly to my snippets file, try to write it and only if I fail to do so I will check the docs with the urge of doing it as quick as possible to not loose focus on what I was actually working on. So docs are probably more approachable to what they look to me.

That said, I am actively reading the docs, and here are the points that I was able to understand (and below, some observations that make me think different).
So, there are three important "index" concepts in the docs:

1. The index of each node in a Lua table. This index only matters in a single place, and that is the list of nodes you pass to the snippet function. Other than that, this has no effect on the snippet (or should not, more info on this below).
2. The jump-index. This is a key concept within what luasnip is and offers, and probably needs to be explained as soon as possible. Basically a jump-index is created by any node that allows user interaction, for example insert nodes, choice nodes. It is not clear to me what happens when more than one of the nodes that create jump-indexes reference the same jump-index (for example, to insert nodes with the same index). Also, it is worth noticing that this jump-index is what other "dependant" nodes take as argument. For example the rep node or the function node. In both the function and the rep docs the jump-index is called just index, which is one of my main sources of confusion.
3. There is also another place where you may think there are indexes: in the fmt string. It looks that each placeholder in the FMT string gets an index based on it's position, making this some kind of derivative of 1 because it produces a table of nodes that you can pass to the snippet function, but it can duplicate jump-indexes if you pass repeated placeholders that reference the same named key. This is by far the trickiest to understand because, as I said, it seems to deviate from both 1 and 2

With my new knowledge of 1 and 2 I decided to give my snippet ideas another try, and I discovered that, in the third case (the list generated by fmt) the order of the jump-indexes is somehow linked to the order of the placeholders in the format string, even if you use key/named placeholders. Why do I think like this? Look at this 2 versions of the same snippet.
This does not work:

  fmt(
    [[ s({{ trig = "{trig}", dscr = "{dscr}", {regTrig} }}, {} )]],
    { trig = i(1), dscr = i(3, "description"), regTrig = c(2, { t "", t "regTrig=true" }), i(0) }
  )

And this DOES work:

  fmt(
    [[ s({{ trig = "{trig}", dscr = "{dscr}", {regTrig} }}, {} )]],
    { trig = i(1), dscr = i(2, "description"), regTrig = c(3, { t "", t "regTrig=true" }), i(0) }
  )

The difference between the two is that, in the first case, the dscr node gets a jump-index that does not matches it's position in the format string, and when you jump from one node to the next it gets skipped. In the second example however, it gets the index 2, which matches its appearance in the format string and in that case it works correctly.
So, despite using named placeholders, and even when the jump-index should not be linked with the position of the node in the table of nodes, it is somehow related.
Maybe this is just a wrong usage of the API from my side, or just a corner case, but it definitely confuses me 😄

[L3MON4D3]

Thanks again for keeping making the docs better and an open mind on it

The better the docs are, the more I can tell users to RTFM :P

It is worth mentioning that, the mood I usually came to the Luasnip docs is not the best: I am doing something else, and I have the feeling for a great snippet, then I just jump directly to my snippets file, try to write it and only if I fail to do so I will check the docs with the urge of doing it as quick as possible to not loose focus on what I was actually working on. So docs are probably more approachable to what they look to me.

Mhmm, that's interesting, and sounds like it could be pretty common.
One change we should make to accomodate this more: some parts of the doc are just a big block of text, something like "the first argument is so-and-so, and does ..., the second is this-and-that, and does ...". Those should all be changed to lists, so one can quickly get an overview by just taking a look.
Do you have any ideas to improve that workflow?

Mhh, the fmt-examples both work just fine for me. Are you getting an error for the first?
But I'd definitely be very confused if one of those failed, and the other worked fine, so I can relate 😅

[danielo515]

If both examples work as expected, then it is probably something wrong in my configuration. I use lunarvim and they have quite complex jump logic, so I can not be sure there. About the workflow that I mentioned earlier, the only thing that comes to my mind is to try to interpolate more little examples for each concept. I know there is a great file of examples, maybe linking to the lines within that file that contains examples using the described methods will help. Humans usually work nest with concrete examples.

On Mon, 29 Aug 2022 at 19:45, L3MON4D3 ***@***.***> wrote: Thanks again for keeping making the docs better and an open mind on it The better the docs are, the more I can tell users to RTFM :P It is worth mentioning that, the mood I usually came to the Luasnip docs is not the best: I am doing something else, and I have the feeling for a great snippet, then I just jump directly to my snippets file, try to write it and only if I fail to do so I will check the docs with the urge of doing it as quick as possible to not loose focus on what I was actually working on. So docs are probably more approachable to what they look to me. Mhmm, that's interesting, and sounds like it could be pretty common. One change we should make to accomodate this more: some parts of the doc are just a big block of text, something like "the first argument is so-and-so, and does ..., the second is this-and-that, and does ...". Those should all be changed to lists, so one can quickly get an overview by just taking a look. Do you have any ideas to improve that workflow? Mhh, the fmt-examples both work just fine for me. Are you getting an error for the first? But I'd definitely be very confused if one of those failed, and the other worked fine, so I can relate 😅 — Reply to this email directly, view it on GitHub <#550 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARKJWLX4X25YBKEYP4MJBTV3TZL3ANCNFSM57VXVCKA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

-- --- https://danielorodriguez.com

[L3MON4D3]

If both examples work as expected, then it is probably something wrong in
my configuration. I use lunarvim and they have quite complex jump logic, so
I can not be sure there.

Ahh, maybe, best bring it to their attention. Maybe they have modified the default-fmt 🤷

Regarding examples, linking to those in Examples/snippets.lua would work, but linenumbers are pretty hard to keep intact.
I think we'll have to incorporate more examples in DOC.md, but that shouldn't hurt.