Raku UML::Translators

In brief

This repository is for a Raku package for the translations of code into Unified Modeling Language (UML) specifications and vice versa.

Currently, the package only translates Object-Oriented Programming (OOP) Raku code into:

• The Domain Specific Language (DSL) of Mermaid-JS

• The DSL of PlantUML

• Argument specification of the UML class diagram function UMLClassGraph of the Mathematica / Wolfram Language (WL) package [AAp1]

See [AA2] for usage examples of both PlantUML and UMLClassGraph in Mathematica.

Remark: The package provides Command Line Interface (CLI) script.

Remark: (Currently) the development of PlantUML is more robust and complete than that of Mermaid-JS. Hence, workflow-wise, using this package to generate PlantUML specs would produce (on average) best results.

Future plans

A fully fledged version of this package would translate:

• C++, Java, Kotlin, or Raku code into UML specs

• UML specs into C++, Java, Kotlin, or Raku code

Currently, only UML specs are generated to PlantUML's DSL and a much poorer WL DSL. Ideally, subsequent versions of this package would be able to use UML specifications encoded in XML and JSON.

Installation

From zef's ecosystem

zef install UML::Translators

From GitHub

zef install https://github.com/antononcube/Raku-UML-Translators.git 

Command Line Interface

The package provides the CLI script to-uml-spec. Here is its usage message:

to-uml-spec --help

Usage examples

Generate PlantUML spec for the Raku package "ML::Clustering":

to-uml-spec --/methods --/attributes "ML::Clustering"

With this shell command we generate a Plant UML spec for the package "Chemistry::Stoichiometry" and create the UML diagram image with a local PlantUML JAR file (downloaded from [PUML1]):

to-uml-spec --/methods --/attributes 'Chemistry::Stoichiometry' | java -jar ~/Downloads/plantuml-1.2022.5.jar -pipe -tjpg > /tmp/myuml.jpg

Raku session

UML for ad hoc classes

Here we generate a PlantUML spec:

use UML::Translators;
module MyPackageClass {
  role A { method a1 {} }
  role B { method b1 {} }
  class C does A { has $!c-var; method c1 {} }
  class D does B is C { has $!d-var; method d1 {} }
}
to-uml-spec('MyPackageClass')

Here we generate a MermaidJS spec:

to-uml-spec('MyPackageClass', format => 'mermaid')

UML for packages

Get PlantUML code for the package 'Chemistry::Stoichiometry':

say to-uml-spec('Chemistry::Stoichiometry'):!methods:!attributes

Get WL UML graph spec for the package [AAp1]:

say to-uml-spec('Chemistry::Stoichiometry', format => 'wluml'):!methods:!attributes

Classes in a name space

Get the classes, roles, subs, and constants of a namespace:

.say for namespace-types('ML::TriesWithFrequencies', :how-pairs).sort(*.key)

Potential problems

Mermaid JS

The package can export class diagrams in the Mermaid-JS format. Unfortunately, currently (November 2022) Mermaid-JS does not support colon characters in class names. Hence, colons are replaced with underscores.

Also, currently (November 2022) class specs in Mermaid-JS cannot be empty. I.e. the Mermaid JS code generated here will not produce a diagram:

to-uml-spec --/methods --/attributes "ML::Clustering" --format=mermaid  

(Because of the empty definition ML_Clustering_KMeans { }.)

This command should produce Mermaid JS code that will produce diagram:

to-uml-spec --/methods --/attributes "ML::Clustering" --format=mermaid  

References

[AA1] Anton Antonov, et al., "Find programmatically all classes, grammars, and roles in a Raku package", (2021), StackOverflow.

[AA2] Anton Antonov, "Generating UML diagrams for Raku namespaces", (2022), community.wolfram.com.

[AAp1] Anton Antonov, "UML Diagram Generation Mathematica package", (2016), MathematicaForPrediction at GitHub/antononcube.

[ES1] Eugene Steinberg and Vojtech Krasa, PlantUML integration IntelliJ IDEA plugin, JetBrains Plugins Marketplace.

[GV1] graphviz.org.

[PUML1] plantuml.com.

[PUML2] PlantUML online demo server.

[UMLD1] uml-diagrams.org.

[WK1] Wikipedia entry, "Graphviz".

[WK2] Wikipedia entry, "PlantUML".

[WK3] Wikipedia entry, "Unified Modeling Language".