Search code examples
plantuml

How prevent PlantUML from creating error images?

When PlantUML console tool encounters syntax error in a diagram it generates an image with error traceback like the following:

Error image example

Is there a way to disable generating error images and possibly output the traceback into stderr instead?

I generate images from several source files with PlantUML CLI like this:

$ plantuml diag1.puml diag2.puml diag3.puml

Some of these diagrams may have faulty syntax, I need the faulty ones to be skipped.

I could parse the stderr and get faulty diagram names from there, but that's the last resort. I believe there should be a native option for mentioned behavior.

Solution

  • Update 07.07.2021

    since Plantuml version 1.2021.8 there's a new option -noerror which does exactly this: skips faulty diagrams and writes info about errors in them into stderr.

    $ plantuml -noerror diag1.puml diag2.puml diag3.puml
Error line 5 in file: diag2.puml
Some diagram description contains errors

    only two images were generated.

    Pro tip: Plantuml has a wonderful forum where creator promptly responds to all issues and pushes changes into the new version within few days.

    Old answer

    Seems that it's impossible in normal mode, but it is possible in -pipe mode. The sought paramter is -pipeNoStderr.

    If you run PlantUML in pipe mode in console, you can type diagram code and after each diagram it will output the binary code for image right away. You can also use it in scripts to input code in stdin and get results in stdout.

    You should run plantuml like this:

    $ plantuml -pipe -pipeNoStderr -pipedelimitor ___sep___

    Here:

    • -pipe means start plantuml in pipe mode. It will accept diagram code in stdin, immediately process it and return result in stdout in binary format;
    • -pipeNoStderr tells plantuml not to render error images. Instead it will return the error traceback in text format;
    • -pipedelimitor tells plantuml to add separators between diagrams if you send several diagram sources into the pipe. This way you can determine where one image ends and another starts;
    • ___sep___ is a string which I've chosen for separator, it may be anything you like, but unique enough.

    The pipe workflow enforced me to completely rewrite our tool that generates diagrams. Concrete examples in Python are out of the scope of this question, but general steps were:

    1. Collect all diagram sources which you want to render.
    2. Check that each source starts with @startuml and ends with @enduml (otherwise such faulty source may corrupt adjacent diagrams).
    3. Put all sources into one string variable, separated by several newlines.
    4. Run Plantuml subprocess in the pipe mode.
    5. Feed the combined source string to it.
    6. Get response from stdout and split it by the separator (___sep___ in my case)
    7. Cycle through the result list and alert user about elements which start with ERROR and save in binary format elements which don't.

    This article was of great help. It has an example project on JavaScript which solves the problem (unlike me) asynchronically.