Skip to content
Snippets Groups Projects
Commit e7622121 authored by René Schöne's avatar René Schöne
Browse files

2.0.1

- add more documentation on using
- make filter method using regexes deprecated
parent 68ab2cc9
Branches
No related tags found
1 merge request!133.0.1
Pipeline #14722 passed
...@@ -16,33 +16,7 @@ import java.util.function.Supplier; ...@@ -16,33 +16,7 @@ import java.util.function.Supplier;
import static de.tudresden.inf.st.jastadd.dumpAst.ast.ASTNode.matches; import static de.tudresden.inf.st.jastadd.dumpAst.ast.ASTNode.matches;
/** /**
* Building a dump. * Creating a snapshot of an AST.
* <p>
*
* <h3>Inclusion and Exclusion of Types</h3>
* Types can be only be disabled, see {@link #disableTypes(String, String...)}.
*
* <h3>Inclusion and Exclusion of children, tokens and relations</h3>
* Children, 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.
* <ol>
* <li>Include everything as default.
* <li>Exclude general.
* <li>Include per type.
* <li>Exclude per type.
* </ol>
*
* <h3>Inclusion and Exclusion of Attributes</h3>
* 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.
* <ol>
* <li> Exclude everything as default.
* <li> Include general.
* <li> Exclude per type.
* <li> Include per type
* </ol>
*/ */
@SuppressWarnings("UnusedReturnValue") @SuppressWarnings("UnusedReturnValue")
public class DumpBuilder { public class DumpBuilder {
...@@ -203,6 +177,7 @@ public class DumpBuilder { ...@@ -203,6 +177,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeTokens(String regex, String... moreRegexes) { public DumpBuilder excludeTokens(String regex, String... moreRegexes) {
updateRegexes(() -> buildConfig.getGlobalPatternCollection().getTokenPattern(), updateRegexes(() -> buildConfig.getGlobalPatternCollection().getTokenPattern(),
s -> buildConfig.getGlobalPatternCollection().setTokenPattern(s), s -> buildConfig.getGlobalPatternCollection().setTokenPattern(s),
...@@ -221,6 +196,7 @@ public class DumpBuilder { ...@@ -221,6 +196,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeTokensFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder excludeTokensFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex);
updateRegexes(collection::getTokenPattern, updateRegexes(collection::getTokenPattern,
...@@ -240,6 +216,7 @@ public class DumpBuilder { ...@@ -240,6 +216,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder includeTokensFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder includeTokensFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex);
updateRegexes(collection::getTokenPattern, updateRegexes(collection::getTokenPattern,
...@@ -269,6 +246,7 @@ public class DumpBuilder { ...@@ -269,6 +246,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeChildren(String regex, String... moreRegexes) { public DumpBuilder excludeChildren(String regex, String... moreRegexes) {
updateRegexes(() -> buildConfig.getGlobalPatternCollection().getChildPattern(), updateRegexes(() -> buildConfig.getGlobalPatternCollection().getChildPattern(),
s -> buildConfig.getGlobalPatternCollection().setChildPattern(s), s -> buildConfig.getGlobalPatternCollection().setChildPattern(s),
...@@ -288,6 +266,7 @@ public class DumpBuilder { ...@@ -288,6 +266,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeChildrenFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder excludeChildrenFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex);
updateRegexes(collection::getChildPattern, updateRegexes(collection::getChildPattern,
...@@ -308,6 +287,7 @@ public class DumpBuilder { ...@@ -308,6 +287,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder includeChildrenFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder includeChildrenFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex);
updateRegexes(collection::getChildPattern, updateRegexes(collection::getChildPattern,
...@@ -336,6 +316,7 @@ public class DumpBuilder { ...@@ -336,6 +316,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder includeAttributes(String regex, String... moreRegexes) { public DumpBuilder includeAttributes(String regex, String... moreRegexes) {
updateRegexes(() -> buildConfig.getGlobalPatternCollection().getAttributePattern(), updateRegexes(() -> buildConfig.getGlobalPatternCollection().getAttributePattern(),
s -> buildConfig.getGlobalPatternCollection().setAttributePattern(s), s -> buildConfig.getGlobalPatternCollection().setAttributePattern(s),
...@@ -354,6 +335,7 @@ public class DumpBuilder { ...@@ -354,6 +335,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder includeAttributesFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder includeAttributesFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex);
updateRegexes(collection::getAttributePattern, updateRegexes(collection::getAttributePattern,
...@@ -373,6 +355,7 @@ public class DumpBuilder { ...@@ -373,6 +355,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeAttributesFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder excludeAttributesFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex);
updateRegexes(collection::getAttributePattern, updateRegexes(collection::getAttributePattern,
...@@ -397,6 +380,7 @@ public class DumpBuilder { ...@@ -397,6 +380,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder includeNonterminalAttributes(String regex, String... moreRegexes) { public DumpBuilder includeNonterminalAttributes(String regex, String... moreRegexes) {
updateRegexes(() -> buildConfig.getGlobalPatternCollection().getNonterminalAttributePattern(), updateRegexes(() -> buildConfig.getGlobalPatternCollection().getNonterminalAttributePattern(),
s -> buildConfig.getGlobalPatternCollection().setNonterminalAttributePattern(s), s -> buildConfig.getGlobalPatternCollection().setNonterminalAttributePattern(s),
...@@ -419,6 +403,7 @@ public class DumpBuilder { ...@@ -419,6 +403,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder includeNonterminalAttributesFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder includeNonterminalAttributesFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex);
updateRegexes(collection::getNonterminalAttributePattern, updateRegexes(collection::getNonterminalAttributePattern,
...@@ -442,6 +427,7 @@ public class DumpBuilder { ...@@ -442,6 +427,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeNonterminalAttributesFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder excludeNonterminalAttributesFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex);
updateRegexes(collection::getNonterminalAttributePattern, updateRegexes(collection::getNonterminalAttributePattern,
...@@ -472,6 +458,7 @@ public class DumpBuilder { ...@@ -472,6 +458,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeRelations(String regex, String... moreRegexes) { public DumpBuilder excludeRelations(String regex, String... moreRegexes) {
updateRegexes(() -> buildConfig.getGlobalPatternCollection().getRelationPattern(), updateRegexes(() -> buildConfig.getGlobalPatternCollection().getRelationPattern(),
s -> buildConfig.getGlobalPatternCollection().setRelationPattern(s), s -> buildConfig.getGlobalPatternCollection().setRelationPattern(s),
...@@ -492,6 +479,7 @@ public class DumpBuilder { ...@@ -492,6 +479,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder excludeRelationsFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder excludeRelationsFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex);
updateRegexes(collection::getRelationPattern, updateRegexes(collection::getRelationPattern,
...@@ -513,6 +501,7 @@ public class DumpBuilder { ...@@ -513,6 +501,7 @@ public class DumpBuilder {
* @return this * @return this
* @see java.util.regex.Pattern#compile(String) * @see java.util.regex.Pattern#compile(String)
*/ */
@Deprecated(since = "2.0.1")
public DumpBuilder includeRelationsFor(String typeRegex, String regex, String... moreRegexes) { public DumpBuilder includeRelationsFor(String typeRegex, String regex, String... moreRegexes) {
PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex);
updateRegexes(collection::getRelationPattern, updateRegexes(collection::getRelationPattern,
...@@ -523,7 +512,6 @@ public class DumpBuilder { ...@@ -523,7 +512,6 @@ public class DumpBuilder {
// --- Settings --- // --- Settings ---
/** /**
* Omit children that are <code>null</code> (in a full AST, there are no such nodes). * Omit children that are <code>null</code> (in a full AST, there are no such nodes).
* *
......
#Thu Sep 08 16:46:11 CEST 2022 #Fri Sep 30 12:44:09 CEST 2022
version=2.0.0 version=2.0.1
...@@ -4,7 +4,7 @@ Check the [package overview page](https://git-st.inf.tu-dresden.de/jastadd/dumpA ...@@ -4,7 +4,7 @@ Check the [package overview page](https://git-st.inf.tu-dresden.de/jastadd/dumpA
To use `dumpAst`, adjust your `build.gradle` as follows. To use `dumpAst`, adjust your `build.gradle` as follows.
Set up the maven package source as repository: Set up the maven package source as a repository:
``` ```
repositories { repositories {
......
# DumpAst # DumpAst
The tool called `DumpAst` ([see in repo](https://git-st.inf.tu-dresden.de/jastadd/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/dumpAst)) is used to create a snapshot of an AST and visualise it.
![](img/dumpAst.png) ![](img/dumpAst.png)
...@@ -17,6 +17,6 @@ Then, read in the ASTNode in question: ...@@ -17,6 +17,6 @@ Then, read in the ASTNode in question:
Dumper.read(astNode) Dumper.read(astNode)
``` ```
Using the return value (a `DumpBuilder`), use methods to filter out unwanted parts, add styling or other settings. Using the return value (a `DumpBuilder`), use methods to filter out unwanted parts and add styling or other settings.
All methods can be chained together. All methods can be chained together.
Please see the [API documentation](ragdoc/index.html) for more details. Please see [the subpage on using DumpAst](using.md) and the [API documentation](ragdoc/index.html) for more details.
# Using DumpAst
After [adding DumpAst to your project](adding.md), you can start getting snapshot of some (part of an) AST.
Here is one example with a `Model` containing nodes of type `Robot`, `Joint` and `EndEffector` amongst others.
It is explained in detail below.
```java
import de.tudresden.inf.st.jastadd.dumpAst.ast.*;
import your.model.Robot;
import your.model.Model;
import your.model.ASTNode;
import java.io.IOException;
import java.nio.file.Path;
import java.nio.file.Paths;
public class Main {
public static void main(String[] args) throws IOException, TransformationException {
Model model = createModel(); // (1)
DumpBuilder builder = Dumper.read(model) // (2)
.includeChildWhen((parentNode, childNode, contextName) -> {
if (parentNode instanceof Robot && ((Robot) parentNode).getName().equals("Robot2")) {
return false;
}
return !contextName.equals("EndEffector");
}) // (3)
.includeAttributes("*go")
.excludeAttributes("logo")
.includeAttributesFor("logo", "Robot") // (4)
.setNameMethod(node -> node.getClass().getSimpleName()) // (5)
.setBackgroundColorMethod<ASTNode>(node -> node.size() > 30 ? "blue" : "white")
.skinParam(SkinParamBooleanSetting.Shadowing, false); // (6)
builder.dumpAsPng(Paths.get("featureTest.png")); // (7)
builder.dumpAsSVG(Paths.get("featureTest.svg")); // (8)
}
}
```
DumpAst uses the [Builder design pattern](https://en.wikipedia.org/wiki/Builder_pattern) as well as a [fluent API](https://en.wikipedia.org/wiki/Fluent_interface).
That means, first, all settings are specified (2-6), and only after a "dump"-method is called (7,8) the actual snapshot is taken.
For filtering the output, there are two ways: using lambda functions (`include___When` methods) and using include/exclude mechanism (`include___`, `include___For`, `exclude___`, `exclude___For`).
The latter has been deprecated since `2.0.1`.
Those methods are available for children, attributes, relations and tokens.
The methods using lambda functions are preferred, as they are more powerful.
The steps in detail:
- (1) In the beginning, your model is somehow constructed and changed. This is indicated with the method `createModel`.
- (2) The first call is always `Dumper.read()` to which the (part of the) AST is provided as an argument. It returns an object of type [DumpBuilder](/ragdoc/#/type/DumpBuilder). With this object, the output can be changed.
- (3) [Optional] You can only include nodes of certain types by using `includeChildWhen` and passing a lambda function, which is called for every node and should return `true` if the `childNode` shall be included in the output. It defaults to returning `true` for every node. Here, all children of a `Robot` node (except if the name of the robot is `"Robot2"`) and all children of the context named `"EndEffector"` are excluded. This way of configuring the output is the preferred one.
- (4) [Optional] The alternative (legacy) mechanism for inclusion and exclusion is described at [DumpBuilder](/ragdoc/#/type/DumpBuilder). Attributes are excluded per default. Here, an attribute whose name ends with `"go"` is included. However, it is excluded again when it is named `"logo"`, except for nodes of type `Robot` where it is included (again).
- (5) [Optional] To use a different name for nodes, use `setNameMethod`. The default is to use the class name along with the hashcode of the object (`n -> n == null ? "null" : n.getClass().getSimpleName() + "@" + Integer.toHexString(n.hashCode())`).
- (6) [Optional] There are a few ways to style the output in general through [SkinParam](https://plantuml.com/de/skinparam). Not all of those parameters are supported; see `SkinParamBooleanSetting` and `SkinParamStringSetting`.
- (7) and (8) To create a PNG image, use `dumpAsPng` (for SVG, use `dumpAsSVG`). Those methods do not return the builder object, as they produce an output. They potentially throw two kinds of exception: `IOException` (when the file could not be written) and `TransformationException` (when the AST could not be processed). As shown here, the builder object must be stored in a variable to create multiple outputs.
To summarise the required steps: Specify the AST to read in, configure the output, and write ("dump") the output.
For more configuration options, please consult the [API Docs of DumpBuilder](/ragdoc/#/type/DumpBuilder).
## (Deprecated) Inclusion and Exclusion of Types
Types can only be disabled; see `disableTypes(String, String...)` in the [API Docs of DumpBuilder](/ragdoc/#/type/DumpBuilder).
### Inclusion and Exclusion of children, tokens and relations
Children, 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.
1. Exclude general.
1. Include per type.
1. 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.
1. Include general.
1. Exclude per type.
1. Include per type
...@@ -5,6 +5,7 @@ site_dir: ../public ...@@ -5,6 +5,7 @@ site_dir: ../public
nav: nav:
- "DumpAst": index.md - "DumpAst": index.md
- "Add to your project": adding.md - "Add to your project": adding.md
- "Using DumpAst": using.md
- "API documentation": ragdoc/index.html - "API documentation": ragdoc/index.html
theme: theme:
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment