Sequenz Anwendungsfall Klasse Aktivität Komponente Zustand Objekt Einsatz Zeitverlauf Regex Network Wireframe Archimate Gantt MindMap WBS EBNF JSON YAML
PlantUML Language specification Preprocessing

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Preprocessing

Einige Preprocessing-Funktionen sind in PlantUML enthalten und für alle Diagramme verfügbar.

Diese Funktionalitäten sind sehr ähnlich wie der C-Sprache Preprozessor, mit dem Unterschied, dass das spezielle Zeichen # durch das Ausrufezeichen ! ersetzt wurde.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Variablendefinition [=, ?=]

Obwohl dies nicht verpflichtend ist, empfehlen wir dringend, dass Variablennamen mit einem $ beginnen.

Es gibt drei Arten von Daten: (Für die Definition und Verwendung von JSON-Variablen, siehe mehr Details auf der Preprocessing-JSON Seite)

Variablen, die außerhalb von Funktionen erstellt werden, sind global, das heißt, Sie können von überall darauf zugreifen (einschließlich aus Funktionen). Dies können Sie durch Verwendung des optionalen Schlüsselworts global bei der Definition einer Variablen betonen.

Sie können auch einer Variablen einen Wert zuweisen, nur wenn sie noch nicht definiert ist, mit der Syntax: !$a ?= "foo"

WARNING
 This translation need to be updated. 
WARNING

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Boolescher Ausdruck

Boolesche Darstellung [0 ist false]

Es gibt keinen echten Booleschen Typ, aber PlantUML verwendet diese Integer-Konvention:

[Ref. QA-9702]

Boolesche Operation und Operator [&&, ||, ()]

Sie können boolesche Ausdrücke in Tests verwenden, mit:

(Siehe nächstes Beispiel innerhalb des if Tests.)

Boolesche eingebaute Funktionen [%false(), %true(), %not(<exp>)]

Zur Vereinfachung können Sie diese booleschen eingebauten Funktionen verwenden:

[Siehe auch Eingebaute Funktionen]

[Ref. PR-1873]
WARNING
 This translation need to be updated. 
WARNING

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Bedingungen [!if, !else, !elseif, !endif]

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Wiederholschleife [!while, !endwhile]

Sie können die Schlüsselwörter !while und !endwhile verwenden, um Wiederholschleifen zu erstellen.

Wiederholschleife (im Aktivitätsdiagramm)

[Angepasst von QA-10838]

Wiederholschleife (im Mindmap-Diagramm)

Wiederholschleife (im Komponenten-/Deployment-Diagramm)

[Ref. QA-14088]

WARNING
 This translation need to be updated. 
WARNING

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Prozedur [!procedure, !endprocedure]

Beispiel:

Variablen, die in Prozeduren definiert werden, sind lokal. Das bedeutet, dass die Variable zerstört wird, wenn die Prozedur endet.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Rückgabefunktion [!function, !endfunction]

Eine Rückgabefunktion gibt keinen Text aus. Sie definiert lediglich eine Funktion, die Sie aufrufen können:

Es ist möglich, einfache Funktionsdefinitionen in einer Zeile zu verkürzen:

Wie in einer Prozedur (void-Funktion) sind Variablen standardmäßig lokal (sie werden zerstört, wenn die Funktion beendet wird). Sie können jedoch auf globale Variablen aus der Funktion zugreifen. Sie können jedoch das Schlüsselwort local verwenden, um eine lokale Variable zu erstellen, falls bereits eine globale Variable mit demselben Namen existiert.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Standardwert für Argumente

Sowohl in Prozeduren als auch in Rückgabefunktionen können Sie Standardwerte für Argumente definieren.

Nur Argumente am Ende der Parameterliste können Standardwerte haben.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Unzitierte Prozedur oder Funktion [!unquoted]

Standardmäßig müssen Sie Anführungszeichen setzen, wenn Sie eine Funktion oder eine Prozedur aufrufen. Es ist möglich, das Schlüsselwort unquoted zu verwenden, um anzugeben, dass eine Funktion oder eine Prozedur keine Anführungszeichen für ihre Argumente benötigt.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Schlüsselwortargumente

Wie in Python können Sie Schlüsselwortargumente verwenden:

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Dateien oder URLs einbinden [!include, !includemany, !includeonce]

Verwenden Sie die Direktive !include, um Dateien in Ihr Diagramm einzubinden. Mit URLs können Sie auch Dateien aus dem Internet/Intranet einbinden. Geschützte Internetressourcen können ebenfalls zugegriffen werden, dies wird in URL-Authentifizierung beschrieben.

