diff --git a/dumpAst.base/src/main/java/de/tudresden/inf/st/jastadd/dumpAst/ast/DumpBuilder.java b/dumpAst.base/src/main/java/de/tudresden/inf/st/jastadd/dumpAst/ast/DumpBuilder.java index ed87cf24a45c0d9c8cda43c612c4450080fc8504..1e7109889b014f8a1691d98a46fc5356799cb502 100644 --- a/dumpAst.base/src/main/java/de/tudresden/inf/st/jastadd/dumpAst/ast/DumpBuilder.java +++ b/dumpAst.base/src/main/java/de/tudresden/inf/st/jastadd/dumpAst/ast/DumpBuilder.java @@ -16,33 +16,7 @@ import java.util.function.Supplier; import static de.tudresden.inf.st.jastadd.dumpAst.ast.ASTNode.matches; /** - * Building a dump. - * <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> + * Creating a snapshot of an AST. */ @SuppressWarnings("UnusedReturnValue") public class DumpBuilder { @@ -203,6 +177,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeTokens(String regex, String... moreRegexes) { updateRegexes(() -> buildConfig.getGlobalPatternCollection().getTokenPattern(), s -> buildConfig.getGlobalPatternCollection().setTokenPattern(s), @@ -221,6 +196,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeTokensFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); updateRegexes(collection::getTokenPattern, @@ -240,6 +216,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder includeTokensFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); updateRegexes(collection::getTokenPattern, @@ -269,6 +246,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeChildren(String regex, String... moreRegexes) { updateRegexes(() -> buildConfig.getGlobalPatternCollection().getChildPattern(), s -> buildConfig.getGlobalPatternCollection().setChildPattern(s), @@ -288,6 +266,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeChildrenFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); updateRegexes(collection::getChildPattern, @@ -308,6 +287,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder includeChildrenFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); updateRegexes(collection::getChildPattern, @@ -336,6 +316,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder includeAttributes(String regex, String... moreRegexes) { updateRegexes(() -> buildConfig.getGlobalPatternCollection().getAttributePattern(), s -> buildConfig.getGlobalPatternCollection().setAttributePattern(s), @@ -354,6 +335,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder includeAttributesFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); updateRegexes(collection::getAttributePattern, @@ -373,6 +355,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeAttributesFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); updateRegexes(collection::getAttributePattern, @@ -397,6 +380,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder includeNonterminalAttributes(String regex, String... moreRegexes) { updateRegexes(() -> buildConfig.getGlobalPatternCollection().getNonterminalAttributePattern(), s -> buildConfig.getGlobalPatternCollection().setNonterminalAttributePattern(s), @@ -419,6 +403,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder includeNonterminalAttributesFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); updateRegexes(collection::getNonterminalAttributePattern, @@ -442,6 +427,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeNonterminalAttributesFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); updateRegexes(collection::getNonterminalAttributePattern, @@ -472,6 +458,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeRelations(String regex, String... moreRegexes) { updateRegexes(() -> buildConfig.getGlobalPatternCollection().getRelationPattern(), s -> buildConfig.getGlobalPatternCollection().setRelationPattern(s), @@ -492,6 +479,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder excludeRelationsFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateExcludePatternCollection(typeRegex); updateRegexes(collection::getRelationPattern, @@ -513,6 +501,7 @@ public class DumpBuilder { * @return this * @see java.util.regex.Pattern#compile(String) */ + @Deprecated(since = "2.0.1") public DumpBuilder includeRelationsFor(String typeRegex, String regex, String... moreRegexes) { PatternCollection collection = findOrCreateIncludePatternCollection(typeRegex); updateRegexes(collection::getRelationPattern, @@ -523,7 +512,6 @@ public class DumpBuilder { // --- Settings --- - /** * Omit children that are <code>null</code> (in a full AST, there are no such nodes). * diff --git a/dumpAst.base/src/main/resources/dumpAstVersion.properties b/dumpAst.base/src/main/resources/dumpAstVersion.properties index 810cb294c4f21dbbf55024b562596a4775489dbd..89cf2e4268a710501294ca2f9d799c81f6ffa8ff 100644 --- a/dumpAst.base/src/main/resources/dumpAstVersion.properties +++ b/dumpAst.base/src/main/resources/dumpAstVersion.properties @@ -1,2 +1,2 @@ -#Thu Sep 08 16:46:11 CEST 2022 -version=2.0.0 +#Fri Sep 30 12:44:09 CEST 2022 +version=2.0.1 diff --git a/pages/docs/adding.md b/pages/docs/adding.md index 2e2f9a84375a501e95467de1af6bd37e7f53d265..6e0f2ca5ee70f1a4bef6ff2a1fc436d1c056a45d 100644 --- a/pages/docs/adding.md +++ b/pages/docs/adding.md @@ -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. -Set up the maven package source as repository: +Set up the maven package source as a repository: ``` repositories { diff --git a/pages/docs/index.md b/pages/docs/index.md index 0910060203c01660960cf1904dcb8fe0a5ee3537..3d61a112efba6697ffab2feda8a1ff0b859ff515 100644 --- a/pages/docs/index.md +++ b/pages/docs/index.md @@ -1,6 +1,6 @@ # 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.  @@ -17,6 +17,6 @@ Then, read in the ASTNode in question: 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. -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. diff --git a/pages/docs/using.md b/pages/docs/using.md new file mode 100644 index 0000000000000000000000000000000000000000..fcf25518454650213f62c9f6f026268cf086cfa2 --- /dev/null +++ b/pages/docs/using.md @@ -0,0 +1,86 @@ +# 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 + diff --git a/pages/mkdocs.yml b/pages/mkdocs.yml index ac59250d32152419ed9a44f44d83207f2d954397..69ac30ba6196e116e9a55e81b193ff2b2d952d53 100644 --- a/pages/mkdocs.yml +++ b/pages/mkdocs.yml @@ -5,6 +5,7 @@ site_dir: ../public nav: - "DumpAst": index.md - "Add to your project": adding.md + - "Using DumpAst": using.md - "API documentation": ragdoc/index.html theme: