2.0.1

- add more documentation on using
- make filter method using regexes deprecated

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).
    *

dumpAst.base/src/main/resources/dumpAstVersion.properties

-#Thu Sep 08 16:46:11 CEST 2022
-version=2.0.0
+#Fri Sep 30 12:44:09 CEST 2022
+version=2.0.1

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 {

pages/docs/index.md

 # 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)
 
@@ -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.

pages/docs/using.md

+# 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
+

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: