gopuml

README

gopuml

A Go reimplementation of PlantUML v1.2026.8 (MIT variant). It reads the same diagram language and produces the same SVG, PNG and text output, and it works as:

• a command line that replaces java -jar plantuml.jar
• a Go library
• an HTTP server compatible with PlantUML's built-in server and the main plantuml-server routes
• a WebAssembly module for browsers and Node.js

No JVM is needed. Graphviz dot is needed only for class, description (use case, component, deployment), state and legacy activity diagrams.

Supported diagrams and formats

Diagram type	SVG	PNG	TXT / UTXT
Sequence	yes	yes	yes
Class and object	yes (needs dot)	yes (needs dot)	no
Use case, component and deployment	yes (needs dot)	yes (needs dot)	no
State	yes (needs dot)	yes (needs dot)	no
Activity (new syntax)	yes	yes	no
Activity (legacy syntax)	yes (needs dot)	yes (needs dot)	no

The preprocessor (!include, !define, functions, all 74 builtins, JSON), themes, skin parameters, styles and creole are supported, including diagrams embedded in text with {{ ... }}, and so is the PREPROC output (--preproc).

Other diagram types (archimate, timing, gantt, mindmap, and so on) are reported with an explicit "... diagrams are not supported yet" error image instead of a wrong drawing.

Compatibility is measured against upstream PlantUML v1.2026.8 with a conformance suite of 502 cases (upstream's Vega test corpus plus curated cases): every case passes, apart from 25 documented known differences (testdata/conformance/known-differences.yaml) and 105 cases of diagram types that are not supported yet. Most SVG outputs are byte-identical to upstream's, except the encoded source in <?plantuml-src ...?>, which uses a different deflate implementation and decodes to the same text.

Installation

Each release has an archive of the command line for linux, macOS and windows on amd64 and arm64 (gopuml_<version>_<os>_<arch>.tar.gz, .zip on windows), with LICENSE, NOTICE and this README, an archive of the WebAssembly module (gopuml_<version>_wasm.tar.gz), and checksums.txt with the SHA-256 of every archive. Download the archive of your system and checksums.txt from the release page, or with the GitHub CLI, then check and unpack it:

gh release download v0.1.0 --repo ekalinin/gopuml -p '*_darwin_arm64.tar.gz' -p checksums.txt
shasum -a 256 --ignore-missing -c checksums.txt   # sha256sum on linux
tar xzf gopuml_0.1.0_darwin_arm64.tar.gz plantuml
./plantuml --version

The macOS binaries are not signed. When a browser downloaded the archive, macOS blocks the binary until its quarantine attribute is removed:

xattr -d com.apple.quarantine plantuml

With Go 1.26 or later, the command line can also be installed from source:

go install github.com/ekalinin/gopuml/cmd/plantuml@v0.1.0

While the repository is private, set GOPRIVATE=github.com/ekalinin/gopuml, so that the go command fetches it with your git credentials instead of the module proxy.

Building

Go 1.26 or later is needed. In a checkout of this repository:

go build -o plantuml ./cmd/plantuml
./plantuml --version

Command line

The command line accepts the flags of java -jar plantuml.jar. Flags that this implementation does not provide (for example --pdf) are rejected with exit status 1 instead of being silently ignored.

printf '@startuml\nAlice -> Bob : hello\n@enduml\n' > diagram.puml

./plantuml diagram.puml              # writes diagram.png (PNG is the default)
./plantuml --svg diagram.puml        # writes diagram.svg
./plantuml --txt diagram.puml        # writes diagram.atxt
./plantuml --svg -o out diagram.puml # writes out/diagram.svg
./plantuml --check-syntax diagram.puml

printf 'Alice -> Bob\n' | ./plantuml -p --svg > pipe.svg
printf 'Alice -> Bob\n' | ./plantuml -syntax

./plantuml --encode-url diagram.puml
./plantuml --extract-source diagram.svg
./plantuml --help

Exit statuses are upstream's: 0 on success, 50 when no input file is found, 100 when no diagram is found, 200 when a diagram has an error.

Library

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/ekalinin/gopuml"
)

func main() {
	src := "@startuml\nAlice -> Bob : hello\n@enduml\n"
	res, err := gopuml.Render(context.Background(), src, &gopuml.Options{Format: gopuml.SVG})
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
	fmt.Printf("%dx%d %s\n", res.Width, res.Height, res.Description)
	os.WriteFile("diagram.svg", res.Data, 0o644)
}

Render returns typed errors (*gopuml.SyntaxError with the line and message, gopuml.ErrGraphvizNotFound, gopuml.ErrUnsupportedDiagram, ...) and, for a syntax error, the error image together with the error. gopuml.Inspect lists the blocks of a source, and gopuml.Encode and gopuml.Decode convert sources to and from the text of server URLs. Includes can be resolved from an fs.FS given in the options.

HTTP server

./plantuml --http-server:8080

