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


Ligne de commande

Command line

Vous pouvez également exécuter PlantUML en utilisant la commande suivante

java -jar plantuml.jar file1 file2 file3

Ceci recherchera @startXYZ dans file1, file2 et file3. Pour chaque diagramme, un fichier .png sera créé.

Pour traiter un répertoire entier, vous pouvez utiliser

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

Cette commande recherchera @startXYZ et @endXYZ dans .txt, .tex, .java, .htm, .html, .c, .h, .cpp, .apt, .pu, .puml, .hpp ou les fichiers .hh des répertoires c:/directory1 et c:/directory2

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.

Caractères génériques

Wildcards

Vous pouvez aussi utiliser des caractères génériques:

  • Pour un caractère unique, utilisez ?
  • Pour plusieurs caractères (y compris zéro caractères), utilisez *
  • Si vous voulez aussi inclure les caractères spéciaux / et \), utilisez une double étoile **

Pour traiter tous les fichiers .cpp des répertoires dont le nom commence par dummy :

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

Pour traiter tous les fichiers .cpp des répertoires dont le nom commence par dummy, ainsi que leurs sous-répertoires:

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"

Exclure des fichiers

Excluded files

Vous pouvez exclure certains fichiers en utilisant l'option -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"

Répertoire de sortie

Output Directory

Vous pouvez spécifier un répertoire de sortie pour toutes les images en utilisant le commutateur -o

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

Si vous faites une récursion dans plusieurs répertoires, il y a une légère différence si vous fournissez un chemin absolu ou relatif pour ce répertoire de sortie :

  • Un chemin absolu garantira que toutes les images sont sorties dans un seul répertoire spécifique.

  • Si vous fournissez un chemin relatif, alors les images sont placées dans ce répertoire par rapport à l'emplacement du fichier d'entrée, et non dans le répertoire courant (note : ceci s'applique même si le chemin commence par un .). Lorsque Plantuml traite des fichiers provenant de plusieurs répertoires, la structure de répertoire correspondante est créée sous le répertoire de sortie calculé

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 de fichiers de sortie

Types of Output File

Les images de vos diagrammes peuvent être exportées dans différents formats. Par défaut, le format sera un fichier PNG mais un autre type peut être sélectionné en utilisant les extensions suivantes

Nom du paramètre Nom court du paramètre Format de sortie Commentaire
-tpng -png PNG Défaut
-tsvg -svg SVG Plus de détails sont disponibles ici
-teps -eps EPS Plus de détails peuvent être trouvés ici
-teps:text -eps:text EPS Cette option permet de conserver le texte en tant que texte
-tpdf -pdf PDF Plus de détails peuvent être trouvés ici
-tvdx -vdx VDX Document Microsoft Visio
-txmi -xmi XMI De plus amples informations sont disponibles ici
-tscxml -scxml SCXML
-thtml -html HTML Caractéristique alpha : ne pas utiliser
-ttxt -txt ATXT Art ASCII. Vous trouverez plus de détails ici
-tutxt -utxt UTXT art ASCII utilisant des caractères Unicode
-tlatex -latex LATEX De plus amples informations sont disponibles ici
-tlatex:nopreamble -latex:nopreamble LATEX Ne contient pas de préambule LaTeX créant un document
-tbraille -braille PNG Image en braille

Exemple

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

Fichier de configuration

Configuration File

Vous pouvez fournir un fichier de configuration qui sera inclus avant chaque diagramme:

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

Métadonnées

Metadata

Après tous les prétraitements (inclusions, etc.), PlantUML enregistre le code source du diagramme dans les métadonnées PNG générées sous forme de texte encodé.
  • Si vous ne voulez pas que PlantUML enregistre le code source du diagramme dans les métadonnées PNG générées, vous pouvez, pendant la génération, utiliser l'option -nometadata pour désactiver cette fonctionnalité (pour NE PAS exporter les métadonnées dans les fichiers PNG/SVG générés).
  • Il est possible de récupérer cette source avec l'option -metadata. Cela signifie que le PNG est presque "éditable" : vous pouvez le poster sur un wiki d'entreprise où vous ne pouvez pas installer de plugins, et quelqu'un dans le futur peut mettre à jour le diagramme en récupérant les métadonnées, en les éditant et en les rechargeant à nouveau. De plus, le diagramme est autonome.
  • A l'inverse, l'option -checkmetadata vérifie si le PNG cible a la même source et s'il n'y a pas de changement, ne régénère pas le PNG, économisant ainsi tout le temps de traitement. Cela vous permet d'exécuter PlantUML sur un dossier entier (ou un arbre avec l'option -recursive ) de manière incrémentale.