Stellen Sie sich vor, Sie haben dieselbe Klasse, die in vielen Diagrammen erscheint. Anstatt die Beschreibung dieser Klasse zu duplizieren, können Sie eine Datei definieren, die die Beschreibung enthält.

Datei List.iuml 

interface List
List : int size()
List : void clear()

Die Datei List.iuml kann in vielen Diagrammen eingebunden werden, und jede Änderung in dieser Datei wird alle Diagramme ändern, die sie einbinden.

Sie können auch mehrere @startuml/@enduml Textblöcke in einer eingebundenen Datei haben und dann angeben, welchen Block Sie einbinden möchten, indem Sie !0 hinzufügen, wobei 0 die Blocknummer ist. Die Notation !0 bezeichnet das erste Diagramm.

Zum Beispiel, wenn Sie !include foo.txt!1 verwenden, wird der zweite @startuml/@enduml Block innerhalb von foo.txt eingebunden.

Sie können auch einer bestimmten @startuml/@enduml Textblock in einer eingebundenen Datei eine ID geben, indem Sie die Syntax @startuml(id=MY_OWN_ID) verwenden und dann den Block hinzufügen, indem Sie !MY_OWN_ID beim Einbinden der Datei hinzufügen, also etwas wie !include foo.txt!MY_OWN_ID verwenden.

Standardmäßig kann eine Datei nur einmal eingebunden werden. Sie können !include_many anstelle von !include verwenden, wenn Sie eine Datei mehrmals einbinden möchten. Beachten Sie, dass es auch eine Direktive !include_once gibt, die einen Fehler auslöst, wenn eine Datei mehrmals eingebunden wird.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Including Subpart [!startsub, !endsub, !includesub]

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

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Builtin functions [%]

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

Name Description Example Return
%boolval Convert a value (String, Integer, JSON value) to boolean value %boolval("true") 1
%breakline Return a newline in the PlantUML source code. See more documention on the newline page %breakline() a newline in the PlantUML source code
%call_user_func Invoke a return function by its name with given arguments. %call_user_func("bold", "Hello") Depends on the called function
%chr Return a character from a give Unicode value %chr(65) A
%darken Return a darken color of a given color with some ratio %darken("red", 20) #CC0000
%date Retrieve current date. You can provide an optional format for the date %date("yyyy.MM.dd' at 'HH:mm") current date
You can provide another optional time (on epoch format) %date("YYYY-MM-dd", %now() + 1*24*3600) tomorrow date
%dec2hex Return the hexadecimal string (String) of a decimal value (Int) %dec2hex(12) c
%dirpath Retrieve current dirpath %dirpath() current path
%feature Check if some feature is available in the current PlantUML running version %feature("theme") true
%false Return always false %false() false
%file_exists Check if a file exists on the local filesystem %file_exists("c:/foo/dummy.txt") true if the file exists
%filename Retrieve current filename %filename() current filename
%function_exists Check if a function exists %function_exists("$some_function") true if the function has been defined
%get_all_theme Retreive a JSON Array of all PlantUML theme %get_all_theme() ["_none_", "amiga", ..., "vibrant"]
%get_all_stdlib Retreive a JSON Array of all PlantUML stdlib names %get_all_stdlib() ["archimate", "aws", ..., "tupadr3"]
%get_all_stdlib Retreive a JSON Object of all PlantUML stdlib information %get_all_stdlib(detailed) a JSON Object with stdlib information
%get_variable_value Retrieve some variable value %get_variable_value("$my_variable") the value of the variable
%getenv Retrieve environment variable value %getenv("OS") the value of OS variable
%hex2dec Return the decimal value (Int) of a hexadecimal string (String) %hex2dec("d") or %hex2dec(d) 13
%hsl_color Return the RGBa color from a HSL color %hsl_color(h, s, l) or %hsl_color(h, s, l, a) %hsl_color(120, 100, 50) #00FF00
%intval Convert a String to Int %intval("42") 42
%invoke_procedure Dynamically invoke a procedure by its name, passing optional arguments to the called procedure. %invoke_procedure("$go", "hello from Bob...") Depends on the invoked procedure
%is_dark Check if a color is a dark one %is_dark("#000000") true
%is_light Check if a color is a light one %is_light("#000000") false
%lighten Return a lighten color of a given color with some ratio %lighten("red", 20) #CC3333
%load_json Load JSON data from local file or external URL %load_json("http://localhost:7778/management/health") JSON data
%lower Return a lowercase string %lower("Hello") hello in that example
%mod Return the remainder of division of two integers (modulo division) %mod(10, 3) 1
%n Return a newline in rendered text, shortcut to %newline . See more documention on the newline page %n() a newline
%newline Return a newline in rendered text, similar to %n . See more documention on the newline page %newline() a newline
%not Return the logical negation of an expression %not(2+2==4) false in that example
%now Return the current epoch time %now() 1685547132 in that example (when updating the doc.)
%ord Return a Unicode value from a given character %ord("A") 65
%lighten Return a lighten color of a given color with some ratio %lighten("red", 20) #CC3333
%random() Return randomly the integer 0 or 1 %random() 0 or 1
%random(n) Return randomly an interger between 0 and n - 1 %random(5) 3
%random(min, max) Return randomly an interger between min and max - 1 %random(7, 15) 13
%reverse_color Reverse a color using RGB %reverse_color("#FF7700") #0088FF
%reverse_hsluv_color Reverse a color using HSLuv %reverse_hsluv_color("#FF7700") #602800
%set_variable_value Set a global variable %set_variable_value("$my_variable", "some_value") an empty string
%size Return the size of any string or JSON structure %size("foo") 3 in the example
%splitstr Split a string into an array based on a specified delimiter. %splitstr("abc~def~ghi", "~") ["abc", "def", "ghi"]
%splitstr_regex Split a string into an array based on a specified REGEX. %splitstr_regex("AbcDefGhi", "(?=[A-Z])") ["Abc", "Def", "Ghi"]
%string Convert an expression to String %string(1 + 2) 3 in the example
%strlen Calculate the length of a String %strlen("foo") 3 in the example
%strpos Search a substring in a string %strpos("abcdef", "ef") 4 (position of ef)
%substr Extract a substring. Takes 2 or 3 arguments %substr("abcdef", 3, 2) "de" in the example
%true Return always true %true() true
%upper Return an uppercase string %upper("Hello") HELLO in that example
%variable_exists Check if a variable exists %variable_exists("$my_variable") true if the variable has been defined exists
%version Return PlantUML current version %version() 1.2020.8 for example

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Logging [!log]

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.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Memory dump [!dump_memory]

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.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Assertion [!assert]