It serves GET /svg/<encoded>, /png/<encoded>, /txt/<encoded>, /utxt/<encoded> (also under /plantuml/, and the d-prefixed dark mode routes), POST /render with a JSON body, /coder, /check, /language and /serverinfo. It runs in the INTERNET security profile, limits request bodies to 1 MiB and renders for at most 60 seconds.

WebAssembly

make wasm

This writes plantuml.wasm, Go's wasm_exec.js and the ES module loader plantuml.mjs into dist/wasm:

import { load } from './plantuml.mjs';

const plantuml = await load();
const result = await plantuml.render('@startuml\nAlice -> Bob\n@enduml', { format: 'svg' });
// result.data is a Uint8Array; result.error is null or { kind, message, line }.

The module runs in the SANDBOX security profile: includes come only from the files option. Class, description, state and legacy activity diagrams report that graph layout is not available in this build.

Graphviz

Class, object, description, state and legacy activity diagrams are laid out by Graphviz dot, as upstream does. dot is looked up from --dot-path (or the library option), then the GRAPHVIZ_DOT environment variable, then PATH and the usual install locations. ./plantuml --check-graphviz reports the version found. The references were made with Graphviz 14.0.1. Sequence diagrams and activity diagrams in the new syntax do not need Graphviz.

Conformance suite

make conformance renders every case with this implementation and compares the outputs with the references of upstream PlantUML, which make reference records in a Docker image (tools/reference/Dockerfile). The comparison writes conformance-report.md.

CI runs the suite on every pull request and every push to main, with every group required: a failing case that is not listed in testdata/conformance/known-differences.yaml fails the run. The report is attached to the run and shown in its summary. On a linux/amd64 host, these commands reproduce the CI run:

make reference
make conformance REQUIRE=all GO_IN_IMAGE=1

GO_IN_IMAGE=1 renders the outputs of this implementation in the reference image, so that both implementations use the same Graphviz. On arm64 hosts, make conformance renders them natively with the host's Graphviz, so the results there are indicative only.

License

MIT, see LICENSE. This project translates the MIT-licensed variant of PlantUML v1.2026.8 (net.sourceforge.plantuml:plantuml-mit), (C) Copyright 2009-2024, Arnaud Roques. Every Go file names the upstream file it comes from in its header. NOTICE lists the bundled assets (DejaVu fonts, themes) with their licenses, the parts of fdlibm the math functions come from, and the upstream components that are not included.

Documentation

Overview

Package gopuml renders PlantUML diagram source to SVG, PNG and text.

It is a Go reimplementation of PlantUML v1.2026.8 (MIT variant).

Index

• Variables
• func Decode(text string) (string, error)
• func Encode(source string) string
• type Block
  • func Inspect(ctx context.Context, source string, opts *Options) ([]*Block, error)
  • func (b *Block) Encoded() string
  • func (b *Block) Pages() int
  • func (b *Block) Render(ctx context.Context, w io.Writer, page int, opts *Options) (*Result, error)
  • func (b *Block) Source() []string
• type Define
• type Format
  • func (f Format) String() string
• type Options
• type Result
  • func Render(ctx context.Context, source string, opts *Options) (*Result, error)
• type SyntaxError
  • func (e *SyntaxError) Error() string
  • func (e *SyntaxError) Is(target error) bool
• type UnsupportedError
  • func (e *UnsupportedError) Error() string
  • func (e *UnsupportedError) Is(target error) bool

Variables

var (
	// ErrSyntax matches every *SyntaxError.
	ErrSyntax = errors.New("plantuml: syntax error")
	// ErrNoDiagram reports a source without a diagram, or a diagram or
	// page index out of range.
	ErrNoDiagram = errors.New("plantuml: no diagram found")
	// ErrUnsupportedDiagram reports a diagram type or family this
	// implementation does not provide.
	ErrUnsupportedDiagram = errors.New("plantuml: diagram type not supported")
	// ErrUnsupportedFormat reports a format a diagram type cannot produce.
	ErrUnsupportedFormat = errors.New("plantuml: format not supported for this diagram")
	// ErrGraphvizNotFound reports that the Graphviz dot program is missing.
	ErrGraphvizNotFound = errors.New("plantuml: Graphviz dot not found")
	// ErrGraphvizTimeout reports a dot run stopped after the timeout.
	ErrGraphvizTimeout = errors.New("plantuml: Graphviz dot timed out")
	// ErrGraphvizFailed reports a dot run that failed.
	ErrGraphvizFailed = errors.New("plantuml: Graphviz dot failed")
	// ErrAccessDenied reports a file or URL the security profile does not
	// allow.
	ErrAccessDenied = security.ErrDenied
	// ErrDecode reports text that is not encoded diagram source.
	ErrDecode = code.ErrNoCompression
)

Errors returned by the package. Test for them with errors.Is; a syntax error is also a *SyntaxError, usable with errors.As.

Functions

func Decode

func Decode(text string) (string, error)

Decode returns the source of text in any format PlantUML server URLs use. It fails with an error matching ErrDecode.

