Aerijo commented 5 years ago

NOTE: Ready for review

Requirements

Filling out the template is required. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.
All new code requires tests to ensure against regressions

Description of the Change

Redoes a lot of stuff. Basic idea is to comply with the VS Code spec (based on TextMate spec; also used by Sublime Text) as much as possible, because that's the spec language servers are supposed to use. With this, we'll fully support well formed LSP snippets. The added features are also useful anyway, and following an existing spec means we don't have to define our own (though I believe it's all based off of TextMate anyway).

Putting this up now for feedback and trying it out while it's still being worked on.

Added

[X] Support for variables
[X] Support for replacement if / else conditionals based on capture group match
[X] Support for choices (parses the syntax; actual choice popup deferred to later PR)
[X] Support for LSP transformation syntax
[X] Service for custom variable resolvers (not in the spec, but I like this idea a lot)
[X] Implicit end tab stops when one was not already defined (togglable in settings)
[X] Forced undo breaks at each tabstop

Changed

[X] Removed implicit g flag from transformation regex. If users want it, they can add it explicitly. And now, if they don't want it, they have a choice.
[X] The parser has been rewritten, but still creates a tree compatible with the existing logic when using existing features. A notable change is that \ only escapes the characters $, }, and \ (and a few others depending on context).
[X] Specs have been updated to add the g flag where the implicit one was relied upon.
[X] Snippet bodies and tab stops are now formed on demand, and are no longer members of the snippet. This is necessary, given the dynamic nature of variables and their transformations. They are now made in the SnippetExpansion, which is a temporary representation for the expanded snippet.
[x] Refactoring the existing snippet.getTabStops into something more modular. Currently renamed to toString, but it will make the insertion string and tab stops.
[X] Implicit end tab stops (configurable in Settings)
[X] End tab stops now break out of the snippet, so you will no longer be able to tab backwards from one (this is in line with their purpose of marking where to put the cursor when the snippet finishes).
[X] Redid a lot of editor.transact calls; these appeared to only make the undo behaviour fail in strange ways.

Open Questions

[ ] Should \ escape everything? It would make it easier to remember what it does, but subtly break VS Code compatibility (which is slightly different in a few areas anyway). It would also simplify the grammar.
- Am going with no in this PR. May be possible to make configurable in future (especially if users complain), by passing an argument to the parser.

Alternate Designs

Would have removed \u and co flags entirely, but they appear to be supported by TextMate too and so are worth keeping.

Benefits

99% backwards compatible, and adds much more advanced and dynamic capabilities. With custom variable resolvers, users can do pretty much anything with the provided text editor (and any other relevant params).

Possible Drawbacks

Bodies that contained text like ${1|one,two,three|} will now be interpreted, instead of being a literal. But 1. the fix is to escape the $ like this \\${1|one,two,three|} (as the raw CSON value), and 2. no one^* would be doing that unless they wanted a choice placeholder anyway.

^*me

Applicable Issues

Closes #287 (this also contains the decaffeination changes)

Closes #285

Also closes #41 I think

Closes https://github.com/atom/apm/issues/213. That conversion uses alternate replacement syntax (?1:=:=) that now has support added here too.

aviatesk commented 4 years ago

@lee-dohm @lkashef bump. I played with this PR for a while and feel that this fairly works well.

Aerijo commented 4 years ago

@aviatesk Progress is happening; we're aiming to split it into smaller, more manageable PRs. The decaffeination of the remaining files is the first step.