HOME      NEWS      MAP

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 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
Note that the -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

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
File ArrayList.iuml:
class ArrayList
!ifdef SHOW_METHODS
ArrayList : int size()
ArrayList : 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

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

HOME      NEWS      MAP