Preprocessing
Some minor preprocessing capabilities are included in PlantUML, and available for all diagrams.
Those functionnalities are very similar to the C language preprocessor, except that the special character # has been changed to the exclamation mark !.
Including files
Use the !include directive to include file in your diagram.
Imagine you have the very same class that appears in many diagrams. Instead of duplicating the description of this class, you can define a file that contains the description.
@startuml
!include List.iuml
List <|.. ArrayList
@enduml
File List.iuml
interface List
List : int size()
List : void clear()
The file List.iuml can be included in many diagrams, and any modification in this file will change all diagrams that include it.
A file can be only be included once. If you want to include several times the very same file, you have to use the directive !include_many instead of !include.
You can also put several @startuml/@enduml text block in an included file and then specify which block you want to include adding !0 where 0 is the block number.
For example, if you use !include foo.txt!1, the second @startuml/@enduml block within foo.txt will be included.
You can also put an id to some @startuml/@enduml text block in an included file using @startuml(id=MY_OWN_ID) syntax and then include the block adding !MY_OWN_ID when including the file, so using something like !include foo.txt!MY_OWN_ID.
Including Subpart
You can also use !startsub NAME and !endsub to indicate sections of text to include from other files using !includesub. For example:
file1.puml:
@startuml
A -> A : stuff1
!startsub BASIC
B -> B : stuff2
!endsub
C -> C : stuff3
!startsub BASIC
D -> D : stuff4
!endsub
@enduml
file1.puml would be rendered exactly as if it were:
@startuml
A -> A : stuff1
B -> B : stuff2
C -> C : stuff3
D -> D : stuff4
@enduml
However, this would also allow you to have another file2.puml like this:
file2.puml
@startuml
title this contains only B and D
!includesub file1.puml!BASIC
@enduml
This file would be rendered exactly as if:
@startuml
title this contains only B and D
B -> B : stuff2
D -> D : stuff4
@enduml
Including URL
Use the !includeurl directive to include file from Internet/Intranet in your diagram.
You can also use !includeurl http://someurl.com/mypath!0 to specify which @startuml/@enduml block from http://someurl.com/mypath you want to include. The !0 notation denotes the first diagram.
Constant definition
You can define constant using the!define directive. As in C language, a constant name can only use alphanumeric and underscore characters, and cannot start with a digit.
@startuml
!define SEQUENCE (S,#AAAAAA) Database Sequence
!define TABLE (T,#FFAAAA) Database Table
class USER << TABLE >>
class ACCOUNT << TABLE >>
class UID << SEQUENCE >>
USER "1" -- "*" ACCOUNT
USER -> UID
@enduml
Of course, you can use the !include directive to define all your constants in a single file that you include in your diagram.
Constant can be undefined with the !undef XXX directive.
You can also specify constants within the command line, with the -D flags.
java -jar plantuml.jar -DTITLE="My title" atest1.txt
-D flag must be put after the "-jar plantuml.jar" section.
Macro definition
You can also define macro with arguments.
@startuml
!define module(x) component x <<module>>
module(ABC)
module(XYZ)
@enduml
Macro can have several arguments.
@startuml
!define send(a,b,c) a->b : c
send(Alice, Bob, Hello)
send(Bob, Alice, ok)
@enduml
Adding date and time
You can also expand current date and time using the special variable%date%. Date format can be specified using format specified in SimpleDataFormat documentation.
@startuml
!define ANOTHER_DATE %date[yyyy.MM.dd 'at' HH:mm]%
Title Generated %date% or ANOTHER_DATE
alice -> bob
@enduml
Other special variables
You can also use the following special variables:| Variable | Content |
| %dirpath% | Path of the current file |
| %filename% | Name of the current file |
Macro on several lines
You can also define macro on several lines using!definelong and !enddefinelong.
@startuml
!define DOUBLE(x) x x
!definelong AUTHEN(x,y)
x -> y : DOUBLE(hello)
y -> x : ok
!enddefinelong
AUTHEN(Bob,Alice)
@enduml
Default values for macro parameters
It is possible to assign default values to macro parameters.
@startuml
!define some_macro(x, y = "some default" , z = 'another default' ) x and y and z
class foo {
some_macro(Z1, Z2, Z3)
some_macro(Z1, Z2)
some_macro(A)
}
@enduml
Conditions
You can use!ifdef XXX and !endif directives to have conditionnal drawings. The lines between those two directives will be included only if the constant after the !ifdef directive has been defined before.
You can also provide a !else part which will be included if the constant has not been defined.
@startuml
!include ArrayList.iuml
@enduml
class ArrayList
!ifdef SHOW_METHODS
class ArrayList {
int size()
void clear()
}
!endif
You can then use the !define directive to activate the conditionnal part of the diagram.
@startuml
!define SHOW_METHODS
!include ArrayList.iuml
@enduml
You can also use the !ifndef directive that includes lines if the provided constant has NOT been defined.
You can use boolean expression with parenthesis, operators && and || in the test.
@startuml
!define SHOW_FIELDS
!undef SHOW_METHODS
class foo {
!ifdef SHOW_FIELDS || SHOW_METHODS
This is shown
!endif
!ifdef SHOW_FIELDS && SHOW_METHODS
This is NOT shown
!endif
}
@enduml
Building custom library
It's possible to package a set of included files into a single .zip or .jar archive. This single zip/jar can then be imported into your diagram using !import directive.
Once the library has been imported, you can !include file from this single zip/jar.
Example:
@startuml
!import /path/to/customLibrary.zip
' This just adds "customLibrary.zip" in the search path
!include myFolder/myFile.iuml
' Assuming that myFolder/myFile.iuml is located somewhere
' either inside "customLibrary.zip" or on the local filesystem
...
Search path
You can specify the java property plantuml.include.path in the command line.
For example:
java -Dplantuml.include.path="c:/mydir" -jar plantuml.jar atest1.txt
Note the this -D option has to put before the -jar option. -D options after the -jar option will be used to define constants within plantuml preprocessor.
Advanced features
It is possible to append text to a macro argument using the ## syntax.
@startuml
!definelong COMP_TEXTGENCOMP(name)
[name] << Comp >>
interface Ifc << IfcType >> AS name##Ifc
name##Ifc - [name]
!enddefinelong
COMP_TEXTGENCOMP(dummy)
@enduml
A macro can be defined by another macro.
@startuml
!define DOUBLE(x) x x
!definelong AUTHEN(x,y)
x -> y : DOUBLE(hello)
y -> x : ok
!enddefinelong
AUTHEN(Bob,Alice)
@enduml
A macro can be polymorphic with argument count.
@startuml
!define module(x) component x <<module>>
!define module(x,y) component x as y <<module>>
module(foo)
module(bar, barcode)
@enduml
You can use system environment variable or constant definition when using include:
!include %windir%/test1.txt
!define PLANTUML_HOME /home/foo
!include PLANTUML_HOME/test1.txt