Structured Text (IEC 61131-3)

[Serhioromano]

Language
Language for programming PLC one of the 5 in IEC 61131-3 standard.

Additional resources
The language specification is not public for free. I wanted to contribute it. I have already contributed support for this language for highlight.js, Monaco editor, VS Code extension. Unfortunately, I cannot get how to make it here. I mean I understood file syntax but is there a deve playground? How I can watch the progress while development? Can I run some server so that after changes JS file I could simply update in the browser and see a result? Or I have to compile it first?

What is the development flow?

[RunDevelopment]

Unfortunately, the documentation of adding a new language is lacking, so here is a brief summary of my usual workflow when adding a new language.

1. Create a new file prism-lang-id.js under components/.

2. Edit components.json to register the added language. Include your new language in the languages object. (Please note that all languages are sorted alphabetically by title.) The added object might look like this:

   "lang-id": {
       "title": "Language Title",
       "owner": "Your GitHub name"
   }

   If your language definition needs any other languages, you have to specify this here as well by adding a "require" property. E.g. "require": "clike", or "require" : ["markup", "css"].

3. Rebuild Prism by running npx gulp.
   This will make your language available on the test page, or more precise: your local version of it. You can just open the test.html page in any browser, select your language, and... well... test the language. Note that you have to reload the page to apply changes made in prism-lang-id.js.
   The test page is probably the most helpful tool Prism has when it comes to writing language definitions.

4. Write the language definition.
   The extending page explains the makeup of language definitions.

5. When done writing the language definition: Add some test.
   Create a folder lang-id under tests/languages/. This is where your test files will live. The test format and how to run tests is described here. You should add a test for every major feature of your language. Test files should test the common case and certain edge cases (if any).
   You can use this template for new .test files:

   The code to test.
   
   ----------------------------------------------------
   
   [ "JSON of the simplified token stream. We will add this later." ]
   
   ----------------------------------------------------
   
   Brief description.
   

   For every test file:

   1. Add the code to test and a brief description.
   2. Verify that your language actually highlights the test code correctly. This can be done using the test page. Note: Using the Show tokens options, you see the token stream your language definition created.
   3. Once you carefully checked that the test case is handled correctly (i.e. by using the test page), run the following command:
      npm run test:languages -- --language=lang-id --pretty
      This command will run only your tests. The new test will fail because the specified JSON is incorrect but the error message of the failed test case will also include the JSON of the simplified token stream Prism created. This is what we're after. Just replace the current incorrect JSON with the output labeled Token Stream. (Please also adjust the indentation. We use tabs.)
   4. Carefully check that the token stream JSON you just inserted is what you expect.
   5. Re-run npm run test:languages -- --language=lang-id --pretty to verify that the test passes.

6. Run npm test to check that all tests pass, not just your language tests.
   This will usually pass without problems. If you can't get all the tests to pass, skip this step. We will help you.

7. Add an example page.
   Create a new file prism-lang-id.html under examples/. This will be the template containing the example markup. Just look at other examples to see how these files are structured.
   We don't have any rules as to what counts as an example, but I usually opt for a single Full example section where I present the correct highlighting of all major features of the language.

8. Run npx gulp again.

9. Make a PR!

I hope this helps. If you have any questions, feel free to ask.

[mAAdhaTTah]

@RunDevelopment You should take that comment and copy it into the docs and PR it. That's a really great summary!

[maddie]

It would be great if IEC 61131-3 is supported! I wanted to port the Highlight.js version over but have no idea how it works.

[Serhioromano]

It would be great if IEC 61131-3 is supported! I wanted to port the Highlight.js version over but have no idea how it works.

I've created highlight.js support for ST

https://github.com/highlightjs/highlightjs-structured-text

It works like any other language in hljs. Tell me more about what environment you are and I'll suggest how to highlight. I highlight with this my ST book.

I would create highlights for prism but there is no documentation and I do not have time to go through all the source code to get how it works.

[maddie]

@Serhioromano Thanks for the reply.

Actually, I'm using Docusaurus v2 which has PrismJS as its syntax highlight engine. I tried to use Highlight.js along with PrismJS but:

• I couldn't make it work (not really good at front-end things)
• It doesn't seem like a great solution (having two syntax highlight libraries loaded)

I have figured out a way to add additional language to PrismJS in Docusaurus, but I don't know the correct definition of the language.

So it would be great if ST can be supported by PrismJS!

EDIT: By the way, there's documentation on adding a new language here: https://prismjs.com/extending.html

I've already added some for ST in my project with this guide, but I doubt that they're correct 😂

[RunDevelopment]

there is no documentation

@Serhioromano Could you please tell what additional information you need and I'll try to add it.

[Serhioromano]

@maddie I see. let me see if I can find some time to look through.

@RunDevelopment right now I find everything I would need to add ST support, except time :) I'll see if I can find some time to go through.

[Serhioromano]

@RunDevelopment I started to look at it. Generated simple file and run npx gulp. It generated files

I think those that are highlighted should not be PR, right? Should those be added to .gitignore?

[RunDevelopment]

Nope. All generated files (including the highlighted ones) have to be in your PR or else the build will fail.

All except package-lock.json. Please don't commit this file. You can use npm ci instead of npm i to install dependencies without changing package-lock.json.

[Serhioromano]

I've added PR but it has conflicts now n those files.

[Serhioromano]

@maddie I've submitter PR at #2310. Please follow this PR to find out when it is merged

[maddie]

@Serhioromano Thanks a lot for your contribution!

[RunDevelopment]

Closed by #2311.