How is diagram type determined

0 votes
asked Jun 14, 2021 in Question / help by skrech

I'm new to PlantUML but I'd really like to start using it more. However, every time I try to read about it I get very confused at how PlantUML decides what to output. It seems that there are various types (component, class, actor, etc) and associated operations (various links/arrows), but it turns out that some combinations of types can't be mixed within a "context" (eg. single block between @startuml/@enduml). It seems that there is some form of type inference involved when not explicitly declaring types, but it's not documented and feels a bit magical.

So, is there some overview of the inner working of PlantUML, which explains how types are inferred, what can be mixed and why/why not?

1 Answer

0 votes
answered Jun 16, 2021 by Martin (8,360 points)

I agree it is confusing.  Plantuml supports multiple diagram types each with their own independent syntaxes.  And you can start most of them with @startuml (although other start commands are available to help the parser).  I'm really not sure how the code picks the parser that best fits what you've typed.  In particular "usecase", "component", and "deployment" are very similar (in fact I think they may actually share the same parser and just be logical distinctions, which is why you can mix and match between them).  And as people ask for consistency of features across diagram types, they all get more and more similar.  Unfortunately Plantuml doesn't have a parameterised syntax (eg ANTLR), instead the source code is splattered with regex matching, making it difficult to work out what the possible syntaxes are - I don't think anyone has managed a 'rail-road syntax diagram' for Plantuml.  But the flexibility is what makes Plantuml powerful.  I'm afraid the best advice I can give is to browse the documentation for the different diagram types along the top bar of, pick the diagram type that best fits what you want to draw, and then stick to the syntax in that documentation section.  (Then there are few common documentation sections such as "style" and "creole" and "preprocessing" and "commons" that are useful to all diagram types, so browsing is the next step.)