search

structurizr / cli

A command line utility for Structurizr.
https://docs.structurizr.com/cli
Apache License 2.0
500 stars 77 forks source link

Change "Getting started" example to fit restrictions of VS Code plugin #34

Closed dvrensk closed 3 years ago

dvrensk commented 3 years ago

The systemticks.c4-dsl-extension for VS Code has important features like in-editor previews but disallows some valid DSL. This commit caters to the lowest common denominator in the interest of smoothing adaption.

simonbrowndotje commented 3 years ago

Thanks for this. Have you raised an issue on the extension itself? I think I'd prefer this was fixed at source, rather than patching over the underlying issue.

dvrensk commented 3 years ago

Hi! No, I haven't contacted them yet. I agree that the issue should be fixed at the root, but they are aware of the problems and have this to say in their documentation:

Divergences The goal is, that the Xtext grammar (used in this extension) is compliant to the origin language reference. However the Xtext grammar is a bit more strict in some points:

  • Double quote characters ("...") are mandatory, even when a property does not contain whitespaces
  • You can't use keywords like person or container as variable names

I hope that they will find a fix for this in the longer run, but right now, I can live with some capriciousness on part of the extension if it means that I get a working close-to-real-time preview function.

simonbrowndotje commented 3 years ago

I think I'd recommend:

  1. Making a PR to the extensions project with your updated examples ... if people are using the extension, I imagine they would look there for examples anyway.
  2. Raising an issue about the divergences ... your other PR removes some double-quotes, so I'm not sure they are truly mandatory everywhere.
dvrensk commented 3 years ago

if people are using the extension, I imagine they would look there for examples anyway.

Maybe they will. I know it never occurred to me, because I was perusing your sites and found the following:

  1. https://github.com/structurizr/cli -> https://github.com/structurizr/cli/blob/master/docs/getting-started.md
  2. https://structurizr.org/#code -> https://github.com/structurizr/dsl#tooling-support -> VS Code extension - syntax highlighting and PlantUML previews

So, following instructions on your sites, I got an editor with red squigglies. That's what I am trying to fix for my colleagues and others who might follow a similar path.

I absolutely plan to open tickets and one day PRs with the plugin, but I don't see it as an either-or.

As for your comment on removing double-quotes, yes, I saw the irony too. They have built a grammar that's too strict, and whether that is fixable without swapping out the grammar engine remains to be seen. In the meanwhile, having examples that work with the admittedly slightly broken plugin that you link to can't be such a bad idea, can it?

simonbrowndotje commented 3 years ago

Thanks, understood, but this issue needs to be dealt with at source. Since the divergences are noted, and the extension has its own set of examples, I've added a note to the DSL tooling page with some links.