Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate syntax railroad diagrams #1075

Merged
merged 12 commits into from
Jun 30, 2023
Merged

Generate syntax railroad diagrams #1075

merged 12 commits into from
Jun 30, 2023

Conversation

msujew
Copy link
Member

@msujew msujew commented Jun 5, 2023

Closes #827
Closes #1062

This change introduces a new package, langium-railroad that is able to generate railroad syntax diagrams from Langium grammars. The package is reused in langium-cli and langium-vscode:

  1. To generate a railroad html file for each entry grammar (if specified in the langium-config.json).
  2. Adds a preview command to the current langium editor that shows a webview with the railroad syntax diagram for the currently selected langium editor.

The vscode webview follows the current editor and updates on changes to the grammar file.

The new langium-railroad package can also be used in the playground for an inline syntax diagram view of the current grammar.

@msujew msujew added the cli CLI related issue label Jun 5, 2023
@msujew msujew added this to the v2.0.0 milestone Jun 6, 2023
Copy link
Contributor

@spoenemann spoenemann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great new feature! I also like how it's realized with relatively little code.

packages/langium-vscode/package.json Outdated Show resolved Hide resolved
packages/langium-vscode/src/railroad-webview.ts Outdated Show resolved Hide resolved
@spoenemann
Copy link
Contributor

@msujew could you also add a description of the new webview feature to the extension README (and update it while you're at it)?

Copy link
Contributor

@montymxb montymxb left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is cool! I tried it out on a few of our example languages, and it works quite nicely. Just one suggestion below regarding terminals.

@spoenemann spoenemann requested a review from Lotes June 23, 2023 09:35
@Lotes
Copy link
Contributor

Lotes commented Jun 26, 2023

I think it would be a visual improvement if would choose the same background color as we use for the diagrams. Or make the diagrams transparent, but that would conflict with dark/light mode (lines are black and will not be visible in dark mode).

@msujew
Copy link
Member Author

msujew commented Jun 26, 2023

I think it would be a visual improvement if would choose the same background color as we use for the diagrams. Or make the diagrams transparent, but that would conflict with dark/light mode (lines are black and will not be visible in dark mode).

I think that we can leave those for later :) This PR does what it should, any additional changes can be performed on top.

@Lotes
Copy link
Contributor

Lotes commented Jun 26, 2023

The decision might be already made, but my first try to use the railroads was through the Langium CLI. I was a bit surprised that there is no --help that lists me the option to have diagrams.
I see that we have these flags in a Langium config file. Maybe one place too less. langium init command or a langium generate --railroad maybe?

@msujew
Copy link
Member Author

msujew commented Jun 26, 2023

I see that we have these flags in a Langium config file. Maybe one place too less. langium init command or a langium generate --railroad maybe?

I think a langium generate --railroad command would be nice, but without a target path, it won't work. However, we can't add one, since we generate separate files for each grammar. We also already have documentation on that in the langium-cli readme (appearing on npmjs), and the vscode editor will also propose the railroad property on the langium-config.json file.

Having a better --help might work, but that's also outside of the feature scope.

@msujew msujew merged commit 6b86f74 into main Jun 30, 2023
3 checks passed
@msujew msujew deleted the msujew/railroad-diagrams branch June 30, 2023 11:34
spoenemann pushed a commit that referenced this pull request Aug 15, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cli CLI related issue
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Grammar railroad diagram Generate syntax diagrams
4 participants