func Encode

func Encode(source string) string

Encode returns source in the text format of PlantUML server URLs.

Types

type Block

type Block struct {
	// Name is the name given on the start line, such as "login" for
	// "@startuml login", or "".
	Name string
	// Family is the word after @start, in lower case, such as "uml".
	Family string
	// Type is the diagram type upstream detects, such as "SEQUENCE" or
	// "CLASS", or "" for a block with an error.
	Type string
	// Description is upstream's description, such as "(2 participants)" or
	// "(Error)".
	Description string
	// Err is the syntax status: nil, a *SyntaxError, or an error matching
	// ErrUnsupportedDiagram.
	Err error
	// contains filtered or unexported fields
}

Block is one @start/@end block of a source, with its diagram.

func Inspect

func Inspect(ctx context.Context, source string, opts *Options) ([]*Block, error)

Inspect lists the blocks of a source with their diagram type and syntax status, without drawing them.

func (*Block) Encoded

func (b *Block) Encoded() string

Encoded returns the block in the text format of PlantUML server URLs.

func (*Block) Pages

func (b *Block) Pages() int

Pages returns the number of pages of the diagram.

func (*Block) Render

func (b *Block) Render(ctx context.Context, w io.Writer, page int, opts *Options) (*Result, error)

Render draws one page of the block to w. A block with an error returns its error (a *SyntaxError or an *UnsupportedError) together with the error image, unless NoErrorImage is set.

func (*Block) Source

func (b *Block) Source() []string

Source returns the lines of the block, from the start line to the end line.

type Define

type Define struct {
	Name, Value string
}

Define is a preprocessor definition, like -DNAME=VALUE on the command line.

type Format

type Format int

Format is an output format.

const (
	SVG  Format = iota
	PNG         // PNG image
	TXT         // ASCII art
	UTXT        // Unicode art
)

Formats. The zero value is SVG.

func (Format) String

func (f Format) String() string

type Options

type Options struct {
	// Format is the output format.
	Format Format
	// Diagram and Page select what Render draws: the index of the
	// @start/@end block and the page within it, both from 0.
	Diagram, Page int
	// NoMetadata omits the embedded source from SVG and PNG output.
	NoMetadata bool
	// NoErrorImage returns syntax errors without an error image.
	NoErrorImage bool
	// Defines are preprocessor definitions, in order.
	Defines []Define
	// Config lines are inserted after the start line of every diagram.
	Config []string
	// IncludePaths are directories searched by !include.
	IncludePaths []string
	// Theme is applied to every diagram, like !theme.
	Theme string
	// DarkMode renders with upstream's dark color mapping.
	DarkMode bool
	// SecurityProfile is upstream's profile name, such as SANDBOX or
	// INTERNET; empty means LEGACY.
	SecurityProfile string
	// DotPath is the Graphviz dot program; empty means it is searched for.
	DotPath string
	// DotTimeout stops dot after this duration; zero means 30 seconds.
	DotTimeout time.Duration
	// FS resolves includes and themes. When nil, the operating system's
	// file system is used, subject to the security profile.
	FS fs.FS
	// Dir is the directory of the source, against which relative includes
	// are resolved.
	Dir string
	// Filename is the name of the source, as %filename() returns it.
	Filename string
}

Options configure one call; they do not affect other calls. A nil *Options means the zero value.

type Result

type Result struct {
	// Data is the output: an image, or text for TXT and UTXT.
	Data []byte
	// Width and Height are the size of the image in pixels.
	Width, Height int
	// Description is upstream's description, such as "(2 participants)".
	Description string
	// Pages is the number of pages of the rendered diagram.
	Pages int
	// Diagrams is the number of @start/@end blocks of the source.
	Diagrams int
}

Result is a rendered page.

func Render

func Render(ctx context.Context, source string, opts *Options) (*Result, error)

Render draws the diagram and page selected by opts.Diagram and opts.Page. For a syntax error it returns the error image, unless opts.NoErrorImage is set, together with the *SyntaxError.

type SyntaxError

type SyntaxError struct {
	// Line is the 1-based line of the error in the source.
	Line int
	// Message is upstream's message, for example "Syntax Error? (Assumed
	// diagram type: sequence)".
	Message string
}

SyntaxError is a diagram with a syntax error.

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

func (*SyntaxError) Is

func (e *SyntaxError) Is(target error) bool

Is makes errors.Is(err, ErrSyntax) true for a *SyntaxError.

type UnsupportedError

type UnsupportedError struct {
	// Line is the 1-based line of the source that shows the type.
	Line int
	// Message explains what is not supported, for example "mindmap
	// diagrams are not supported yet".
	Message string
}

UnsupportedError is a diagram whose type or family this implementation does not provide.

func (*UnsupportedError) Error

func (e *UnsupportedError) Error() string

func (*UnsupportedError) Is

func (e *UnsupportedError) Is(target error) bool

Is makes errors.Is(err, ErrUnsupportedDiagram) true for an *UnsupportedError.