PlantUMLAdvanced usageCommand line

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.

Privacy Policy      Advertise