PlantUMLAdvanced usageCommand line

コマンドライン

PlantUMLは、次のコマンドで実行することもできます： 

java -jar plantuml.jar file1 file2 file3

これを実行すると、file1、file2、file3から@startXYZを検索し、それぞれのダイアグラムについて .pngファイルを生成します。

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

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

これを実行すると、c:/directory1とc:/directory2ディレクトリにある、.c、.h、.cpp、.txt、.pu、.tex、.html、.htm、.javaファイルから、@startXYZと@endXYZを検索します。 This command will search for @startXYZ and @endXYZ into .txt, .tex, .java, .htm, .html, .c, .h, .cpp, .apt, .pu, .puml, .hpp or .hh files of the c:/directory1 and c:/directory2 directories.
WARNING
 This translation need to be updated. 
WARNING

ワイルドカード

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

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

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

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

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

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

除外するファイル

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

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

出力ディレクトリ

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

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

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

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

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

Types of Output File

Images for your diagrams can be exported in a variety of different formats. By default the format will be a PNG file but another type can be selected using the following extensions:

Param name Output format Comment
-tpng PNG Default
-tsvg SVG Further details can be found here
-teps EPS Further details can be found here
-teps:text EPS This option keeps text as text
-tpdf PDF Further details can be found here
-tvdx VDX Microsoft Visio Document
-txmi XMI Further details can be found here
-tscxml SCXML
-thtml HTML Alpha feature: do not use
-ttxt ATXT ASCII art. Further details can be found here
-tutxt UTXT ASCII art using Unicode characters
-tlatex LATEX Further details can be found here
-tlatex:nopreamble LATEX Contains no LaTeX preamble creating a document
-tbraille PNG Braille image

Example: 

java -jar plantuml.jar yourdiagram.txt -ttxt

設定ファイル

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

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

メタデータ

すべてのプリプロセス(include等)が完了すると、PlantUMLはダイアグラムのソースコードをencoded text形式に変換し、生成したPNGのメタデータに保存します。
  • -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のメタデータを取り出すことが可能です。
WARNING
 This translation need to be updated. 
WARNING

終了コード

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

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

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

Standard report [stdrpt]

Using the -stdrpt (standard report) option, you can change the format of the error output of your PlantUML scripts.

With this option, a different error output of your diagram is possible:
  • -stdrpt
  • -stdrpt:1
  • -stdrpt:2

[Ref. Issue#155 and QA-11805]

Examples, with the bad file file1.pu, where as is written aass: 

@startuml
participant "Famous Bob" aass Bob
@enduml

Without any option

java -jar plantuml.jar file1.pu

The error output is: 

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

-stdrpt option

java -jar plantuml.jar -stdrpt file1.pu

The error output is: 

file1.pu:2:error:Syntax Error?

-stdrpt:1 option

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

The error output is: 

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

-stdrpt:2 option (like -stdrpt)

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

The error output is: 

file1.pu:2:error:Syntax Error?

標準入出力

-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を参照してください。

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:
    -DVAR1=value                   Set a preprocessing variable as if '!define VAR1 value' were used
    -I/path/to/file                Include file as if '!include file' was used
    -I/path/to/*.puml              Include files with pattern
    -Sparam1=value                 Set a skin parameter as if 'skinparam param1 value' were used
    -author[s]                     Print information about PlantUML authors
    -charset xyz                   Use a specific charset (default is windows-1252).
                                   Use "utf-8" for extra international chars
    -checkmetadata                 Skip PNG files that don't need to be regenerated
    -checkonly                     Check the syntax of files without generating images
    -checkversion                  Check if a newer version is available for download
    -computeurl|-encodeurl         Compute the encoded URL of a PlantUML source file
    -config "file"                 Include a file before each diagram (same as -I ??)
    -cypher                        Cypher texts of diagrams so that you can share them
    -decodeurl                     Retrieve the PlantUML source from an encoded URL
    -disablestats                  Disable statistics computation (default)
    -duration                      Print the duration of complete diagrams processing
    -[exclude|x] pattern           Exclude files that match the provided pattern
    -enablestats                   Enable statistics computation
    -encodesprite 4|8|16[z] "file" Encode a sprite at gray level (z for compression) from an image
    -extractstdlib                 Extract PlantUML Standard Library into stdlib folder
    -failfast                      Stop processing as soon as a syntax error in diagram occurs
    -failfast2                     Do a first syntax check before processing files, to fail even faster
    -filename \"example.puml\"     Override %filename% variable
    -graphvizdot "exe"             Specify the graphviz "dot" executable.
                                   If needed, you can setup the environment variable GRAPHVIZ_DOT.
    -gui                           Run the graphical user interface
    -h[elp]                        Display this help message
    -htmlstats                     Output general statistics in file plantuml-stats.html
    -keepfiles                     Do NOT delete temporary files after processing
    -language                      Print the list of PlantUML keywords
    -loopstats                     Continuously print statistics about usage
    -metadata                      Retrieve PlantUML sources from PNG images
    -nbthread N                    Use N threads for processing
    -nbthread auto                 Use 4 threads for processing
    -o[utput] "dir"                Generate images in the specified directory
    -overwrite                     Allow overwriting of read-only files
    -p[ipe]                        Use stdin for PlantUML source and stdout for PNG/SVG/EPS generation
    -pattern                       Print the list of Regular Expression used by PlantUML
    -pipeNoStderr                  When used with -pipe, print errors to stdout (no image is generated in that case).
                                   The first line is "ERROR" and it respects -pipedelimitor
    -pipedelimitor "xyz"           When used with -pipe, append "xyz" after every image
    -pipeimageindex N              Generate only the N-th image when used with -pipe
    -pipemap                       Generate PNG map data of hyperlink rectangles, for use in HTML
    -preproc                       Output the preprocessed text of diagrams
    -printfonts                    Print fonts available on your system
    -progress                      Display a textual progress bar at the console
    -quiet                         Do NOT print error messages to the console
    -r[ecurse]                     Recurse through directories
    -realtimestats                 Generate statistics on the fly rather than at the end
    -splash                        Display a splash screen with some progress bar
    -stdlib                        Print standard library info
    -syntax                        Report any syntax error from standard input without generating images
    -teps                          Generate images using EPS format
    -testdot                       Test the installation of graphviz
    -thtml                         Generate HTML file for class diagram
    -tlatex                        Generate images using LaTeX/Tikz format
    -tlatex:nopreamble             Generate images using LaTeX/Tikz format without preamble
    -tpdf                          Generate images using PDF format
    -tpng                          Generate images using PNG format (default)
    -tscxml                        Generate SCXML file for state diagram
    -tsvg                          Generate images using SVG format
    -ttxt                          Generate images with ASCII art
    -tutxt                         Generate images with ASCII art using Unicode characters
    -tvdx                          Generate images using VDX format
    -txmi                          Generate XMI file for class diagram
    -v[erbose]                     Have log information
    -version                       Display information about PlantUML and Java versions
    -xmlstats                      Output general statistics in file plantuml-stats.xml