Scala2PlantUML generates PlantUML diagrams from Scala code.
It comes as a standalone library, a CLI tool and an sbt plugin.
Scala2PlantUML consumes SemanticDB files so you will need to know how to create those or simply follow the sbt setup instructions below.
scala2plantuml \
--url 'https://repo1.maven.org/maven2/nz/co/bottech/scala2plantuml-example_2.13/0.3.0/scala2plantuml-example_2.13-0.3.0.jar'\
--project example \
"nz/co/bottech/scala2plantuml/example/Main."@startuml
class A extends B {
+ {method} <init>
+ {method} b
}
A o-- C
interface B {
+ {abstract} {method} b
}
B o-- C
class C {
+ {method} <init>
+ {field} value
}
C o-- A
class Main {
+ {static} {field} a
}
Main o-- A
@enduml
For sbt versions >= 1.3.0:
semanticdbEnabled := trueFor sbt versions < 1.3.0:
addCompilerPlugin("org.scalameta" % "semanticdb-scalac" % "x.y.z" cross CrossVersion.full)
scalacOptions += "-Yrangepos"For most use cases you should add Scala2PlantUML as a global plugin since your build is unlikely to depend on it.
Create ~/.sbt/1.0/plugins/scala2PlantUML.sbt containing:
addSbtPlugin("nz.co.bottech" % "sbt-scala2plantuml" % "0.3.0")
Run the scala2PlantUML task from sbt:
scala2PlantUML "com/example/Foo#"This accepts the following arguments:
--include--exclude--output
Refer to the CLI Usage for the definition of these arguments.
Use Coursier to create a launcher for Scala2PlantUML:
cs install --channel https://git.io/Jqv1i scala2plantumlscala2plantuml --helpScala2PlantUML version 0.3.0
Usage: scala2plantuml [options] symbol
Scala2PlantUML generates PlantUML Class Diagrams from Scala SemanticDB files.
symbol The symbol to use as the starting point for generating the diagram.
To get a symbol from a class name, convert the package name separate '.' to '/' and add a '#'
suffix. For an object use a suffix of '.'.
See https://scalameta.org/docs/semanticdb/specification.html#symbol-1 for the full syntax.
Examples:
'com/example/Foo#' (class com.example.Foo)
'com/example/Foo.' (object com.example.Foo)
'com/example/Foo.bar.' (value/variable bar on object com.example.Foo)
'com/example/Foo#baz().' (function baz on class com.example.Foo)
The --include and --exclude options control which symbols will be processed. Each of these can be provided multiple times.
The pattern supports two wildcards:
1) ** (matches any character)
2) * (matches all characters except for '/')
-i, --include <pattern> Only include symbols that match the pattern.
Default: '**'
Example:
--include 'com/example/**/model/*'
-e, --exclude <pattern> Excludes all symbols that match the pattern.
Default: 'scala/**', 'java/**'
Example:
--exclude 'com/example/**/data/*'
The --dir, --jar, and --url options specify the directories and JAR files that are used when locating SemanticDB files.
Each of these can be provided multiple times.
By default, the classpath that was used when executing Scala2PlantUML is also used.
-d, --dir <dir> Directories of the SemanticDB target roots containing META-INF/semanticdb/**/*.semanticdb files.
Example:
--dir 'my-project/target/scala-2.13/meta'
-j, --jar <jar> JAR containing META-INF/semanticdb/**/*.semanticdb files.
Example:
--jar 'foo.jar'
-u, --url <url> A URL to a JAR containing META-INF/semanticdb/**/*.semanticdb files.
Example:
--url 'https://repo1.maven.org/maven2/com/example/foo/foo_2.13/1.0.0/foo_2.13-1.0.0-semanticdb.jar'
The --project and --source options specify where within the search locations the SemanticDB files can be found.
Each of these can be provided multiple times. The result will be all combinations of projects and source roots.
-p, --project <project> The name of the projects that have SemanticDB files.
The project name will be used when looking for SemanticDB files such as:
META-INF/semanticdb/<project>/<source>/*.semanticdb
An empty project name will search in:
META-INF/semanticdb/<source>/*.semanticdb
Default: ''
Example:
--project my-project
-s, --source <source> The directory relative to the project where the source files were located.
The source will be used when looking for SemanticDB files such as
META-INF/semanticdb/<project>/<source>/*.semanticdb.
Default: src/main/scala
Example:
--source 'source/scala'
-l, --max-level <level> The maximum number of levels that will be traversed when following symbol references.
This means that parent symbols that would be beyond the max level will not be shown.
A diagram with a max-level of 1 will only contain the initial symbol.
Default: Unlimited
Example:
--max-level 3
-o, --output <file> Write the output to the given file.
Example:
--output docs/diagrams/my-project.puml
-c, --colour <value> Enables coloured output.
Default: true
Example:
--colour false
-v, --verbose Increases the log level.
This can be provided twice for the most verbose logging.
Example:
-vv
-h, --help
--version
🚧 TODO: Document Library.
- Only class diagrams are supported.
- Only inheritance or aggregations are supported, compositions are shown as aggregations.
- Aggregations are shown between types not between fields. There is a [bug][namespaced field links] in PlantUML which prevents us from being able to do this reliably.
- There is no reliable way to determine the path to a SemanticDB file from any symbol.
If Scala2PlantUML is unable to find your symbols then the following may help:
- Only have a single top level type in each file.
- Ensure that the file name matches the type name.
- Nest any subclasses of a sealed class within the companion object of the sealed class.