Scala2PlantUML

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.

Example

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

sbt

Enable SemanticDB

For sbt versions >= 1.3.0:

semanticdbEnabled := true

For sbt versions < 1.3.0:

addCompilerPlugin("org.scalameta" % "semanticdb-scalac" % "x.y.z" cross CrossVersion.full)
scalacOptions += "-Yrangepos"

Add Scala2PlantUMLPlugin

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")

Generate the Diagram

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.

CLI

Install

Use Coursier to create a launcher for Scala2PlantUML:

cs install --channel https://git.io/Jqv1i scala2plantuml

Usage

scala2plantuml --help

Scala2PlantUML 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

Library

🚧 TODO: Document Library.

Limitations

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.

License

scala-steward/scala2plantuml

ErrorLooks like something went wrong!

About

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Error
Looks like something went wrong!

Packages