More documentation on defining your own rules

[tandrewnichols]

I'm looking at the help doc and the default rules but still struggling to understand how to write my own rules. Not all of the possible keys are defined in the docs, which makes it a challenge. Some make sense and some I can guess at, but what are braket, quotes, literal_quotes, and immutable for?

For reference, I'm trying to add a rule to swap parts of url path (e.g. foo/bar -> bar/foo. So I've got the delimiter as ['\/'] but I don't know how to tell where the beginning and end are, as a url may or may not start/end with a slash . . . or with quotes. I.e. I'd like it to work for urls that look like

$http.get('/foo/bar/baz')

But also for things like

$http.get(apiBase + 'foo/bar/baz') // I'm only worried about tokenizing the string part here
$http.get('/foo/bar/baz?hello=world') // I'm only interested in being able to swap path parts, so the query should be ignored
router.get('/foo/bar/:type') // urls _might_ contain characters that would normally be encoded, e.g. in a parameterized route configuration

and

GET   /foo/bar/baz # urls might not have quotes in a conf file

and maybe even more complicated things like

$http.get('/foo/' + user.id + '/bar')

although that last one seems like it would be difficult to match and swap properly.

Also, it would help me understand the default rules if they had names or examples or both. I can't tell easily just from looking at them what they would match, which means I don't actually know what all the default rules are (which is important if I don't want to end up accidentally reinventing the wheel and if I just want to know what works out of the box . . . like, where can I use this thing I just installed?) In general, a list of default rules with examples in main README (and maybe in the helpdocs too) would be helpful.

[tandrewnichols]

Ok, here's what I have so far. Let me know if you have suggestions to improve this to allow for more of the use cases above:

  \   {
  \     'mode': 'n',
  \     'delimiter': ['\/'],
  \     'surrounds': ['''\|"\|\s', '''\|"\|\s']
  \   }

[tandrewnichols]

(By the way, I did finally find those other property keys in the docs . . . although I still didn't understand them.)

[machakann]

Thank you for your comment! Indeed, names for default rules sounds a good idea. Though regular expression is an extremely useful tool, it's readability is awful. I will work for it and better documentations in this weekend.

In short braket, quotes and literal_quotes are useful in the following case.

this_is_function_name(arg1, [arg2a, arg2b], arg3)

If the cursor is on "arg1", what I want to do is to exchange the order of three items, "arg1", "[arg2a, arg2b]" and "arg3". However, the rule

\  {
\    'surrounds': ['\h\w*(', ')'],
\    'delimiter': ['\s*,\s*'],
\  }

would change the order of four items, "arg1", "[arg2a", "arg2b]", and "arg3". The second list argument is split into two parts because it includes a delimiter inside. Thus what I need is:

\  {
\    'surrounds': ['\h\w*(', ')'],
\    'delimiter': ['\s*,\s*'],
\    'braket': [['[', ']']],
\  }

Then the grouping by "[]" is considered and a comma inside "[arg2a, arg2b]" is ignored to re-order "arg1", "[arg2a, arg2b]" and "arg3".

---

Without braket

With braket

[machakann]

The immutable is something neither a delimiter nor an re-ordered item. But... Actually it is almost same as a delimiter, and not necessarily to use at this moment, probably... Only the difference is re-ordering text would not be placed between a delimiter and a immutable. For example, regarding "," as delimiter and ";" as immutable.

\  {
\    'surrounds': ['(', ')'],
\    'delimiter': [','],
\    'immutable': [';'],
\  }

Given that I want to change the locaion of "text1" in the following string:

(text1,,;text2)

This could be (,text1,;text2) but never be (,,text;text2). Honestly, I made this for future extensions which is not mentioned in the document, but I have not implemented yet, I've almost forgotten about it.

[tandrewnichols]

Ok, I understand braket. Still not so much quotes and literal_quotes. Your explanation also made me wonder how this plugin would handle es6 default function parameters and destructuring assignments, like:

function(a = 12, b = { foo: 'bar' })

and

function({ a, b })

But these are sort of side questions. In general, I was really excited about this plugin. I had a swap parameters plugin previously, but it wasn't always super accurate, and it did really weird things if you ever triggered it outside of a parameter list. This is more general purpose and extensible, which I like. It's just hard to get started because vim regular expressions can be really tricky.

[tandrewnichols]

Is body the thing to match or the thing to scan for matches? I.e. in a url, is it one part of the url path or the full url including the delimiters? I'm having trouble getting body to work as I'd expect. The regex does assign a rule.region but when buffer.swappable is called it returns 0 because len(self.items) is only 1.

[tandrewnichols]

The surrounds I'm using above works for static url strings, but not for url strings inside lodash templates. Here's a gif. The first line works as I'd expect. The second line, for some reason, doesn't cut off correctly at the beginning or at the end (it ignores the single quote on both sides).

Help?

Again, for reference, here's the rule definition I'm using:

  \   {
  \     'mode': 'n',
  \     'delimiter': ['\/'],
  \     'surrounds': ['''/\?\|"/\?\| /\?', '''\|"\| \|?', 0]
  \   }

[tandrewnichols]

It seems to have something with the dollar sign in the second string because it works fine if I take that out.

[machakann]

The body is an alternative of surrounds key and it is an regular expression of whole body including delimiters. If the target is url, then the body includes /.

It seems the filepath (url?) is a difficult example. So far I use this to do.

  \   {
  \     'mode': 'n',
  \     'delimiter': ['\/'],
  \     'surrounds': ['''/\?\|\"/\?\| /\?', '''\|\"\|$', 0]
  \   }

However, I still don't understand what happened in your screen shot. Do you have any other rules in g:swap#rules?

[tandrewnichols]

I don't. I didn't assign the default ones even. Your gif looks like it's working as I'd expect, so let me try that and see if it works on my system too.

[tandrewnichols]

Hmm, copied yours exactly, and still seeing the same behavior. Maybe we have a difference in settings that would cause this?

[machakann]

Hmm, could you tell me the version of your vim editor? You can check by :version command, I want to know the first three lines (or if you are using neovim, I need the first two lines).

[tandrewnichols]

VIM - Vi IMproved 8.0 (2016 Sep 12, compiled Sep 23 2016 10:44:45)                                                                                                                                          
MacOS X (unix) version                                                                                                                                                                                      
Included patches: 1-8 

[machakann]

Thank you! Let me think.

[tandrewnichols]

Just to be clear, I think this probably means it's not really on you to figure this out, although I do appreciate the help.

[machakann]

Thank you for your kind words. It's just for my curiosity, never mind.

[machakann]

Hi, I'm still revising the documents, and it has not finished yet, but maybe I understand the problem. It seems that the existence of the $ was the key to reproduce as you said. There were some codes checking syntax coloring. However, it has been hardly used and very slow and, what was worse, it doesn't work I expected at all. So I deleted them.

Probably the syntax settings for javascript (?) were different with my and your vim. Now it should work as we expected.

I will continue to update documents!

[tandrewnichols]

Oh cool! I'll give it a try. Thanks!

[tandrewnichols]

Yeah, it's working now.

[machakann]

Hi, finally I updated the documents. I hope it would be better than previous!

[tandrewnichols]

Thanks! Looks good!