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.

Recent changes    Wiki Toc    View page history    Add new chapter    Reorder page    Raw

命令行

您也可以使用下面的命令行运行PlantUML:

java -jar plantuml.jar file1 file2 file3

这将在 file1, file2file3 中寻找 @startXYZ。 对于每个图表, 都将创建一个 .png 文件。

对于处理整个文件夹, 您可以使用:

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

此命令将寻找 @startXYZ@endXYZ 位于 c:/directory1c:/directory2 目录中的 .c, .h, .cpp, .txt, .pu, .tex, .html, .htm.java 文件。

Command line

You can also run PlantUML using the following command :

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 .c, .h, .cpp, .txt, .pu, .tex, .html, .htm or .java files of the c:/directory1 and c:/directory2 directories.

通配符

您也可以使用通过符 :

  • 对于单个字符,用 ?
  • 对于零个或多个字符, 用 *
  • 对于零个或多个字符, (包括 /\), 用一对 **

所以处理所有以 dummy 开始的目录的任意 .cpp 文件:

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

和处理以 dummy 开始的目录及其子目录中的任意 .cpp 文件 :

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

Wildcards

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"

排除文件

您可以使用 -x 选项来排除处理队列中的某些文件:

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

Excluded files

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

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

输出目录

您可以使用 -o 开关来指定一个输出所有图片的目录:

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

如果您递归进入几个目录,如果为此输出目录提供绝对路径或相对路径,则会略有不同。

  • 绝对路径: 将使用唯一的输出目录,在其中生成所有图像
  • 相对路径: 将在文件树中使用多个输出目录。

Output Directory

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.

  • absolute path: An unique output directory will be used, with all images generated inside
  • relative path: Several output directories will be used across the file tree.

配置文件

您还可以在每个图表之前提供将包含的配置文件:

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

Configuration File

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

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

Metadata

After all preprocessing (includes etc), PlantUML saves the diagram's source code in the generated PNG Metadata in the form of encoded text.
  • 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.

Metadata

After all preprocessing (includes etc), PlantUML saves the diagram's source code in the generated PNG Metadata in the form of encoded text.
  • 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.

退出代码

当图表中存在一些错误时,该命令会返回错误 (-1) 退出代码。 但即使某些图表包含一些错误, 所有 图表仍会生成,这对于大型项目来说可能是耗时的。

您可以使用 -failfast 标志来改变这种行为,在错误发生时尽快停止图表生成。在这种情况下,将生成一些图表,而有些图表则不会生成。

同时有 -failfast2 标志做第一次通过检查。 如果出现某些错误,根本不会有图表生成。如果有错误 -failfast2 运行速度比 -failfast 要快, 这可能对大型项目有用。。

Exit code

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.

标准输入输出

使用 -pipe 选项,您可以很容易在脚本中使用 PlantUML。

使用此选项,通过标准输入接收图表描述,并生成png文件到标准输出。在本地文件系统上不会写任何文件。

例如:

type somefile.txt | java -jar plantuml.jar -pipe > somefile.png

Standard Input & Output

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.

帮助

您可以用以下命令来获得帮助:

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
    -nosuggestengine               Disable the suggest engine when errors in diagrams
    -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

Help

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:
    -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
    -nosuggestengine               Disable the suggest engine when errors in diagrams
    -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


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