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 !
.
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
.
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.
!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.
Note that the
java -jar plantuml.jar -DTITLE="My title" atest1.txt
-D
flag must be put after the "-jar plantuml.jar
" section.
@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
%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
Variable | Content |
%dirpath% | Path of the current file |
%filename% | Name of the current file |
!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
@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
!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
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
...
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.
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