A short introduction to PlantUML

Unified Modeling Language (UML) is presented in academia mainly through GUI applications which implement the aforementioned standard, all of which are inefficient to navigate and hard to maintain. PlantUML is a tool that implements UML in a unique manner - a textual language - leading to significant improvements in many areas:

• Reproducibility: GUI UML tools do not whatsoever integrate into the document compilation process, or the writing environment for that matter. It is exceptionally hard to replicate the exact image twice, because the input is variable - the input being a person interacting with the interface using a mouse. For example, many diagrams used throughout this website were not generated by me. Instead, a hand-crafted CI workflow is instructed to build them every time the website receives an update.
• Versioning: Git and every other version control system favor and are optimized for text. PlantUML is a human-readable, human-writable document format, and as a result, the version control system is able to do its compression magic, which in turn saves you a non-negligible amount of time.
• Collaboration: This point ties into the previous one, version control systems are there to track documents as they evolve over time, and thus, collaborating with others becomes much easier.
• Integration: Using PlantUML as part of your workflow is possible regardless of how (or what application) you write. this allows you to mold the tool into your workflow as you see fit.
• Accessibility: GUI UML tools are exceptionally hard for blind people to use, PlantUML is a viable element in making UML more accessible [1].

My computing environment is revolved around the philosophy of a keyboard-centric worfklow. I find that it saves me a lot of time and energy not having to move my hands beyond the home row, and it's gratifying to jump back and forth between my windows and workspaces at the speed of light. PlantUML, being text-driven, does not hamper my workflow, rather it extends it.

Let's represent the animal kingdom in a class diagram, abstracting it the objected oriented way. Give this a good read.

package Animalia {

  Animal <|-- Feline
  Animal <|-- Canine

  Feline --> Felidae
  Canine --> Canidae

  abstract class Animal {
     {abstract} void jump(height: int)
     {abstract} void run(velocity: int)
  }
  
  class Feline {
     - species: Enum<Felidae>
     + jump(height: int)
     + run(velocity: int)
  }
  
  class Canine {
     - species: Enum<Canidae>
     + jump(height: int)
     + run(velocity: int)
  }

  enum Felidae {
     Jaguar,
     Lion,
     Cougar
  }
  
  enum Canidae {
     Wolf,
     Fox,
     Dog
  }
}

Inside the Animalia package, we find two classes, Feline and Canine which implement the functions defined in Animal, our abstract class. We've also got two enums, Felidae, and Canidae, which hold as many species of the two families as I can possibly think of.

Okay, so how do we tie everything together? You guessed it, with arrows!

We can represent aggregation between two classes with <|-- or --|>, and to represent a normal relationship between two things, such as what you see between the different enums and classes, we can use <-- or -->.

The direction of the pointy bit matters, and it will be reflected as is in the output diagram.

The last thing I'll cover is access modifiers, all of which are assigned a unique icon by PlantUML. Prepending a method or attribute with a + will indicate that it's public – - is private – # is protected and ~ is package private. It's sort of your responsibility to use them appropriately, as PlantUML won't stop you from shooting yourself in the foot.

To see the result of the diagram's textual representation, place the contents of the source in a file, e.g. animalia.puml and run the following command in a shell:

plantuml animalia.puml -tpng animalia.png

You should then see an animalia.png file appear in your working directory… Go on, open it, it should look like this:

I hope I've given PlantUML the proper introduction it deserves. We have barely even touched the surface of what PlantUML can do, but we're already capable of doing so much.