You can put assertions in your diagram.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Building custom library [!import, !include]

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

...

Edit in DokuwikiEdit in AsciidocEdit in Markdown
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.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Argument concatenation [##]

It is possible to append text to a macro argument using the ## syntax.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Dynamic invocation [%invoke_procedure(), %call_user_func()]

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() :

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Evaluation of addition depending of data types [+]

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

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Preprocessing JSON

You can extend the functionality of the current Preprocessing with JSON Preprocessing features:

(See more details on Preprocessing-JSON page)

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Including theme [!theme]

Use the !theme directive to change the default theme of your diagram.

You will find more information on the dedicated page.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Migration notes

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.

Edit in DokuwikiEdit in AsciidocEdit in Markdown
%splitstr builtin function

Similar to:

[Ref. QA-15374]

Edit in DokuwikiEdit in AsciidocEdit in Markdown
%splitstr_regex builtin function

Similar to:

[Ref. QA-18827]

Edit in DokuwikiEdit in AsciidocEdit in Markdown
%get_all_theme builtin function

You can use the %get_all_theme() builtin function to retreive a JSON array of all PlantUML theme.

[from version 1.2024.4]

Edit in DokuwikiEdit in AsciidocEdit in Markdown
%get_all_stdlib builtin function

Compact version (only standard library name)

You can use the %get_all_stdlib() builtin function to retreive a JSON array of all PlantUML stdlib names.

Detailed version (with version and source)

With whatever parameter, you can use %get_all_stdlib(detailed) to retreive a JSON object of all PlantUML stdlib.

[from version 1.2024.4]

Edit in DokuwikiEdit in AsciidocEdit in Markdown
%random builtin function

You can use the %random builtin function to retreive a random integer.

Nb param. Input Output
0 %random() returns 0 or 1
1 %random(n) returns an interger between 0 and n - 1
2 %random(min, max) returns an interger between min and max - 1

[from version 1.2024.2]

Edit in DokuwikiEdit in AsciidocEdit in Markdown
%boolval builtin function

You can use the %boolval builtin function to manage boolean value.

[Ref. PR-1873, from version 1.2024.7]

Edit in DokuwikiEdit in AsciidocEdit in Markdown
Escape function

Some character are specials, then we can escape them with some escape functions:

Escape function Output
%dollar() $
%percent() %
%backslash() \

[Ref. QA-19607]