Multilingual Wiki Documentation

You are currently using syntax.
In an attempt to improve PlantUML documentation...
Please do not use this website for your own diagrams.
You can click here and use the online server here for your own documentation.

Wiki Toc    View page history    Add new chapter    Reorder page    Raw


コマンドライン

Command line

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

java -jar plantuml.jar file1 file2 file3

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

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

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

これを実行すると、c:/directory1c:/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

You can run PlantUML using the command line. (See running for ways to run PlantUML from various other tools and workflows).

The most basic way to run it is:

java -jar plantuml.jar file1 file2 file3

This will look for @startXYZ into file1, file2 and file3. For each diagram, a .png file will be created.

For processing a whole directory, you can use:

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

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.

ワイルドカード

Wildcards

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

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

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

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

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

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

You can also use wildcards :

  • For a single character, use ?
  • For zero or more characters, use *
  • For zero or more characters, (including / or \), use a double **

So to process any .cpp files in all directories starting by dummy :

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

And to process any .cpp files in all directories starting by dummy, and theirs subdirectories :

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

除外するファイル

Excluded files

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

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

You can exlude some files from the process using the -x option:

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

出力ディレクトリ

Output Directory

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

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

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

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

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

You can specify an output directory for all images using the -o switch:

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

If you recurse into several directory, there is a slight difference if you provide an absolute or a relative path for this output directory:

  • An absolute path will ensure that all images are output to a single, specific, directory.

  • If you provide a relative path then the images is placed in that directory relative to the location of the input file, not the current directory (note: this applies even if the path begins with a .). When Plantuml processes files from multiple directores then the corresponding directory structure is created under the computed output directory.

出力ファイル形式

Types of Output File

ダイアグラムの画像は様々な形式で出力することができます。デフォルトは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

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 Short param name Output format Comment
-tpng -png PNG Default
-tsvg -svg SVG Further details can be found here
-teps -eps EPS Further details can be found here
-teps:text -eps:text EPS This option keeps text as text
-tpdf -pdf PDF Further details can be found here
-tvdx -vdx VDX Microsoft Visio Document
-txmi -xmi XMI Further details can be found here
-tscxml -scxml SCXML
-thtml -html HTML Alpha feature: do not use
-ttxt -txt ATXT ASCII art. Further details can be found here
-tutxt -utxt UTXT ASCII art using Unicode characters
-tlatex -latex LATEX Further details can be found here
-tlatex:nopreamble -latex:nopreamble LATEX Contains no LaTeX preamble creating a document
-tbraille -braille PNG Braille image

Example:

java -jar plantuml.jar yourdiagram.txt -ttxt

設定ファイル

Configuration File

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

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

You can also provide a configuration file which will be included before each diagram:

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

メタデータ

Metadata

すべてのプリプロセス(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のメタデータを取り出すことが可能です。

After all preprocessing (includes etc), PlantUML saves the diagram's source code in the generated PNG Metadata in the form of encoded text.
  • If you does not want plantuml to save the diagram's source code in the generated PNG Metadata, you can during generation use the option -nometadata to disable this functionality (To NOT export metadata in PNG/SVG generated files).
  • It is possible to retrieve this source with the -metadata option. This means that the PNG is almost "editable": you can post it on a corporate wiki where you cannot install plugins, and someone in the future can update the diagram by getting the metadata, editing and re-uploading again. Also, the diagram is stand-alone.
  • Conversely, the -checkmetadata option checks whether the target PNG has the same source and if there are no changes, doesn't regenerate the PNG, thus saving all processing time. This allows you to run PlantUML on a whole folder (or tree with the -recursive option) incrementally.

Sounds like magic! No, merely clever engineering :-)

Example:

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

Unfortunately this option works only with local files. It doesn't work with -pipe so you cannot fetch a URL with eg curl and feed the PNG to PlantUML.

However, the Plantuml server has a similar feature, where it can get a PNG from a URL and extract its metadata.

終了コード

Exit code

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

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

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

When there are some errors in diagrams the command returns an error (-1) exit code. But even if some diagrams contain some errors, all diagrams are generated, which can be time consuming for large project.

You can use the -failfast flag to change this behavior to stop diagram generations as soon as one error occurs. In that case, some diagrams will be generated, and some will not.

There is also a -failfast2 flag that does a first checking pass. If some error is present, no diagram will be generated at all. In case of error, -failfast2 runs even faster than -failfast, which may be useful for huge project.

Standard report [stdrpt]

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?

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?

標準入出力

Standard Input & Output

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

Using the -pipe option, you can easily use PlantUML in your scripts.

With this option, a diagram description is received through standard input and the PNG file is generated to standard output. No file is written on the local file system.

Example:

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

The -pipemap option can be used to generate PNG map data (hyperlink rectangles) for use in HTML, eg:

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

The map file looks like this:

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

Note: Also take a look at -pipedelimitor and -pipeNoStderr to implement proper multiplexing of several PNG in a stream (in case the puml file contains multiple diagrams), and error handling.

Help

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

You can have a help message by launching :

java -jar plantuml.jar -help

This will output:

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


Please report any bugs to plantuml@gmail.com or here.
This website is still in beta testing.