前処理

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では慣例に従い次のように定義します:

  • 整数型の 0false を意味します
  • それ以外の非nullの数値(1など)と、すべての文字列("1"、あるいは"0"でさえも)はtrueを意味します

[Ref. QA-9702]

真偽値型の演算と演算子 [&&, ||, ()]

真偽値判定では、次の演算子を使用できます:
  • 括弧 ()
  • and演算子&&
  • or演算子||

(ifの判定式の例を参照)

真偽値の組み込み関数 [%false(), %true(), %not(<exp>)]

利便性のため、次の組み込み関数が用意されています:

  • %false()
  • %true()
  • %not(<exp>)

[組み込み関数を参照]

条件分岐 [!if, !else, !elseif, !endif]

  • 条件部に式を記述することができます。
  • elseelseifを使用することもできます。

🎉 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ループ [!while, !endwhile]

!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]

プロシージャ [!procedure, !endprocedure]

  • プロシージャ名は$で開始する必要があります
  • 引数名は$で開始する必要があります
  • プロシージャから他のプロシージャを呼び出すことができます

例:

🎉 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関数 [!function, !endfunction]

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]

デフォルトでは、プロシージャや関数の文字列型引数はクォーテーション記号で囲む必要があります。 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

ファイルやURLのインクルード [!include, !include_many, !include_once]

!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ブロックを記述し、 インクルード時に!00はブロックの番号)を追加すると、特定のブロックをインクルードすることができます。!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, !endsub, !includesub]

!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_colorHSLuvを使用して色を反転します。 %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

ログ出力 [!log]

!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を使用すると、ダイアグラム生成中のメモリの全内容をダンプ出力することができます。!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

アサーション [!assert]

ダイアグラムにアサーションを追加できます。

🎉 Copied!
@startuml
Alice -> Bob : Hello
!assert %strpos("abcdef", "cd")==3 : "This always fails"
@enduml

カスタムライブラリの作成 [!import, !include]

複数のインクルードファイルを、一つの.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(), %call_user_func()]

特別な%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の型に依存して行われます。

🎉 Copied!
@startuml
title
<#LightBlue>|= |=  $a |=  $b |=  <U+0025>string($a + $b)|
<#LightGray>| type | str | str | str (concatenation) |
| example |= "a" |= "b" |= %string("a" + "b") |
<#LightGray>| type | str | int | str (concatenation) |
| ex.|= "a" |=  2  |= %string("a" + 2)   |
<#LightGray>| type | str | int | str (concatenation) |
| ex.|=  1  |= "b" |= %string(1 + "b")   |
<#LightGray>| type | bool | str | str (concatenation) |
| ex.|= <U+0025>true() |= "b" |= %string(%true() + "b") |
<#LightGray>| type | str | bool | str (concatenation) |
| ex.|= "a" |= <U+0025>false() |= %string("a" + %false()) |
<#LightGray>| type |  int  |  int | int (addition of int) |
| ex.|=  1  |=  2  |= %string(1 + 2)     |
<#LightGray>| type |  bool  |  int | int (addition) |
| ex.|= <U+0025>true() |= 2 |= %string(%true() + 2) |
<#LightGray>| type |  int  |  bool | int (addition) |
| ex.|=  1  |= <U+0025>false() |= %string(1 + %false()) |
<#LightGray>| type |  int  |  int | int (addition) |
| ex.|=  1  |=  <U+0025>intval("2")  |= %string(1 + %intval("2")) |
end title
@enduml

JSON前処理

JSON前処理機能によって、前処理機能を拡張できます:

  • JSON変数定義
  • JSONデータへのアクセス
  • JSON配列に対するループ

(詳細はJSON前処理のページを確認)

テーマのインクルード [!theme]

!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.


Privacy Policy      Advertise