Drawing diagrams with PlantUML
Custom Images
In addition to the integrated icons, you can also create custom images. Listing 9 shows the source for embedding a custom image, and Figure 8 shows its output.
Listing 9
Embedding Images
01 @startuml 02 sprite tux linuxtux.png 03 Linux->World : I am here <$tux>, where are you? 04 Linux<-World : I am SO glad to see you! 05 @enduml
To do this, define a sprite
(a graphical element) with a label (tux
in my example) and associate it with an actual image on your hard drive. Next, you can place the image where you want by calling its label with the syntax shown in line 3 of Listing 8. In addition to regular images, you may define and embed custom sprites [7], which are monochrome images that are defined similarly to traditional ASCII art right inside your UML code:
startuml sprite $foo1 { FFFFFFFFFFFFFFF F0123456789ABCF F0123456789ABCF FFFFFFFFFFFFFFF }
This format is less esoteric than it may seem. Each hexadecimal digit inside the curly braces corresponds to one pixel of the image, and its value corresponds to the gray level of that pixel, with
being white, and F
being black. For further details on embedded sprites, see the PlantUML guide [5].
UML Programming
UML's creators have given it several capabilities of a real programming language.
You can include comments in your UML files to make them more readable. Single line comments start with one simple quote ('
), and multiline comments are enclosed by /'
and '/
tags.
Lines that start with exclamation marks (!
) are preprocessing directives, with which you can give PlantUML general instructions or make it interact with your system. The following
!log Now generating a Gantt Diagram
tells PlantUML to log a message, by writing it to its standard output.
PlantUML also uses variables and functions. PlantUML variables can only contain strings or integer numbers; it is good practice to give them names starting with a dollar sign ($
), like Perl. Besides storing values for later use, variables can also be used for simple flow control, to decide what to draw where:
Alice -> Bob : Are you free tonight? !if ($day == "Saturday") Alice <- Bob : yes !else Alice -> Bob : no, I'm sorry !endif
PlantUML supports three different types of functions: built-in, void, and return functions. Built-in functions, which have names starting with %
, include operators like %strlen
(string length) or %substr
(substring extraction). Other built-in functions give access to system information, like file location or the current date.
Void and return functions are recognizable, because, like variables, their names must start with a dollar sign ($
). The difference is simple between void and return functions and summarized in Listing 10.
Listing 10
Void and Return Functions
01 !function $warning($source, $recipient) 02 $source --> $recipient : Warning! You have been hacked! 03 !endfunction 04 !function $halfvalue($a) 05 !return $a/2 06 !endfunction
Void functions directly insert something (normally one statement) into the UML diagram description. In Listing 10, the $warning
function (line 1) will print a warning from user $source
to user $recipient
whenever it is called, obviously replacing $source
and $recipient
with the current values of those variables. Return functions perform a calculation or string processing and return the result (lines 4 and 5); they are often called from other functions.
In both void and return functions, you can define local variables, which are not visible from outside the function, and set default values for the arguments.
Code Management
In UML, as in software in general, reuse is almost always good, and duplication is almost always bad. You can put all the configuration and formatting functions that you regularly use in one file and make PlantUML load it as follows:
java -jar /path/to/plantuml.jar -config "./config.cfg" dir1
To do the same thing with the actual drawing code (e.g., the initial part of a sequence exchange or flow diagram) that you want to duplicate in other diagrams, you can write the corresponding code once (maybe packaging it as a function) in one file. Then !include
that file in other files every time you need it as follows:
@startuml !include common-diagrams-section.iuml .. your other UML code here @enduml
By doing this, any change in that single file will be seen and reloaded by all the files that include it the next time you run PlantUML, just as if you had copied and pasted common-diagrams-section
in each file. The !include
directive supports URLs, so you may even load code directly from the Internet or your company network. By default, a file can only be included once. You may include the same file several times in your code with the !include_many
directive, but think twice before doing it: It may make your code unmanageable.
Syntax-wise, you may also put several independent blocks of common code in the same file, each within its own @startuml
/@enduml
statements, and identify each of those blocks by their number. A directive like !include myuml.txt!1
will then load only the second (numbering starts from
) block within myuml.txt
. To improve code readability, you can assign names to a block
@startuml(id=SOME_IDENTIFIER)
and then include only that block with this statement
!include foo.txt!SOME_IDENTIFIER
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
![Learn More](https://www.linux-magazine.com/var/linux_magazin/storage/images/media/linux-magazine-eng-us/images/misc/learn-more/834592-1-eng-US/Learn-More_medium.png)
News
-
NVIDIA Released Driver for Upcoming NVIDIA 560 GPU for Linux
Not only has NVIDIA released the driver for its upcoming CPU series, it's the first release that defaults to using open-source GPU kernel modules.
-
OpenMandriva Lx 24.07 Released
If you’re into rolling release Linux distributions, OpenMandriva ROME has a new snapshot with a new kernel.
-
Kernel 6.10 Available for General Usage
Linus Torvalds has released the 6.10 kernel and it includes significant performance increases for Intel Core hybrid systems and more.
-
TUXEDO Computers Releases InfinityBook Pro 14 Gen9 Laptop
Sporting either AMD or Intel CPUs, the TUXEDO InfinityBook Pro 14 is an extremely compact, lightweight, sturdy powerhouse.
-
Google Extends Support for Linux Kernels Used for Android
Because the LTS Linux kernel releases are so important to Android, Google has decided to extend the support period beyond that offered by the kernel development team.
-
Linux Mint 22 Stable Delayed
If you're anxious about getting your hands on the stable release of Linux Mint 22, it looks as if you're going to have to wait a bit longer.
-
Nitrux 3.5.1 Available for Install
The latest version of the immutable, systemd-free distribution includes an updated kernel and NVIDIA driver.
-
Debian 12.6 Released with Plenty of Bug Fixes and Updates
The sixth update to Debian "Bookworm" is all about security mitigations and making adjustments for some "serious problems."
-
Canonical Offers 12-Year LTS for Open Source Docker Images
Canonical is expanding its LTS offering to reach beyond the DEB packages with a new distro-less Docker image.
-
Plasma Desktop 6.1 Released with Several Enhancements
If you're a fan of Plasma Desktop, you should be excited about this new point release.