Cela semble magique ! Non, simplement une ingénierie intelligente :-)

Exemple

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

Malheureusement, cette option ne fonctionne qu'avec les fichiers locaux. Elle ne fonctionne pas avec -pipe donc vous ne pouvez pas récupérer une URL avec par exemple curl et envoyer le PNG à PlantUML.

Cependant, le serveur Plantuml a une fonctionnalité similaire, où il peut récupérer un PNG à partir d'une URL et extraire ses métadonnées

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.

Code d'erreur

Exit code

Quand il y a des erreurs dans un ou plusieurs diagrammes, la commande renvoie un code d'erreur (-1). Mais même s'il y a des diagrammes en erreur, tous les diagrammes sont générés, ce qui peut prendre du temps pour les projets de grande taille.

Vous pouvez utiliser l'option -failfast pour changer ce comportement et arrêter la génération des diagrammes dès qu'une erreur est rencontrée. Dans ce cas certains diagrammes seront effectivement générés et d'autres ne le seront pas.

Il y a aussi une option -failfast2 qui effectue une première passe de vérification. Si jamais une erreur est présente, aucun diagramme ne sera généré dans ce cas. En cas d'erreur, l'option -failfast2 permet à la commande de s'exécuter encore plus rapidement qu'avec -failfast ce qui peut être utile pour les très grands projets.

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.

Rapport standard [stdrpt]

Standard report [stdrpt]

En utilisant l'option -stdrpt (rapport standard), vous pouvez changer le format de la sortie d'erreur de vos scripts PlantUML.

Avec cette option, une sortie d'erreur différente de votre diagramme est possible
  • -stdrpt
  • -stdrpt:1
  • -stdrpt:2

[Ref. Issue#155 and QA-11805]

Exemples, avec le mauvais fichier file1.pu, où as est écrit aass

@startuml
participant "Famous Bob" aass Bob
@enduml

Sans aucune option

java -jar plantuml.jar file1.pu

La sortie d'erreur est

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

Option -stdrpt

java -jar plantuml.jar -stdrpt file1.pu

La sortie d'erreur est

file1.pu:2:error:Syntax Error?

-stdrpt:1 option

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

La sortie d'erreur est

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

-stdrpt:2 option (comme -stdrpt)

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

Le message d'erreur est le suivant

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?

Entrée et sortie standard

Standard Input & Output

En utilisant l'option -pipe, vous pouvez facilement utiliser PlantUML dans vos scripts.

Avec cette option, une description de diagramme est reçue par l'entrée standard et le fichier PNG est généré sur la sortie standard. Aucun fichier n'est écrit sur le système de fichiers local.

Exemple

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

L'option -pipemap peut être utilisée pour générer des données cartographiques PNG (rectangles d'hyperliens) pour une utilisation en HTML, par exemple

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

Le fichier de carte ressemble à ceci

<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 : Regardez aussi -pipedelimitor et -pipeNoStderr pour implémenter le multiplexage correct de plusieurs PNG dans un flux (dans le cas où le fichier puml contient plusieurs diagrammes), et la gestion des erreurs

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.

Aide

Help

Vous pouvez afficher un message d'aide à l'aide de la commande:

java -jar plantuml.jar -help

Cela imprime la sortie suivante:

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

WARNING
 This translation need to be updated. 
WARNING

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.