Edit in DokuwikiEdit in AsciidocEdit in Markdown

コマンドライン

コマンドラインを使って PlantUML を実行することができます。 (他の様々なツールやワークフローから PlantUML を実行する方法については、実行を参照してください)。

最も基本的な実行方法は、次のとおりです。

java -jar plantuml.jar file1 file2 file3

これは、@startXYZ をfile1 、file2 、file3 に探します。各ダイアグラムについて、.png ファイルが作成されます。

ディレクトリ全体を処理する場合は、次のようにします。

java -jar plantuml.jar "c:/directory1" "c:/directory2"

このコマンドは、@startXYZ と@endXYZ を.txt,.tex,.java,.htm,.html,.c,.h,.cpp,.apt,.pu,.puml,.hpp,.hh または.md ディレクトリのc:/directory1 とc:/directory2 ファイルを検索します。

Dockerイメージは、Github PackagesやDocker Hubで公開されています。

docker run ghcr.io/plantuml/plantuml

Edit in DokuwikiEdit in AsciidocEdit in Markdown

ワイルドカード

次のワイルドカード文字を使用することもできます：

• 任意の1文字：?
• 0文字以上の任意の文字：*
• 0文字以上の任意の(/または\を含む)文字：**

dummyから始まるディレクトリのすべての.cppファイルを処理する場合は次のようにします：

java -jar plantuml.jar "dummy*/*.cpp"

dummyから始まるディレクトリと、そのサブディレクトリのすべての.cppファイルを処理する場合は次のようにします：

java -jar plantuml.jar "dummy*/**.cpp"

Edit in DokuwikiEdit in AsciidocEdit in Markdown

除外するファイル

-xオプションを使用して、特定のファイルを処理の対象から除外できます：

java -jar plantuml.jar -x "**/common/**" -x "**/test/Test*" "dummy*/**/*.cpp"

Edit in DokuwikiEdit in AsciidocEdit in Markdown

出力ディレクトリ

-oオプションを使用して、すべての画像ファイルが出力されるディレクトリを指定することができます：

java -jar plantuml.jar -o "c:/outputPng" "c:/directory2"

複数のディレクトリを再帰的に処理する場合、出力ディレクトリを絶対パスで指定するか相対パスで指定するかで結果が異なります：

• 絶対パスで指定すると、すべての画像ファイルは特定の一つのディレクトリに出力されます。

• 相対パスで指定すると、画像ファイルは入力ファイルからの相対パスのディレクトリに出力されます。カレントディレクトリからの相対パスではありません。（注意: .から始まるパスを指定したとしても同様です）。PlantUMLが複数のディレクトリのファイルを処理する場合、計算された出力ディレクトリのそれぞれに対応するディレクトリ構造が作成されます。

Edit in DokuwikiEdit in AsciidocEdit in Markdown

出力ファイル形式

ダイアグラムの画像は様々な形式で出力することができます。デフォルトはPNGファイルですが、以下の形式を選択することができます：

パラメータ名	短いパラメータ名	出力形式	コメント
-tpng	-png	PNG	デフォルト
-tsvg	-svg	SVG	詳細はこちら
-teps	-eps	EPS	詳細はこちら
-teps:text	-eps:text	EPS	このオプションはテキストをテキストのまま保持します
-tpdf	-pdf	PDF	詳細はこちら
-tvdx	-vdx	VDX	Microsoft Visio Document
-txmi	-xmi	XMI	詳細はこちら
-tscxml	-scxml	SCXML
-thtml	-html	HTML	アルファ版機能です。使用しないでください。
-ttxt	-txt	ATXT	アスキーアート。詳細はこちら
-tutxt	-utxt	UTXT	Unicode文字を使用したアスキーアート
-tlatex	-latex	LATEX	詳細はこちら
-tlatex:nopreamble	-latex:nopreamble	LATEX	ドキュメントを作成するためのLaTeXプリアンブルを含みません
-tbraille	-braille	PNG	点字画像

例:

java -jar plantuml.jar yourdiagram.txt -ttxt

WARNING

 This translation need to be updated. 

WARNING

Edit in DokuwikiEdit in AsciidocEdit in Markdown

設定ファイル

すべてのダイアグラムの前にインクルードされる設定ファイルを指定することもできます：

java -jar plantuml.jar -config "./config.cfg" dir1

Edit in DokuwikiEdit in AsciidocEdit in Markdown

メタデータ

すべてのプリプロセス(include等)が完了すると、PlantUMLはダイアグラムのソースコードをencoded text形式に変換し、生成したPNGのメタデータに保存します。

