PlantUMLにはいくつかの前処理機能があり、それは
すべてのダイアグラムに対して利用可能です。
これらの機能は、特殊文字
#
がエクスクラメーションマーク
!
に置き換えられていることを除くと、
C言語のプリプロセッサに非常によく似ています。
これは必須ではありませんが、変数名を
$
で始めることを強く推奨します。
データの種類は3つあります。
- 整数(int)
- 文字列(str) - シングルクォートもしくはダブルクォートで囲みます
- JSON(JSON) - 波括弧で囲みます
(JSON変数の定義と使用方法については、
Preprocessing-JSONのページを参照してください)
関数の外側に作られた変数は
グローバルであり、関数内を含むどこからでもアクセスすることができます。このことを明示するために、変数定義に
global
というキーワードを付けることもできます。
🎉 Copied!
| @startuml
!$a = 42
!$ab = "foo1"
!$cd = "foo2"
!$ef = $ab + $cd
!$foo = { "name": "John", "age" : 30 }
Alice -> Bob : $a
Alice -> Bob : $ab
Alice -> Bob : $cd
Alice -> Bob : $ef
Alice -> Bob : Do you know **$foo.name** ?
@enduml
|
次の構文で、変数が未定義の場合のみ代入することができます:
!$a ?= "foo"
🎉 Copied!
| @startuml
Alice -> Bob : 1. **$name** should be empty
!$name ?= "Charlie"
Alice -> Bob : 2. **$name** should be Charlie
!$name = "David"
Alice -> Bob : 3. **$name** should be David
!$name ?= "Ethan"
Alice -> Bob : 4. **$name** should be David
@enduml
|
真偽値の表現方法 [0 is false]
本当の意味でのboolean型はありませんが、PlantUMLでは慣例に従い次のように定義します:
- 整数型の
0
は false
を意味します - それ以外の非nullの数値(
1
など)と、すべての文字列("1"
、あるいは"0"
でさえも)はtrue
を意味します
[Ref. QA-9702]真偽値型の演算と演算子 [&&, ||, ()]
真偽値判定では、次の演算子を使用できます:
(if
の判定式の例を参照)真偽値の組み込み関数 [%false(), %true(), %not(<exp>)]
利便性のため、次の組み込み関数が用意されています:
%false()
%true()
%not(<exp>)
[組み込み関数を参照]- 条件部に式を記述することができます。
- elseとelseifを使用することもできます。
🎉 Copied!
| @startuml
!$a = 10
!$ijk = "foo"
Alice -> Bob : A
!if ($ijk == "foo") && ($a+10>=4)
Alice -> Bob : yes
!else
Alice -> Bob : This should not appear
!endif
Alice -> Bob : B
@enduml
|
!while
と
!endwhile
キーワードを使用して繰り返しを記述できます。
Whileループ(アクティビティ図での例)
🎉 Copied!
| @startuml
!procedure $foo($arg)
:procedure start;
!while $arg!=0
!$i=3
#palegreen:arg=$arg;
!while $i!=0
:arg=$arg and i=$i;
!$i = $i - 1
!endwhile
!$arg = $arg - 1
!endwhile
:procedure end;
!endprocedure
start
$foo(2)
end
@enduml
|
[Adapted from QA-10838]Whileループ(マインドマップでの例)
🎉 Copied!
| @startmindmap
!procedure $foo($arg)
!while $arg!=0
!$i=3
**[#palegreen] arg = $arg
!while $i!=0
*** i = $i
!$i = $i - 1
!endwhile
!$arg = $arg - 1
!endwhile
!endprocedure
*:While
Loop;
$foo(2)
@endmindmap
|
Whileループ(コンポーネント図/配置図での例)
🎉 Copied!
| @startuml
!procedure $foo($arg)
!while $arg!=0
[Component $arg] as $arg
!$arg = $arg - 1
!endwhile
!endprocedure
$foo(4)
1->2
3-->4
@enduml
|
[Ref. QA-14088]- プロシージャ名は
$
で開始する必要があります - 引数名は
$
で開始する必要があります - プロシージャから他のプロシージャを呼び出すことができます
例:
🎉 Copied!
| @startuml
!procedure $msg($source, $destination)
$source --> $destination
!endprocedure
!procedure $init_class($name)
class $name {
$addCommonMethod()
}
!endprocedure
!procedure $addCommonMethod()
toString()
hashCode()
!endprocedure
$init_class("foo1")
$init_class("foo2")
$msg("foo1", "foo2")
@enduml
|
プロシージャ内で定義された変数は
ローカル変数になります。ローカル変数はプロシージャの終了時に破棄されます。
return関数は文字列を出力しません。 定義した関数は次の個所で呼び出すことができます:
- 変数定義、ダイアグラムのテキスト中で直接使用する
- 他のreturn関数から呼び出す
- プロシージャから呼び出す
- 関数名は
$
で開始する必要があります - 引数名は
$
で開始する必要があります
🎉 Copied!
| @startuml
!function $double($a)
!return $a + $a
!endfunction
Alice -> Bob : The double of 3 is $double(3)
@enduml
|
簡単な関数の定義は、一行で記述することができます:
🎉 Copied!
| @startuml
!function $double($a) !return $a + $a
Alice -> Bob : The double of 3 is $double(3)
Alice -> Bob : $double("This work also for strings.")
@enduml
|
プロシージャと同様に、デフォルトで変数はローカル変数になります(関数の終了時に破棄されます)。しかし、関数からグローバル変数にアクセスすることもできます。
local
キーワードを使用すると、同じ名前のグローバル変数が存在したとしてもローカル変数として定義することができます。
🎉 Copied!
| @startuml
!function $dummy()
!local $ijk = "local"
!return "Alice -> Bob : " + $ijk
!endfunction
!global $ijk = "foo"
Alice -> Bob : $ijk
$dummy()
Alice -> Bob : $ijk
@enduml
|
プロシージャとreturn関数では、引数のデフォルト値を定義することができます。
🎉 Copied!
| @startuml
!function $inc($value, $step=1)
!return $value + $step
!endfunction
Alice -> Bob : Just one more $inc(3)
Alice -> Bob : Add two to three : $inc(3, 2)
@enduml
|
引数リストの最後尾から連続した複数個の引数に、デフォルト値を設定することができます。
🎉 Copied!
| @startuml
!procedure defaulttest($x, $y="DefaultY", $z="DefaultZ")
note over Alice
x = $x
y = $y
z = $z
end note
!endprocedure
defaulttest(1, 2, 3)
defaulttest(1, 2)
defaulttest(1)
@enduml
|
デフォルトでは、プロシージャや関数の文字列型引数はクォーテーション記号で囲む必要があります。
unquoted
キーワードを使用すると、プロシージャや関数の引数をクォーテーション記号で囲まずに記述できるようになります。
🎉 Copied!
| @startuml
!unquoted function id($text1, $text2="FOO") !return $text1 + $text2
alice -> bob : id(aa)
alice -> bob : id(ab,cd)
@enduml
|
Pythonと同様の、キーワード引数を使用することができます:
🎉 Copied!
| @startuml
!unquoted procedure $element($alias, $description="", $label="", $technology="", $size=12, $colour="green")
rectangle $alias as "
<color:$colour><<$alias>></color>
==$label==
//<size:$size>[$technology]</size>//
$description"
!endprocedure
$element(myalias, "This description is %newline()on several lines", $size=10, $technology="Java")
@enduml
|
!include
を使用すると、ダイアグラムにファイルをインクルードすることができます。URLを使用してインターネット/イントラネット上のファイルをインクルードすることもできます。インターネット上の認証が必要なリソースにアクセスすることもできます。詳細は
URL認証機能を確認してください。
例えば、複数のダイアグラムに、まったく同じクラスが現れるような状況を考えてください。 クラスの定義を何度も記述するのではなく、 別のファイルに定義しておくことができます。
🎉 Copied!
| @startuml
interface List
List : int size()
List : void clear()
List <|.. ArrayList
@enduml
|
File List.iuml
interface List
List : int size()
List : void clear()
List.iuml
は、複数のダイアグラムにインクルードすることができます。 このファイルに変更があった場合、インクルード先のすべてのダイアグラムに変更が及びます。
インクルードされるファイルに複数の
@startuml/@enduml
ブロックを記述し、 インクルード時に
!0
(
0
はブロックの番号)を追加すると、特定のブロックをインクルードすることができます。
!0
は最初のブロックを表します。
例えば、
!include foo.txt!1
とすると、
foo.txt
に記述された2番目の
@startuml/@enduml
ブロックがインクルードされます。
@startuml(id=MY_OWN_ID)
という記法で、
@startuml/@enduml
ブロックにIDを付与することもできます。このブロックをインクルードするには、インクルード時に
!MY_OWN_ID
を追加し、
!include foo.txt!MY_OWN_ID
のようにします。
デフォルトでは、一つのファイルは一度だけインクルードできます。一つのファイルを複数回インクルードしたい場合は、
!include
の代わりに
!include_many
を使用します。
!include_once
ディレクティブを使用すると、ファイルが複数回インクルードされた場合にエラーを発生させることができます。
!startsub NAME
と
!endsub
を使用してテキストのセクションを作成し、他のファイルで
!includesub
によってインクルードすることができます。例:
file1.puml:
@startuml
A -> A : stuff1
!startsub BASIC
B -> B : stuff2
!endsub
C -> C : stuff3
!startsub BASIC
D -> D : stuff4
!endsub
@enduml
file1.puml は、次の記述と同じ結果になります:
@startuml
A -> A : stuff1
B -> B : stuff2
C -> C : stuff3
D -> D : stuff4
@enduml
一方で、これを利用して次のような file2.puml を作ることができます:
file2.puml
@startuml
title this contains only B and D
!includesub file1.puml!BASIC
@enduml
このファイルは、次の記述と同じ結果になります:
@startuml
title this contains only B and D
B -> B : stuff2
D -> D : stuff4
@enduml
デフォルトで定義された関数があります。関数名は
%
で始まります。
名称 | 説明 | 例 | 戻り値 |
%chr | 与えられたUnicode値に対応する文字を返します。 | %chr(65) | A |
%darken | 与えられた色を暗くした色を返します。第二引数に暗くする割合を指定します。 | %darken("red", 20) | #CC0000 |
%date | 現在日付を返します。オプションで日付のフォーマットを指定できます。 | %date("yyyy.MM.dd' at 'HH:mm") | 現在日時 |
%dec2hex | 10進数の数値(Int)に対する16進数文字列(String)を返します。 | %dec2hex(12) | c |
%dirpath | 現在のディレクトリパスを取得します。 | %dirpath() | 現在のパス |
%feature | ある機能が、現在実行中のPlantUMLのバージョンで利用できるかどうか確認します。 | %feature("theme") | true |
%false | 常にfalse を返します。 | %false() | false |
%file_exists | ファイルがローカルファイルシステムに存在するかどうか確認します。 | %file_exists("c:/foo/dummy.txt") | ファイルが存在する場合true |
%filename | 現在のファイル名を取得します。 | %filename() | 現在のファイル名 |
%function_exists | 関数が存在するかどうか確認します。 | %function_exists("$some_function") | 関数が定義されている場合true |
%get_variable_value | 変数の値を取得します。 | %get_variable_value("$my_variable") | 変数の値 |
%getenv | 環境変数の値を取得します。 | %getenv("OS") | 環境変数OS の値 |
%hex2dec | 16進数文字列(String)に対する10進数の数値(Int)を返します。 | %hex2dec("d") or %hex2dec(d) | 13 |
%hsl_color | HSL形式の色(%hsl_color(h, s, l) 、%hsl_color(h, s, l, a) )をRGBa形式に変換します。 | %hsl_color(120, 100, 50) | #00FF00 |
%intval | StringをIntに変換します。 | %intval("42") | 42 |
%is_dark | 色が暗い色かどうか判定します。 | %is_dark("#000000") | true |
%is_light | 色が明るい色かどうか判定します。 | %is_light("#000000") | false |
%lighten | 与えられた色を明るくした色を返します。第二引数に明るくする割合を指定します。 | %lighten("red", 20) | #CC3333 |
%loadJSON | ローカルファイルまたはURLから、JSONデータを読み込みます。 | %loadJSON("http://localhost:7778/management/health") | JSONデータ |
%lower | 文字列を小文字に変換します。 | %lower("Hello") | この例の場合hello |
%newline | 改行文字列を返します。 | %newline() | 改行文字列 |
%not | 真偽値の論理否定を返します。 | %not(2+2==4) | この例の場合false |
%reverse_color | RGBを使用して色を反転します。 | %reverse_color("#FF7700") | #0088FF |
%reverse_hsluv_color | HSLuvを使用して色を反転します。 | %reverse_hsluv_color("#FF7700") | #602800 |
%set_variable_value | グローバル変数に値を設定します。 | %set_variable_value("$my_variable", "some_value") | 空文字列 |
%size | 文字列またはJSON構造体のサイズを返します。 | %size("foo") | この例の場合3 |
%string | 文字列に変換します。 | %string(1 + 2) | この例の場合3 |
%strlen | 文字列の長さを返します。 | %strlen("foo") | この例の場合3 |
%strpos | 文字列を検索し、出現位置を返します。 | %strpos("abcdef", "ef") | 4 (ef の出現位置) |
%substr | 部分文字列を取り出します。2つまたは3つの引数を取ります。 | %substr("abcdef", 3, 2) | この例の場合"de" |
%true | 常にtrue を返します。 | %true() | true |
%upper | 文字列を大文字に変換します。 | %upper("Hello") | この例の場合HELLO |
%variable_exists | 変数が存在するかどうか確認します。 | %variable_exists("$my_variable") | 定義済みの変数が存在する場合true |
%version | 実行中のPlantUMLのバージョンを返します。 | %version() | 例:1.2020.8 |
|
%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 | |
%call_user_func()
| Invoke a return function by its name with given arguments. |
%call_user_func("bold", "Hello")
| Depends on the called function | |
%splitstr
| Split a string into an array based on a specified delimiter. |
%splitstr("abc~def~ghi", "~")
|
["abc", "def", "ghi"]
|
WARNING
This translation need to be updated. WARNING
!log
を使用すると、ダイアグラム生成時にログを出力することができます。これは、ダイアグラム自体にはまったく影響を与えません。その代わりに、コマンドラインの出力ストリームにログが出力されます。これはデバッグのために有用です。
🎉 Copied!
| @startuml
!function bold($text)
!$result = "<b>"+ $text +"</b>"
!log Calling bold function with $text. The result is $result
!return $result
!endfunction
Alice -> Bob : This is bold("bold")
Alice -> Bob : This is bold("a second call")
@enduml
|
!dump_memory
を使用すると、ダイアグラム生成中のメモリの全内容をダンプ出力することができます。
!dump_memory
の後に任意の文字列を追加することもできます。これは、ダイアグラム自体にはまったく影響を与えませんが、デバッグのために有用です。
🎉 Copied!
| @startuml
!function $inc($string)
!$val = %intval($string)
!log value is $val
!dump_memory
!return $val+1
!endfunction
Alice -> Bob : 4 $inc("3")
!unused = "foo"
!dump_memory EOF
@enduml
|
ダイアグラムにアサーションを追加できます。
🎉 Copied!
| @startuml
Alice -> Bob : Hello
!assert %strpos("abcdef", "cd")==3 : "This always fails"
@enduml
|
複数のインクルードファイルを、一つの.zipまたは.jarアーカイブにまとめることができます。 作成したzip/jarファイルは、
!import
ディレクティブを使用してダイアグラムにインポートすることができます。
ライブラリのインポート後、そのzip/jarファイルに含まれるファイルを
!include
することができます。
例:
@startuml
!import /path/to/customLibrary.zip
' この記述で、"customLibrary.zip"が検索パスに追加されます。
!include myFolder/myFile.iuml
' myFolder/myFile.iuml は、"customLibrary.zip"の中かローカルのファイルシステムに
' 存在していることが期待されます。
...
コマンドラインで、Javaプロパティの
plantuml.include.path
を使って検索パスを指定できます。
例:
java -Dplantuml.include.path="c:/mydir" -jar plantuml.jar atest1.txt
この-Dオプションは、-jarオプションより前に記述する必要があります。 -jarオプションの後に記述した-Dオプションは、PlantUMLプリプロセッサの定数定義に使用されます。
##
を使用して、マクロ引数に文字列を結合できます。
🎉 Copied!
| @startuml
!unquoted procedure COMP_TEXTGENCOMP(name)
[name] << Comp >>
interface Ifc << IfcType >> AS name##Ifc
name##Ifc - [name]
!endprocedure
COMP_TEXTGENCOMP(dummy)
@enduml
|
特別な
%invoke_procedure()
プロシージャを使用して、プロシージャを動的に呼び出すことができます。 このプロシージャは、最初の引数に実際に呼び出すプロシージャ名を取ります。それに続く残りの引数は、呼び出されるプロシージャの引数として渡されます。
例:
🎉 Copied!
| @startuml
!procedure $go()
Bob -> Alice : hello
!endprocedure
!$wrapper = "$go"
%invoke_procedure($wrapper)
@enduml
|
🎉 Copied!
| @startuml
!procedure $go($txt)
Bob -> Alice : $txt
!endprocedure
%invoke_procedure("$go", "hello from Bob...")
@enduml
|
return関数に対しては、
%call_user_func()
を使用します:
🎉 Copied!
| @startuml
!function bold($text)
!return "<b>"+ $text +"</b>"
!endfunction
Alice -> Bob : %call_user_func("bold", "Hello") there
@enduml
|
$a + $b
の評価は
$a
と
$b
の型に依存して行われます。
JSON前処理機能によって、前処理機能を拡張できます:
- JSON変数定義
- JSONデータへのアクセス
- JSON配列に対するループ
(詳細は
JSON前処理のページを確認)
!theme
ディレクティブを使用すると
ダイアグラムのデフォルトテーマを変更することができます。
🎉 Copied!
| @startuml
!theme spacelab
class Example {
Theme spacelab
}
@enduml
|
詳細は
テーマの説明を確認してください。
現行のプリプロセッサは、レガシーなプリプロセッサーからアップデートしたものです。
レガシーな機能の内いくつかは、現行のプリプロセッサでもサポートされていますが、今後はそれらを使わないようにしてください(将来的に削除される可能性があります)。
!define
と!definelong
は使用しないでください。代わりに!function`、
!procedure?code??もしくは変数定義を使用します。 !define
はreturn!function
に置き換えてください。!definelong
は!procedure
に置き換えてください。
!include
で複数のインクルードが可能になったので、!include_many
を使う必要はありません。!include
はURLを受け取れるようになったので!includeurl
を使う必要はありません。%date%
などのいくつかの機能は、組み込みの関数(%date()
など)に置き換えられました。- レガシーな
!definelong
マクロを引数無しで呼ぶ場合、必ず括弧を使用する必要があります.my_own_definelong()
ではなくmy_own_definelong
のように括弧を省略してしまうと、新しいプリプロセッサでは認識されません。
Please contact us if you have any issues.
🎉 Copied!
| @startmindmap
!$list = %splitstr("abc~def~ghi", "~")
* root
!foreach $item in $list
** $item
!endfor
@endmindmap
|
Similar to:
🎉 Copied!
| @startmindmap
* root
!foreach $item in ["abc", "def", "ghi"]
** $item
!endfor
@endmindmap
|
[Ref. QA-15374] You can use the
%get_all_theme()
builtin function to retreive a JSON array of all PlantUML
theme.
🎉 Copied!
| @startjson
%get_all_theme()
@endjson
|
[from version 1.2024.4]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.
🎉 Copied!
| @startjson
%get_all_stdlib()
@endjson
|
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.
🎉 Copied!
| @startjson
%get_all_stdlib(detailed)
@endjson
|
[from version 1.2024.4] 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 |
🎉 Copied!
| @startcreole
| Nb param. | Input | Output |
| 0 | <U+0025>random() | %random() |
| 1 | <U+0025>random(5) | %random(5) |
| 2 | <U+0025>random(7, 15) | %random(7, 15) |
@endcreole
|
[from version 1.2024.2]