plantuml-parser 0.0.12 introduces TypeScript declarations. Now you can parse PlantUML and get a fully typed result. PlantUML diagrams are awesome! In this post I first give a brief introduction into PlantUML. Then I will show how you can use plantuml-parser with TypeScript to make the most out of your diagrams.

She wouldn’t be my type either

Show source @startuml actor Alice actor Bob Alice -> Bob: Tells Bob that

she does not like

types Bob --> Alice: Leaves her @enduml

Show parser result [ { "elements": [ { "left": "Alice", "right": "Bob", "leftType": "Unknown", "rightType": "Unknown", "leftArrowHead": "", "rightArrowHead": ">", "leftArrowBody": "-", "rightArrowBody": "-", "leftCardinality": "", "rightCardinality": "", "label": "Tells Bob that\

she does not like\

types", "hidden": false }, { "left": "Bob", "right": "Alice", "leftType": "Unknown", "rightType": "Unknown", "leftArrowHead": "", "rightArrowHead": ">", "leftArrowBody": "-", "rightArrowBody": "-", "leftCardinality": "", "rightCardinality": "", "label": "Leaves her", "hidden": false } ] } ]

Table of Contents

Why you should use PlantUML

PlantUML is an open-source tool allowing users to create UML diagrams from a plain text language. The language of PlantUML is an example of a Domain-specific language. It uses Graphviz software to lay out its diagrams. – Source: wikipedia/PlantUML

I use PlantUML daily. A textual description of design diagrams alongside the source code is my definition of a living document. You know the pain of out of date documentation. Did you ever ask yourself why this happens? As a software developer I do reject a tool if it does not make my life easier. Writing sound and solid source code is already hard enough. Having to deal with a ton of different documentation formats makes it even harder. Belive me, if design changes can be documented with a few simple modifications of a text file, I will start doing it.

This has the effect that documentation evolves together with the code. Add version control to the mix and pull requests suddenly become self-documenting. Furthermore, switching to Graphviz means no longer spending hours layouting documents. Time better spent doing actual design work.

With PlantUML you can document without proprietary file mongering software or an overpriced vector graphic editor. In case you ask yourself what all that fuzz is about. You create your design documents in PowerPoint and you are happy with it - Then you should probably ask yourself when things started to go wrong in you life.

You will find another Alice

Show source @startuml (*) --> If "Do you know PlantUML?" then --> [No] "Learn PlantUML" If "" then --> [I don't

have time] "Leave Alice" --> "Learn PlantUML" else --> [Ok] "Good" EndIf else --> [Yes] "Good" EndIf --> "Parse it" @enduml

You are now completely convinced and/or you already created a lot of documentation in PlantUML. Good. But at some point you might like to get even more from that the language. So why not start parsing it?

Parsing PlantUML with TypeScript

Parsing the syntax to something machine-processable is easy with the command line plantuml-parser .

Show example $ npm install -g plantuml-parser $ plantuml-parser << EOF > @startuml > package "Wonderful world without Alice" { > file Doc > file JSON > interface PlantUML > component "plantuml-parser" as pp > > Doc -right- PlantUML > PlantUML ..> pp > pp -left-> JSON > } > @enduml > EOF [ { "elements": [ { "name": "Wonderful world without Alice", "title": "Wonderful world without Alice", "type": "package", "elements": [ { "name": "PlantUML", "title": "PlantUML", "members": [] }, { "name": "pp", "title": "plantuml-parser" }, { "left": "Doc", "right": "PlantUML", "leftType": "Unknown", "rightType": "Unknown", "leftArrowHead": "", "rightArrowHead": "", "leftArrowBody": "-", "rightArrowBody": "-", "leftCardinality": "", "rightCardinality": "", "label": "", "hidden": false }, { "left": "PlantUML", "right": "pp", "leftType": "Unknown", "rightType": "Unknown", "leftArrowHead": "", "rightArrowHead": ">", "leftArrowBody": ".", "rightArrowBody": ".", "leftCardinality": "", "rightCardinality": "", "label": "", "hidden": false }, { "left": "pp", "right": "JSON", "leftType": "Unknown", "rightType": "Unknown", "leftArrowHead": "", "rightArrowHead": ">", "leftArrowBody": "-", "rightArrowBody": "-", "leftCardinality": "", "rightCardinality": "", "label": "", "hidden": false } ] } ] } ]

But today we want to have a look at the programmatic use of the parser. Therefore I created the following demonstration which shows how easy it is to parse PlantUML in TypeScript. The demonstration also contains an example on how type guards can leverage processing of diagrams.

Show source let diag = ` @startuml class Alice <<single>> { +cry(): any } note left of Alice::cry Untyped. She does not like types end note @enduml ` // importing the parser import { parse , Class , Note } from ' plantuml-parser ' ; // for each diagram parsed for ( let d of parse ( diag ) ){ // extract all elements let elems = d . elements ; for ( let e of elems ) { // we can use type guards to // distinguish between the different // elements in the diagram if ( e instanceof Class ) { console . log ( ' Class: ' + e . name ); } if ( e instanceof Note ){ console . log ( ' Note on ' + e . of ); } } }

Contribute

If you do like the project and you would like to contribute, there are numerous ways how you can do so. Even if you do not write source code. Every contribution counts.

Thank you.