Skip to content
GitLab
Commit 48fc8dff authored by René Schöne's avatar René Schöne
Browse files

Add documentation.

parent 9c2e463f
Pipeline #12705 passed with stages
in 2 minutes and 25 seconds
Hide whitespace changes
Inline Side-by-side
pages/adding.md 0 → 100644
View file @ 48fc8dff
# Add relast2uml to your project
If you want to use `Relast2Uml`, either use the latest [pre-build version](#use-packaged-version) or clone the repository and [build it yourself](#build-from-source).
## Use packaged version
Check the [package overview page](https://git-st.inf.tu-dresden.de/jastadd/relast2uml/-/packages) to find the latest versions of the individual packages.
First add this GitLab as a repository in your `build.gradle`:
```
repositories {
maven {
name "gitlab-maven"
url "https://git-st.inf.tu-dresden.de/api/v4/groups/jastadd/-/packages/maven"
}
}
```
### grammar2uml
To use `Grammar2uml`, add it as a dependency:
```
configurations {
grammar2umlClasspath
}
dependencies {
grammar2umlClasspath group: 'de.tudresden.inf.st', name: 'grammar2uml', version: '0.1.1'
}
```
Finally, add a task to create your visualization:
```
task grammar2uml(type: JavaExec) {
main = 'de.tudresden.inf.st.jastadd.grammar2uml.compiler.Compiler'
classpath = configurations.grammar2umlClasspath
args([
'--verbose',
'src/main/jastadd/GoalModel.relast'
])
}
```
### dumpAst
To use `DumpAst` or `DumpAstWithPlantuml`, add it as a dependency:
```
dependencies {
implementation group: 'de.tudresden.inf.st', name: 'dumpAst', version: '0.3.4'
// or
implementation group: 'de.tudresden.inf.st', name: 'dumpAstWithPlantuml', version: '0.3.4'
}
```
## Build from source
If you want to build the tools of `Relast2Uml` from source, first build the jar from the [Relast2Uml repository](https://git-st.inf.tu-dresden.de/jastadd/relast2uml):
```bash
git clone https://git-st.inf.tu-dresden.de/jastadd/relast2uml.git
cd relast2uml
./gradlew jar
ls grammar2uml/build/libs/ dumpAst/build/libs/ dumpAstWithPlantuml/build/libs/
```
Those JARs can then be copied to your project, e.g. for grammar2uml.
```bash
cp grammar2uml/build/libs/grammar2uml-<version>.jar ../your-project/libs/grammar2uml.jar
cd ../your-project/
```
Finally, this JAR has to be integrated into your build process. In case, [Gradle](https://gradle.org/) is used, the JAR file needs to be added as dependency using:
```groovy
dependencies {
implementation fileTree(include: ['grammar2uml.jar'], dir: 'libs')
implementation fileTree(include: ['dumpAst.jar'], dir: 'libs')
}
```
The path to the JAR file may need to be changed according to your project structure.
In case of `grammar2uml` a task needs to be created, similar to the one defined [above](#grammar2uml).
```groovy
task grammar2uml(type: JavaExec) {
main = '-jar'
args([
'../libs/grammar2uml.jar',
'--verbose',
'src/main/jastadd/GoalModel.relast'
])
}
```
pages/dumpAst.md
View file @ 48fc8dff
# DumpAst
The tool called [`DumpAst`](https://git-st.inf.tu-dresden.de/jastadd/relast2uml/-/tree/master/dumpAst) is used to create a snapshot of an AST and visualize it.
The tool called `DumpAst` ([see in repo](https://git-st.inf.tu-dresden.de/jastadd/relast2uml/-/tree/master/dumpAst)) is used to create a snapshot of an AST and visualize it.
![](_static/dumpAst.png)
It has to be used within your application code, and comes with a fluent interface to add and/or filter parts of the AST.
First, import the entry point class `Dumper`
```java
import de.tudresden.inf.st.jastadd.dumpAst.ast.Dumper;
```
Then, read in the ASTnode in question:
```java
Dumper.read(astNode)
```
Using the return value, the following methods are supported and can be chained together.
| Name | Description |
|---------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| customPreamble | Add the given string as preamble to the visualization. |
| disableTypes | Disable all objects with types matching at least one of the given regex strings. Disabled objects won't be included in any output. However, their children are still processed. |
| dumpAsPNG | Write out content as PNG image generated by plantuml. (**Only available in dumpAstWithPlantuml**) |
| dumpAsSource | Write out content as plantuml source code |
| dumpAsSVG | Write out content as SVG image generated by plantuml. (**Only available in dumpAstWithPlantuml**) |
| dumpAsYaml | Write out content as YAML representation of the ASTNode |
| enableDebug | Add debug information in dumped content, mainly version numbers. |
| excludeAttributesFor | *experimental, documentation missing* |
| excludeChildren | Exclude every child whose name (i.e., context) matches at least on of the given regex strings. This means, that the complete object and its (transitive) children will never be included in any output. |
| excludeChildrenFor | *experimental, documentation missing* |
| excludeNonterminalAttributesFor | *experimental, documentation missing* |
| excludeRelations | Exclude every relation whose role-name matches at least on of the given regex strings. This means two things: a) the relation to any potential target object(s) is never shown, and b) the target object(s) are not shown unless they are reachable by another relation or by containment. |
| excludeRelationsFor | *experimental, documentation missing* |
| excludeTokens | Exclude tokens and their value if the token name matches at least one of the given regex strings. |
| excludeTokensFor | *experimental, documentation missing* |
| includeAttributes | Include attributes (as tokens) and their value if the attribute name matches at least on of the given regex strings. |
| includeAttributesFor | *experimental, documentation missing* |
| includeChildrenFor | *experimental, documentation missing* |
| includeEmptyStringsOnTokens | Include empty strings for all tokens |
| includeNonterminalAttributes | Includes nonterminal-attributes (as children) and their values if their attribute name matches at least on of the given regex strings. Note: A leading "get" and a trailing "List" in the name will be removed prior to matching. Thus, it should not be contained in the regex either. |
| includeNonterminalAttributesFor | *experimental, documentation missing* |
| includeRelationsFor | *experimental, documentation missing* |
| includeTokensFor | *experimental, documentation missing* |
| setScale | Set plantuml scale setting |
| skinParam | Add plantuml skinParam setting |
## Inclusion and Exclusion of Types
Types can be only be disabled, see `disableTypes`.
### Inclusion and Exclusion of Childrens, tokens and relations
Childrens, tokens and relations are included by default. This can be changed using exclusions and inclusion, both in general and per-type. They are applied in the following order making later conditions take precedence over the first ones.
1. Include everything as default.
2. Exclude general.
3. Include per type.
4. Exclude per type.
### Inclusion and Exclusion of Attributes
Attributes are excluded by default, i.e., not shown. This can be changed using inclusions and exclusions, both in general and per-type. They are applied in the following order making later conditions take precedence over the first ones.
1. Exclude everything as default.
2. Include general.
3. Exclude per type.
4. Include per type
pages/grammar2uml.md
View file @ 48fc8dff
# Grammar2Uml
The tool called [`Grammar2Uml`](https://git-st.inf.tu-dresden.de/jastadd/relast2uml/-/tree/master/grammar2uml) takes a set of grammar specifications and creates a visualization similar to UML class diagrams.
The tool called `Grammar2Uml` ([see in repo](https://git-st.inf.tu-dresden.de/jastadd/relast2uml/-/tree/master/grammar2uml)) takes a set of grammar specifications and creates a visualization similar to UML class diagrams.
![](_static/grammar2uml.png)
![](_static/minimal-example.png)
Every nonterminal will be shown as a rectangular box with its terminal children listed within it. Children are shown as containment relations between parent and child, whereas relations and intrinsic references are shown using arrows.
Furthermore, some options may be specified.
| Name | Required (Default) | Description |
|----------------------|--------------------|-------------------------------------------------------------------------|
| `--output` | No (`uml.md`) | target file to be generated. |
| `--inputGrammar2Uml` | No | grammar2uml definition file, see [below](#grammar2uml-definition-file). |
| `--defaultFolders` | No (`false`) | Creates a default folder per grammar file. |
| `--help` | No | Print usage and exit. |
| `--version` | No | Print version and exit. |
| `--verbose` | No | Print more messages while compiling. |
## Grammar2uml definition file
To structure the generated visualization, any number of nonterminals can be grouped with folders.
Either specify the option `--defaultFolders` to use one folder per input grammar file, or specify a grammar2uml definition file.
The definition file has a simple syntax, it is a list of folder specifications. One specifications looks like
```
folder FOLDER_NAME : NT1, NT2, ..., NT_n
```
It produces one folder named `FOLDER_NAME` containing all nonterminals (`NT1`, `NT2`, ..., `NT_n`) following it.
pages/index.rst
View file @ 48fc8dff
......@@ -14,6 +14,7 @@ Relast2Uml Documentation
dumpAst.md
grammar2uml.md
adding.md
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment