Replace the cursor index within the completing word parameter of custom-completion closures with a String completion prefix parameter

[rgoldberg]

Replace the cursor index within the completing word parameter of custom-completion closures with a String completion prefix parameter.

Resolve #769

@natecook1000 @rauhul I think that this is an urgent improvement.

The Swift substring API is exceedingly verbose, and this will make using custom completions much easier.

We don't want to release the current API with the 2 indices to users because then it will need to be supported indefinitely, despite being suboptimal.

Checklist

• I've added at least one test that validates that my change is working, if appropriate
• I've followed the code style of the rest of the project
• I've read the Contribution Guidelines
• I've updated the documentation if necessary

[rgoldberg]

@natecook1000 @rauhul I also have a PR for #555 (supporting async functions as custom completion handlers). I will submit it after this PR has been merged because it is branched from this PR's branch. It's not large at all, so shouldn't take long to review.

Please don't release a new version of Swift Argument Parser without checking with me first, because I might have other useful submissions queued up. Obviously, if I don't respond in a timely manner, go ahead & release new versions whenever you want, but if you could check with me first, I'd appreciate it, and users might get more functionality in the new release. Most importantly, if I realize that a new interface is suboptimal, it should be cleaned up ASAP before being officially released so it won't need to be maintained indefinitely, and so it won't be unpleasant for users.

Thanks again.

[natecook1000]

@rgoldberg This change makes sense, since the conversion from Int to substring can be error-prone. Just to make sure I'm understanding this correctly: if a user has the following text on the command line, with their cursor as marked:

$ example --foo 1 --bar 2 baz bizzle
                           ^ cursor here, on 'a' in 'baz'

...then the parameters passed to the custom completion closure would be as if it were called like:

complete(["example", "--foo", "1", "--bar", "2", "baz", "bizzle"], 5, "b")

Is that right?

[natecook1000]

There's a prefix overload that just takes the count of elements to include, so this can be simplified to .prefix(cursorIndexWithinCompletingArgument).

[rgoldberg]

I will update the PR now. I'm still new to Swift, so my API knowledge is limited. I didn't even realize how verbose it is to get substrings in Swift. Thanks for pointing this out. All similar tips will be greatly appreciated, as it will produce much nicer code & get me up to speed much faster. Thanks.

[rgoldberg]

@natecook1000 Pushed the fix. Thanks again for the tip.

[rgoldberg]

@natecook1000 My zsh cursor is always displayed between characters, not on them. Maybe you can switch cursor modes, but for the cursor in-between character mode, it would be between the b & the a. Typing backspace would delete the b. Typing delete would delete the a. Typing a normal character would insert it between the 2. In that case, the arguments you listed are correct. (sorry to be pedantic, but I want to ensure that I am as unambiguous as possible).

Thanks for looking into this.

[natecook1000]

@swift-ci Please test

[rgoldberg]

The failing API breakage check should be OK because the replaced API was never released in a new version.

[natecook1000]

@rgoldberg We're on the same page! The default cursor indicator for me is a block, even though I think of that as the cursor for overwrite mode (though I can't remember what platform that was on). In any case, you're describing what I meant to.

And exactly, merging over the API breakage check.