How to use the command 'plantuml' (with examples)

PlantUML is a powerful tool that allows users to create UML diagrams from a simple and intuitive plain text language. The command-line utility can generate different types of UML diagrams, such as sequence diagrams, use case diagrams, class diagrams, and more. These diagrams can be rendered into various formats, including PNG, SVG, and PDF, among others, making PlantUML a versatile solution for software design and documentation.

Render diagrams to default format (PNG)

Code:

plantuml diagram1.puml diagram2.puml

Motivation for using the example: In software development, quickly generating visual representations of system components and their interactions can be crucial. This command allows developers to convert UML diagrams written in PlantUML’s text format into images (PNGs) which can be easily shared and incorporated into documentation or presentations.

Explanation:

• plantuml: This is the command-line tool for rendering UML diagrams.
• diagram1.puml and diagram2.puml: These are the input files containing PlantUML code. By listing them, the tool will process each file to generate corresponding PNG diagrams.

Example output: Execution of this command would result in two new PNG files, diagram1.png and diagram2.png, appearing in the same directory as the original .puml files.

Render a diagram in given format

Code:

plantuml -t svg diagram.puml

Motivation for using the example: Different scenarios require different file formats. SVG, being a vector format, is ideal for cases where scalability without loss of quality is needed, such as including the diagram in web pages or print materials.

Explanation:

• -t svg: This flag specifies the output format as SVG (Scalable Vector Graphics).
• diagram.puml: The input file that contains the textual definition of the UML diagram.

Example output: The command generates an SVG file diagram.svg from diagram.puml.

Render all diagrams of a directory

Code:

plantuml path/to/diagrams

Motivation for using the example: Developers often store multiple .puml files in a directory. Running a command on the whole directory simplifies batch processing, saving time by avoiding the need to individually render each diagram.

Explanation:

• path/to/diagrams: This path specifies the directory containing the .puml files. The tool will process each file within this directory.

Example output: All .puml files in path/to/diagrams are rendered, resulting in corresponding image files in the same directory.

Render a diagram to the output directory

Code:

plantuml -o path/to/output diagram.puml

Motivation for using the example: Organizing generated output files in a specific directory helps in maintaining a clean and structured project directory, making it easier to locate files and separate source code from generated images.

Explanation:

• -o path/to/output: Specifies the directory where the rendered diagram should be saved.
• diagram.puml: The input PlantUML file to be processed.

Example output: An image file is generated in the specified output directory, path/to/output/diagram.png.

Render a diagram without storing the diagram’s source code

Code:

plantuml -nometadata diagram.png > diagram.puml

Motivation for using the example: Preserving privacy or confidentiality of the source code. When sharing diagrams, the source code metadata is stripped to avoid unintentional exposure of sensitive information embedded in the diagram.

Explanation:

• -nometadata: Prevents the storing of metadata containing the original source code in the PNG file.
• diagram.png > diagram.puml: Redirects the output to save a new PlantUML source file if needed, although the primary intent here is not storing such data in the PNG.

Example output: The diagram.png will be the diagram image without embedded metadata, while diagram.puml captures the extracted source.

Retrieve source from a plantuml diagram’s metadata

Code:

plantuml -metadata diagram.png > diagram.puml

Motivation for using the example: To reconstruct or retrieve the original PlantUML code from a diagram image. This can be particularly useful when the original code file is lost or to review the textual representation used to generate the diagram.

Explanation:

• -metadata: Extracts the original PlantUML source from the image’s metadata.
• diagram.png > diagram.puml: Inputs the image file and outputs the extracted source code into diagram.puml.

Example output: The extracted PlantUML source is written to diagram.puml.

Render a diagram with the configuration file

Code:

plantuml -config config.cfg diagram.puml

Motivation for using the example: Custom configurations are sometimes necessary to maintain consistent styles and settings across multiple diagrams. This flag allows users to apply a predefined set of configurations when rendering diagrams.

Explanation:

• -config config.cfg: Specifies the configuration file that will be used to render the diagram.
• diagram.puml: The input file which will be rendered using the configurations specified.

Example output: The tool outputs an image with custom settings applied as per config.cfg.

Display help

Code:

plantuml -help

Motivation for using the example: Consult the help documentation when unfamiliar with the command-line options or when additional assistance is needed regarding specific functionalities. This is invaluable for both newcomers and experienced users seeking to explore all possibilities the command offers.

Explanation:

• -help: Provides a textual guide and list of available options for using the PlantUML tool.

Example output: A detailed help text is displayed on the terminal, outlining various command options and their functionalities.

Conclusion:

PlantUML is a versatile tool for generating UML diagrams from text descriptions. This guide has walked through various use cases of the PlantUML command-line utility, showcasing how it can be employed in different scenarios to meet specific needs, from output format customization to source code retrieval, enhancing both workflow efficiency and documentation quality.