[wtp-dev] Information on SSE - JSON editor

[Patrik Suzzi <psuzzi@xxxxxxxxx>]

Hi All,

I'd like to share with you some information about the JSON editor,
and provide a starting point to understand SSE-derived editors.

Thanks to Alina, Victor, Angelo, Nitin, and all others helping JSDT
for their efforts

= SSE > JSON Editor

The JSON editor is based on SSE, and is heavily inspired to XML and CSS editors.
this page is a good starting point:
https://eclipse.org/webtools/wst/components/sse/overview.html

Here we have a list of WTP Sour(ce edit = SSE ) > JSON Editotr bugs:
https://bugs.eclipse.org/bugs/buglist.cgi?component=wst.json&list_id=13851761&product=WTP%20Source%20Editing

== JSON formatter

- bug 486524 is low priority as fixing model sync could fix the formatter
The JSON formatter works exactly as the XML and CSS formatters.
When a Region of the text editor is selected and you press format, the
underlying (AST) node is sent to be formatted via
AbstractJSONSourceFormatter#formatProc(IJSONNode node, IRegion
region): StringBuilder.

== IJSONModel Synch

- bug 486860 has high priority
The Editor is based on IJSONModel, so IXMLModel and ICSSModel are a
good starting point to compare.
The synch of IJSONMOdel is a complex task. To improve this synch,
Angelo suggest to set a breakpoint in the JSONModelImpl#nodesReplaced,
type some content in the text editor and debug.

When this bug is fixed, we should add tests like:
https://github.com/angelozerr/eclipse-wtp-json/blob/master/core/org.eclipse.wst.json.core.tests/src/org/eclipse/wst/json/core/document/JSONObjectDocumentChangesTest.java

== JSON Parser grammar

The JSON parser uses a scanner generated with JFlex, that works as the
XML Parser (all WTP parsers are using JFlex). The performances are
quite good, even with big-sized files. See the JSON parser classes
here:
https://github.com/angelozerr/eclipse-wtp-json/tree/master/core/org.eclipse.wst.json.core/src/org/eclipse/wst/json/core/internal/parser

See also the syntax highlighter here:
https://github.com/angelozerr/eclipse-wtp-json/tree/master/core/org.eclipse.wst.json.core/Resource/parserTools/highlighting

The JSON parser's grammar supports also comments, that is not included
in JSON specs.
See https://github.com/angelozerr/eclipse-wtp-json/wiki/SyntaxColoring#json-comment
(note: most commercial products still are not supporting JSON comments)

== SSE related tests:

I asked Nitin, for a suggestion on which are the most important tests
to write when implementing a new SSE-based editor.
- He suggested to first make sure the parser meet the criteria : "They
must be able to handle any text (legal or not) and must return regions
that completely cover the input text (for example, whitespace can not
simply be ignored). More difficult to implement, another constraint is
that for any (correctly specified) subset of text, the reparser must
give the same results that the parser would if parsed from top to
bottom."
- "Then moving up to tests checking the structure versus different
inputs, then before and after making text changes".

Below there is a link to Angelo's test for loading an SSE IStructuredDocument.
https://github.com/angelozerr/eclipse-wtp-json/blob/master/core/org.eclipse.wst.json.core.tests/src/org/eclipse/wst/json/core/TestUtil.java
note: You will need to execute it as JUnit Plug-in test

This test emulates when the user changes the document
https://github.com/angelozerr/eclipse-wtp-json/blob/master/core/org.eclipse.wst.json.core.tests/src/org/eclipse/wst/json/core/document/JSONObjectDocumentChangesTest.java
In particular, this line
https://github.com/angelozerr/eclipse-wtp-json/blob/master/core/org.eclipse.wst.json.core.tests/src/org/eclipse/wst/json/core/document/JSONObjectDocumentChangesTest.java#L33
will call  JSONModelImpl#nodeReplaced

Which Angelo thinks it might be the method to be improved to fix the model sync

== Concluding

Thanks again for the efforts and please, share your feedback / links /
suggestions it you think this can improve the general understanding of
the topic.

Kind Regards,

Patrik Suzzi
https://about.me/psuzzi

P.S:
Here you find articles on
http://www.asegno.com/2016/eclipse/jsdt-development/ and
http://www.asegno.com/2016/eclipse/jsdt-project-structure/