• 生成するPNGのメタデータにダイアグラムのソースコードを保存したくない場合は、生成時に-nometadataオプションを指定します。この機能が無効化され、生成されたPNG/SVGにメタデータはエクスポートされなくなります。
• -metadataオプションを使用して、このソースコードを取り出すことができます。つまり、PNGは「編集可能」と言っても過言ではありません。例えば、プラグインをインストールすることのできない企業のwikiなどにアップロードしたダイアグラムを、将来、誰かがメタデータを利用することで更新して再アップロードすることが可能です。また、ダイアグラムは、それ単体で利用可能です。
• -checkmetadataオプションを使用すると、対象のPNGが同一のソースから生成されたものかどうかをチェックします。もし変更点がなければ、PNGの再生成を行わないので、処理時間をまるごと節約することができます。これにより、PlantUMLをフォルダ全体や-recursiveオプションで再帰的に実行する場合に、インクリメンタルな動作が可能になります。

一見、魔法のようですが、これは巧みなエンジニアリングの産物です :-)

例：

  java -jar plantuml.jar -metadata diagram.png > diagram.puml

残念ながら、このオプションはローカルファイルに対してのみ利用可能です。-pipeと共に利用することはできません。例えばcurlでURLからフェッチしたPNGをPlantUMLに流し込むようなことはできません。

しかし、PlantUMLサーバにも同様の機能があり、こちらを利用すると、URLから取得したPNGのメタデータを取り出すことが可能です。

Edit in DokuwikiEdit in AsciidocEdit in Markdown

終了コード

ダイアグラムで何らかのエラーが発生すると、コマンドはエラーを表す(-1)を終了コードとして返します。しかし、一部のダイアグラムでエラーが発生したとしても、他のすべてのダイアグラムの生成は行われます。これは、大きなプロジェクトでは、時間の無駄になってしまうかもしれません。

-failfastフラグにより、この振る舞いを変更し、一つでもエラーが発生したら即座にダイアグラムの生成を停止するように設定できます。この場合、一部のダイアグラムのみ生成され、他は生成されません。

また、-failfast2フラグを設定すると、最初にチェックのみを実行します。もし、エラーが存在すれば、ダイアグラムは一つも生成されません。エラーが発生するケースでは、-failfastよりも-failfast2の方が高速です。巨大なプロジェクトでは、こちらが役に立つかもしれません。

Edit in DokuwikiEdit in AsciidocEdit in Markdown

Standard report [stdrpt]

-stdrpt (standard report) オプションを使うと、PlantUMLスクリプトのエラー出力の形式を変更することができます。

このオプションでは、ダイアグラムに対する異なるエラー出力を選択できます：

• -stdrpt
• -stdrpt:1
• -stdrpt:2

