Skip to content

Latest commit

 

History

History
151 lines (112 loc) · 5.79 KB

README.md

File metadata and controls

151 lines (112 loc) · 5.79 KB
Raw

PlantUML interface for Dart.

Allows easy conversion of diagrams in PlantUML (see https://plantuml.com) text format to various output formats with the help of PlantUML tools, directly from dart.

Tested on Ubuntu 20.04LTS, but it is expected to work on other Operating Systems as well.

Features

  • Dart API to convert String PlantUML diagrams to various output formats (SVG, PNG for now):
    • PumliCmd uses plantuml command line API to convert the diagrams.
    • PumliREST uses the web API for PlantUML to convert the diagrams.
  • PumliServer to start picoweb service of PlantUML:
    • Start plantuml command (need to be installed as a prerequisite) in picoweb mode with the given arguments.
    • Start java with the given PlantUML jar in picoweb mode with the given arguments.

See it in action the simplest way possible:

const simpleModel = '''
@startuml
start
:Hello Pumli user!;
stop
@enduml
''';

final svg = await PumliREST(serviceURL: PumliREST.plantUmlUrl).getSVG(simpleModel);

and the SVG generated:

Alt hello.svg

Getting started

The easiest to start with the package to use an already available PlantUML rendering service like the public one at https://www.plantuml.com/plantuml if you are comfortable with sending your diagrams over the internet to a public server and you do not mind the slight performance impact of a remote renderer. This allows you to start right away with PumliREST (no need to install PlantUML).

In case you want to use either your own lightweight PlantUML renderer service (recommended for performance and security) or the plantuml command line tool for conversion, you need the plantuml tool to be installed onto your system. See https://plantuml.com/starting for details. As you will see PlantUML requires GraphViz (https://plantuml.com/graphviz-dot) for its operation. Nevertheless, on Ubuntu installation is as simple as

$sudo apt install plantuml

WARNING In order to use the picoweb feature of PlantUML you have to have PlantUML V1.2020.19 (12 Oct, 2020) or newer installed.

Unfortunately even Ubuntu 22.04 does not include such a version from apt (it only provides V1.2020.02), that means on Ubuntu you have to either manually copy a more up-to-date version to replace the plantuml.jar that comes with the package or simply just use the downloaded jar directly (as described in the If you only have the PlantUML jar available section bellow). You might face the same issue with the default PlantUML package distributed by other operating systems or distributions.

I would suggest using V1.2022.1 (1 Feb, 2022) as later versions include a bug related to HyperlinkUnderline skinParam feature you might plan to use (see issue #1241).

Usage

We are going to convert the simple diagram that was already used above to SVG format:

const simpleModel = '''
@startuml
start
:Hello Pumli user;
stop
@enduml
''';

NOTE: Use raw string in case your model includes escaped characters like '\n':

const rawString = r'demo\n';

Convert it with the public PlantUML rendering service

final pumliREST = PumliREST(serviceURL: PumliREST.plantUmlUrl);
final svg = await pumliREST.getSVG(model);
await File('/tmp/simple_rest.svg').writeAsString(svg);

serviceURL could have been any PlantUML web api compliant service you have access to. For example on Linux you can start one from the command line:

$ plantuml -picoweb
webPort=8080

In this case serviceURL would be '127.0.0.1:8080'

Convert simpleModel with using the PlantUML command line API

This first version can be used if the plantuml command is preinstalled on your system:

final pumliCmd = PumliCmd();
final svg2 = await pumliCmd.getSVG(model);
await File('/tmp/simple_cmd.svg').writeAsString(svg2);

If you only have the PlantUML jar available (and GraphViz is installed):

final pumliCmdJar = PumliCmd(jar: '/path/to/plantuml.jar');
final svg3 = await pumliCmdJar.getSVG(model);
await File('/tmp/simple_cmd_jar.svg').writeAsString(svg3);

Starting you own local PlantUML picoweb renderer from dart

as simple as

final pumliServer = PumliServer();
await pumliServer.start();

This will start the plantuml -picoweb:8080:127.0.0.1 command. By default it listens on port 8080 and binds to the localhost (127.0.0.1 - only localhost connections are accepted). After this you can start using it right away:

final pumliREST = PumliREST(serviceURL: pumliServer.url);
final svg = await pumliREST.getSVG(model);
await File('/tmp/simple_rest.svg').writeAsString(svg);

PumliServer constructor includes three parameters to customize its behavior: port to define the listening port of the service, bind to set the bind address (e.g. setting it to 0.0.0.0 will let connections on any interfaces) and jar to define the PlantUML jar path if you want PumliServer to use java directly to start the picoweb service.

Additional information

If you have any questions, comments please go to Pumli GitHub Discussions to start or join discussions.