diff options
author | sariel <shahar.ariel@verizonmedia.com> | 2021-11-04 13:22:54 +0200 |
---|---|---|
committer | sariel <shahar.ariel@verizonmedia.com> | 2021-11-04 13:22:54 +0200 |
commit | b6d7fadf6e23b61ab2cb9b172e96a52e44c2f66f (patch) | |
tree | 17e446cc748f5b425daecedf40eb3284eee877b2 /sd-plugin | |
parent | a0a3a6ca0497a94e50642fcb12ab63a17cd2dc06 (diff) |
Update README and BACKLOG files
Diffstat (limited to 'sd-plugin')
-rw-r--r-- | sd-plugin/BACKLOG.md | 34 | ||||
-rw-r--r-- | sd-plugin/README.md | 43 |
2 files changed, 64 insertions, 13 deletions
diff --git a/sd-plugin/BACKLOG.md b/sd-plugin/BACKLOG.md new file mode 100644 index 00000000000..19e185dcc6b --- /dev/null +++ b/sd-plugin/BACKLOG.md @@ -0,0 +1,34 @@ +### Open Issues + +1. In some cases, the grammar prefers not to enforce bad syntax, because if the parser encounters bad syntax it stops +and can't build the PSI tree. That means none of the features will work for a file like that. For example, in cases +where an element supposes to have zero-to-one occurrences, the grammar will treat it as zero-to-many. +2. In order to enable the grammar recognize some keywords as identifiers (e.g. "filter" as a field's name), the +identifier rule (named "IdentifierVal") wraps the regex (ID_REG) and the KeywordOrIdentifier rule (which contains all +the keywords in the language). +3. The implementation of the GoTo Declaration feature is not exactly the same as IntelliJ. In IntelliJ if a reference +has several declarations, after clicking "Goto Declaration" there is a little window with all the declarations to choose +from. It can be done by changing the method "multiResolve" in SdReference.java to return more than one declaration. The +problem with that is that it causes the "Find Usages" feature to not work. For now, I decided to make the plugin +"Goto Declaration" feature show only the most specific declaration by the right rank-profile scope. +4. The "Find Usages" window can group usages only under rank-profiles and document-summaries. Other usages appear +directly under the .sd file. In order to create another group type of usages' group, you'll need to create 2 classes: +one for the extension "fileStructureGroupRuleProvider" (e.g. SdRankProfileGroupingRuleProvider.java), and one for the +grouping rule itself (e.g. SdRankProfileGroupingRule.java). +Another open problem is that the navigation isn't working in the current grouping rules. It means that when clicking on +the group headline (e.g. some name of a rank-profile) the IDE doesn't "jump" to the matching declaration. +5. Goto declaration doesn't work for document's inherits. e.g. if document A inherits from document B, B doesn't have a +reference to its declaration. +6. There aren't any tests for the plugin. + +### Some useful links: +1. JetBrains official tutorials: https://plugins.jetbrains.com/docs/intellij/custom-language-support.html and +https://plugins.jetbrains.com/docs/intellij/custom-language-support-tutorial.html +2. Grammar-Kit HOWTO: Helps to understand the BNF syntax. + https://github.com/JetBrains/Grammar-Kit/blob/master/HOWTO.md +3. How to deal with left-recursion in the grammar (in SD for example it happens in expressions). Last answer here: +https://intellij-support.jetbrains.com/hc/en-us/community/posts/360001258300-What-s-the-alternative-to-left-recursion-in-GrammarKit- +4. Great tutorial for a custom-language-plugin, but only for the basics (mainly the parser and lexer): + https://medium.com/@shan1024/custom-language-plugin-development-for-intellij-idea-part-01-d6a41ab96bc9 +5. Code of Dart (some custom language) plugin for IntelliJ: +https://github.com/JetBrains/intellij-plugins/tree/0f07ca63355d5530b441ca566c98f17c560e77f8/Dart
\ No newline at end of file diff --git a/sd-plugin/README.md b/sd-plugin/README.md index 74ca1781596..86bebc7d3b1 100644 --- a/sd-plugin/README.md +++ b/sd-plugin/README.md @@ -1,25 +1,42 @@ <!-- Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. --> -This directory holds the code for an IntteliJ plugin for reading SD files. +This directory holds the code for an IntelliJ plugin for reading SD files. -NOTE: This is the source code, not the plugin itself. In order to be able to use the plugin you'll need to download it from JetBrains Marketplace or create a zip file and load it to IntelliJ (details later). +NOTE: This is the source code, not the plugin itself. In order to be able to use the plugin you'll need to download it +from JetBrains Marketplace or create a zip file and load it to IntelliJ by choosing "Install Plugin from Disk". -Before cloning, you should download Gradle and create a Gradle project. -You should also download Grammar-Kit plugin from the Marketplace. +Before starting, you should: +1. Download Gradle 7 (if you don't have it already). +2. Make sure that the bundled Plugin DevKit plugin is enabled (inside IntelliJ). +3. Optional- Download Grammar-Kit plugin from JetBrains Marketplace (inside IntelliJ). It helps with reading the .bnf file. +4. Optional- Download PsiViewer plugin from JetBrains Marketplace (inside IntelliJ). It helps to test the grammar defined +in the .bnf file. +### Working Process The grammar is defined in 2 files: - sd.bnf - sd.flex -After cloning, you should: -1. Right-click the sd.bnf file and press "Generate Parser Code" -2. Right-click the sd.flex file and press "Run JFlex Generator" - -Now you should have a "gen" folder next to the "java" folder, and it contains all the parser and lexer code. +In order to generate the lexer and parser's code, you need to run in the command line: -Important note! After any change in one of this 2 files (bnf, flex) you'll need to generate again. The proper way is to delete the "gen" folder and then do 1-2 again. + ./gradlew generateSdParser + ./gradlew generateSdLexer + +You should now have a "gen" folder next to the "java" folder, and it contains all the parser and lexer code. + +NOTE- Running those tasks would reset the "gen" folder, and all the previous generated files would be deleted before the +new ones would be generated. Now, you can run the gradle task "intellij/runIde", open a project with some sd file and see how the plugin works on it. -In order to test the plugin locally (on you IDE, not by running the gradle task "runIde"), you can run the gradle task -"intellij/buildPlugin". It would create a zip file in the directory build\distributions. You can load it to IntelliJ by -clicking the "settings" in preferences/Plugins and click "Install Plugin from disk".
\ No newline at end of file +### Build the Plugin +In order to build the plugin and create a zip file from it, you should run the command: + + ./gradlew buildPlugin + +Or since it's a default task you can just run: + + ./gradlew + +This task also invokes the tasks generateSdParser and generateSdLexer as a part of the building process. + +Now, you'll have a zip file in the directory build\distributions. |