[Ref. Issue#155 and QA-11805]

例として、asと書くべきところをaassとした不正なファイルfile1.puを用意します:

@startuml
participant "Famous Bob" aass Bob
@enduml

オプションを指定しない場合

java -jar plantuml.jar file1.pu

次のエラーが出力されます:

Error line 2 in file: file1.pu
Some diagram description contains errors

-stdrptを指定した場合

java -jar plantuml.jar -stdrpt file1.pu

次のエラーが出力されます:

file1.pu:2:error:Syntax Error?

-stdrpt:1を指定した場合

java -jar plantuml.jar -stdrpt:1 file1.pu

次のエラーが出力されます:

protocolVersion=1
status=ERROR
lineNumber=2
label=Syntax Error?
Error line 2 in file: file1.pu
Some diagram description contains errors

-stdrpt:2を指定した場合(-stdrptと同様)

java -jar plantuml.jar -stdrpt:2 file1.pu

次のエラーが出力されます:

file1.pu:2:error:Syntax Error?

WARNING

 This translation need to be updated. 

WARNING

Edit in DokuwikiEdit in AsciidocEdit in Markdown

標準入出力

-pipeオプションを使用すると、スクリプト中でPlantUMLを簡単に使用することができます。

このオプションを指定した場合、ダイアグラムの記述は標準入力を通して受け取り、PNGファイルは標準出力に生成されます。ローカルファイルシステムにファイルは書き込まれません。

例：

cat somefile.puml | java -jar plantuml.jar -pipe > somefile.png

-pipemapオプションを使用すると、HTMLで使用するためのPNGマップデータ(ハイパーリンクの矩形)が出力されます。例：

cat somefile.puml | java -jar plantuml.jar -pipemap > somefile.map

mapファイルは次のような内容です：

<map id="plantuml_map" name="plantuml_map">
<area shape="rect" id="id1" href="http://plantuml.com" title="http://plantuml.com"
      alt="" coords="1,8,88,44"/>
</map>

注意: 一つのストリームに複数のPNGを多重化する場合(pumlファイルに複数のダイアグラムを含む場合)や、エラーハンドリングを正しく実装するには、-pipedelimitorと-pipeNoStderrを参照してください。

Edit in DokuwikiEdit in AsciidocEdit in Markdown

Help

次のコマンドで、ヘルプメッセージを表示できます：

java -jar plantuml.jar -help

内容は以下の通りです：

Usage: java -jar plantuml.jar [options] -gui
        (to execute the GUI)
    or java -jar plantuml.jar [options] [file/dir] [file/dir] [file/dir]
        (to process files or directories)

You can use the following wildcards in files/dirs:
        *       means any characters but '\'
        ?       one and only one character but '\'
        **      means any characters (used to recurse through directories)

where options include:
    -darkmode           To use dark mode for diagrams
    -gui                To run the graphical user interface
    -tpng               To generate images using PNG format (default)
    -tsvg               To generate images using SVG format
    -teps               To generate images using EPS format
    -tpdf               To generate images using PDF format
    -tvdx               To generate images using VDX format
    -txmi               To generate XMI file for class diagram
    -tscxml             To generate SCXML file for state diagram
    -thtml              To generate HTML file for class diagram
    -ttxt               To generate images with ASCII art
    -tutxt              To generate images with ASCII art using Unicode characters
    -tlatex             To generate images using LaTeX/Tikz format
    -tlatex:nopreamble  To generate images using LaTeX/Tikz format without preamble
    -o[utput] "dir"     To generate images in the specified directory
    -DVAR1=value        To set a preprocessing variable as if '!define VAR1 value' were used
    -Sparam1=value      To set a skin parameter as if 'skinparam param1 value' were used
    -Ppragma1=value     To set pragma as if '!pragma pragma1 value' were used
    -I\path\to\file     To include file as if '!include file' were used
    -I\path\to\*.puml   To include files with pattern
    -theme xxx          To use a specific theme
    -charset xxx        To use a specific charset (default is windows-1251)
    -e[x]clude pattern  To exclude files that match the provided pattern
    -metadata           To retrieve PlantUML sources from PNG images
    -nometadata         To NOT export metadata in PNG/SVG generated files
    -checkmetadata              Skip PNG files that don't need to be regenerated
    -version            To display information about PlantUML and Java versions
    -v[erbose]          To have log information
    -quiet              To NOT print error message into the console
    -debugsvek          To generate intermediate svek files
    -h[elp]             To display this help message
    -testdot            To test the installation of graphviz
    -graphvizdot "exe"  To specify dot executable
    -p[ipe]             To use stdin for PlantUML source and stdout for PNG/SVG/EPS generation
    -encodesprite 4|8|16[z] "file"      To encode a sprite at gray level (z for compression) from an image
    -computeurl|-encodeurl      To compute the encoded URL of a PlantUML source file
    -decodeurl          To retrieve the PlantUML source from an encoded URL
    -syntax             To report any syntax error from standard input without generating images
    -language           To print the list of PlantUML keywords
    -checkonly          To check the syntax of files without generating images
    -failfast           To stop processing as soon as a syntax error in diagram occurs
    -failfast2          To do a first syntax check before processing files, to fail even faster
    -noerror            To skip images when error in diagrams
    -duration           To print the duration of complete diagrams processing
    -nbthread N         To use (N) threads for processing
    -nbthread auto      To use 4 threads for processing
    -timeout N          Processing timeout in (N) seconds. Defaults to 15 minutes (900 seconds).
    -author[s]          To print information about PlantUML authors
    -overwrite          To allow to overwrite read only files
    -printfonts         To print fonts available on your system
    -enablestats        To enable statistics computation
    -disablestats       To disable statistics computation (default)
    -htmlstats          To output general statistics in file plantuml-stats.html
    -xmlstats           To output general statistics in file plantuml-stats.xml
    -realtimestats      To generate statistics on the fly rather than at the end
    -loopstats          To continuously print statistics about usage
    -splash             To display a splash screen with some progress bar
    -progress           To display a textual progress bar in console
    -pipeimageindex N   To generate the Nth image with pipe option
    -stdlib             To print standard library info
    -extractstdlib      To extract PlantUML Standard Library into stdlib folder
    -filedir xxx        To behave as if the PlantUML source is in this dir (only affects '-pipe' and PicoWeb 'POST /render')
    -filename "example.puml"    To override %filename% variable
    -preproc            To output preprocessor text of diagrams
    -cypher             To cypher texts of diagrams so that you can share them
    -picoweb            To start internal HTTP Server. See https://plantuml.com/picoweb

If needed, you can setup the environment variable GRAPHVIZ_DOT.