Some preprocessing capabilities are included in PlantUML, and available for all diagrams.

Those functionalities are very similar to the C language preprocessor, except that the special character # has been changed to the exclamation mark !.

Although this is not mandatory, we highly suggest that variable names start with a $.

There are three types of data: * Integer number (int); * String (str) - these must be surrounded by single quote or double quote; * JSON (JSON) - these must be surrounded by curly brackets. (for JSON variable definition and usage, see more details on link::preprocessing-json[Preprocessing-JSON page])

Variables created outside function are global, that is you can access them from everywhere (including from functions). You can emphasize this by using the optional global keyword when defining a variable.

You can also assign a value to a variable, only if it is not already defined, with the syntax: !$a ?= "foo"

You can use !while and !endwhile keywords to have repeat loops.

Example:

Variables defined in procedures are local. It means that the variable is destroyed when the procedure ends.

A return function does not output any text. It just define a function that you can call: * directly in variable definition or in diagram text * from other return functions * from procedures

It is possible to shorten simple function definition in one line:

As in procedure (void function), variable are local by default (they are destroyed when the function is exited). However, you can access to global variables from function. However, you can use the local keyword to create a local variable if ever a global variable exists with the same name.

In both procedure and return functions, you can define default values for arguments.

Only arguments at the end of the parameter list can have default values.

By default, you have to put quotes when you call a function or a procedure. It is possible to use the unquoted keyword to indicate that a function or a procedure does not require quotes for its arguments.

Like in Python, you can use keywords arguments :

Use the !include directive to include file in your diagram. Using URL, you can also include file from Internet/Intranet. Protected Internet resources can also be accessed, this is described in link::url-authentication[URL authentication].

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.

File List.iuml

The file List.iuml can be included in many diagrams, and any modification in this file will change all diagrams that include it.

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. The !0 notation denotes the first diagram.

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.

By default, a file can only be included once. You can use !include_many instead of !include if you want to include some file several times. Note that there is also a !include_once directive that raises an error if a file is included several times.

You can also use !startsub NAME and !endsub to indicate sections of text to include from other files using !includesub. For example:

file1.puml:

file1.puml would be rendered exactly as if it were:

However, this would also allow you to have another file2.puml like this:

file2.puml

This file would be rendered exactly as if:

Some functions are defined by default. Their name starts by %

You can use !log to add some log output when generating the diagram. This has no impact at all on the diagram itself. However, those logs are printed in the command line’s output stream. This could be useful for debug purpose.

You can use !dump_memory to dump the full content of the memory when generating the diagram. An optional string can be put after !dump_memory. This has no impact at all on the diagram itself. This could be useful for debug purpose.

You can put assertions in your diagram.

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:

You can specify the java property plantuml.include.path in the command line.

For example:

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.

You can dynamically invoke a procedure using the special %invoke_procedure() procedure. This procedure takes as first argument the name of the actual procedure to be called. The optional following arguments are copied to the called procedure.

For example, you can have:

For return functions, you can use the corresponding special function %call_user_func() :

Evaluation of $a + $b depending of type of $a or $b

You can extend the functionality of the current Preprocessing with link::preprocessing-json[JSON Preprocessing] features:

(See more details on link::preprocessing-json[Preprocessing-JSON page])

Use the !theme directive to change link::theme[the default theme of your diagram].

You will find more information link::theme[on the dedicated page].

The current preprocessor is an update from some legacy preprocessor.

Even if some legacy features are still supported with the actual preprocessor, you should not use them any more (they might be removed in some long term future).

Please contact us if you have any issues.

[Ref. QA-15374]