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`.
For filtering the output, there are various lambda functions (`include___`).
Those methods are available for children, attributes, relations and tokens.
The methods using lambda functions are preferred, as they are more powerful.
By default, all children, relations and tokens are included in the output, whereas all attributes are excluded.
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())`).
- (3) [Optional] You can only include nodes of certain types by using `includeChild` 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.
- (4) and (5) [Optional] To style a node, the `style` is used. It accepts a lambda function, in which the style of every node can be customized by calling methods on the given `Style` object, e.g. setting the name (5) or background color (6). The default name is to use the class name along with the hashcode of the object (`node == null ? "null" : node.getClass().getSimpleName() + "@" + Integer.toHexString(node.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.
- (7), (8) and (9) To create an output image, use `dumpAsPng` for PNG (`dumpAsSVG` for SVG). 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. Alternatively to a file, the result can be written to a given `OutputStream` (9).
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.
