Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Henshin/Parameters"

(Usage during execution: Add screenshot of Interpreter Wizard)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Category:Henshin]][[Category:Modeling]]
 +
 
'''Parameters''' allow to shape the behavior of [[Henshin/Units|units]], including rules, with variable information.
 
'''Parameters''' allow to shape the behavior of [[Henshin/Units|units]], including rules, with variable information.
 
A unit can have an arbitary number of parameters.
 
A unit can have an arbitary number of parameters.
Line 6: Line 8:
  
 
The kind specifies the time when the parameter is bound to a concrete value, and whether the parameter is intended to be accessed after the unit has been applied.
 
The kind specifies the time when the parameter is bound to a concrete value, and whether the parameter is intended to be accessed after the unit has been applied.
There are four parameter kinds (''in'', ''out'', ''inout'', ''var'') and an additional legacy parameter kind (''unknown'')
+
There are four parameter kinds (''in'', ''out'', ''inout'', ''var'') and an additional legacy parameter kind (''unknown'').
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 18: Line 20:
 
! UNKOWN
 
! UNKOWN
 
|-
 
|-
! settable before application
+
! must be set externally before application
 
| style="text-align:center;background-color:#afa" | x
 
| style="text-align:center;background-color:#afa" | x
 
| style="background-color:#faa" |
 
| style="background-color:#faa" |
 
| style="text-align:center;background-color:#afa" | x
 
| style="text-align:center;background-color:#afa" | x
 
| style="background-color:#faa" |
 
| style="background-color:#faa" |
| style="text-align:center;background-color:#afa" | x
+
| style="text-align:center;background-color:#afa" | (x)
 
|-
 
|-
! settable during application
+
! must be set during application
 
| style="background-color:#faa" |
 
| style="background-color:#faa" |
 
| style="text-align:center;background-color:#afa" | x
 
| style="text-align:center;background-color:#afa" | x
 
| style="background-color:#faa" |
 
| style="background-color:#faa" |
 
| style="text-align:center;background-color:#afa" | x
 
| style="text-align:center;background-color:#afa" | x
| style="text-align:center;background-color:#afa" | x
+
| style="text-align:center;background-color:#afa" | (x)
 
|-
 
|-
 
! readable after application
 
! readable after application
 
| style="background-color:#faa" |
 
| style="background-color:#faa" |
 
| style="text-align:center;background-color:#afa" | x
 
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | (x)
 +
|}
 +
 +
Examples:  [[Henshin/Getting started|Bank Accounts]] (''in'', ''var''), [[Henshin/Examples/Ecore2RDB|Ecore2RDB]] (''in'', ''out'', ''var''), [[Henshin/Examples/Ecore2GenModel|Ecore2GenModel]] (''in'', ''out'', ''var''),  [[Henshin/Examples/GridAndCombPattern|Grid and Comb Pattern]] (''in'', ''inout'', ''out''), [[Henshin/Examples/GossipingGirls|Gossiping Girls]] (''out''), [[Henshin/Examples/ProbabilisticBroadcast|Probabilistic Broadcast]], (''in'', ''var'')
 +
 +
== Parameter mappings ==
 +
 +
Parameters that need to be set externally can be set by the user using the [[#Interpreter_API|API]] or the [[#Interpreter_Wizard|Interpreter Wizard]].
 +
In addition, they can be passed in from another unit using a '''parameter mapping'''.
 +
A parameter mapping assigns a source parameter to a target parameter between a unit and its sub-unit.
 +
Parameters that need to be set automatically during unit application are either set during the match finding process (in the case of LHS elements) or after the creation of new elements (in the case of RHS elements).
 +
This behavior can be used to propagate values between LHS and RHS elements, as exemplified in the ''transferMoney'' rule in the [[Henshin/Getting started|Bank Accounts]] example.
 +
 +
{| class="wikitable"
 +
|+Allowed mappings
 +
|-
 +
! From → / to ↓
 +
! IN
 +
! OUT
 +
! INOUT
 +
! VAR
 +
|-
 +
! IN
 
| style="text-align:center;background-color:#afa" | x
 
| style="text-align:center;background-color:#afa" | x
 
| style="background-color:#faa" |
 
| style="background-color:#faa" |
 
| style="text-align:center;background-color:#afa" | x
 
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
|-
 +
! OUT
 +
| style="background-color:#faa" |
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
|-
 +
! INOUT
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
|-
 +
! VAR
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="text-align:center;background-color:#afa" | x
 +
| style="background-color:#faa" |
 
|}
 
|}
 +
 +
The legacy parameter kind ''unknown'' can be mapped arbitrarily depending on its usage.
 +
 +
Examples:  [[Henshin/Examples/Ecore2RDB|Ecore2RDB]] (''in''→''in'', ''out''→''out''),  [[Henshin/Examples/Ecore2GenModel|Ecore2GenModel]] (''in''→''in'', ''out''→''out''), [[Henshin/Examples/GridAndCombPattern|Grid and Comb Pattern]] (''in''→''in'', ''out''→''out'', ''in''→''inout'', ''inout''→''in'', ''inout''→''out'')
  
 
== Usage during definition ==
 
== Usage during definition ==
Line 44: Line 94:
 
Parameters can be created using the tree-based or the [[Henshin/Graphical Editor|graphical]] editor.
 
Parameters can be created using the tree-based or the [[Henshin/Graphical Editor|graphical]] editor.
 
They can be edited using the latter or the ''Properties'' view.
 
They can be edited using the latter or the ''Properties'' view.
 +
 +
Declared parameters are used inside the unit by referencing them by name.
 +
Parameters can be used at any place in the unit where a string value is expected:
 +
in rules, this is the case for node names, attribute values, edge indices, and attribute conditions.
 +
In [[Henshin/Units#Iterated_Unit|iterated units]], this is the case for the iterations condition.
  
 
=== Parameter creation and editing in graphical editor ===
 
=== Parameter creation and editing in graphical editor ===
Line 51: Line 106:
 
To create or edit a parameter with the [[Henshin/Graphical Editor|graphical editor]] open the according ''*.henshin_diagram'' file.
 
To create or edit a parameter with the [[Henshin/Graphical Editor|graphical editor]] open the according ''*.henshin_diagram'' file.
 
Select the name of a unit or rule by clicking on it.
 
Select the name of a unit or rule by clicking on it.
Click a second time to edit the title.
+
Click a second time to edit the name.
You can now text-based add, edit and remove parameters which follow the unit/rule name -- encompassed by parentheses and separated by commas.
+
You can now - text-based - add, edit and remove parameters which follow the unit/rule name encompassed by parentheses and separated by commas.
 
The parameter entries adhere to the following scheme: ''<kind> <name>:<type>'' .
 
The parameter entries adhere to the following scheme: ''<kind> <name>:<type>'' .
 +
Both ''kind'' and ''type'' are optional.
 +
If you omit a ''kind'' the parameter kind will be ''unknown''.
  
 
=== Parameter creation in tree-based editor ===
 
=== Parameter creation in tree-based editor ===
  
[[File:Henshin Parameters Creation TreeEditor.png]]
+
[[File:Henshin Parameters Creation TreeEditor.png|600px]]
  
 
To create a parameter with the tree-based editor open the according ''*.henshin''-file.
 
To create a parameter with the tree-based editor open the according ''*.henshin''-file.
Line 65: Line 122:
 
=== Parameter editing in properties view ===
 
=== Parameter editing in properties view ===
  
[[File:Henshin Parameters Editing PropertiesView.png]]
+
[[File:Henshin Parameters Editing PropertiesView.png|350px]]
  
 
In the ''Properties'' view you can edit a parameter after selecting it in the tree-based editor.
 
In the ''Properties'' view you can edit a parameter after selecting it in the tree-based editor.
 
To edit a value click in the according row of the ''Value'' column.
 
To edit a value click in the according row of the ''Value'' column.
  
=== Parameter mapping ===
+
=== Parameter mapping creation ===
  
[[File:Henshin ParameterMapping Creation TreeEditor.png|600px]]
+
In the graphical editor parameter mappings are maintained implicitly based on overlapping parameter names:
 +
each parameter of a unit is mapped to all parameters of the same name in all sub-units;
 +
mappings in the opposite direction exist as well.
  
You can define parameter mappings to pass parameters between a unit and its sub-unit(s).
+
[[File:Henshin ParameterMapping Creation TreeEditor.png|500px]]
A mappings is implicitly defined when using the same name for two parameters.
+
 
Mappings for parameters with different names can be created manually using the tree-based editor.
+
Using the tree-based editor mappings for parameters can be created manually.
 
Therefore right-click the unit and select ''New Child → Parameter Mapping''.
 
Therefore right-click the unit and select ''New Child → Parameter Mapping''.
 
The mapping can be edited using its ''Properties'' view.
 
The mapping can be edited using its ''Properties'' view.
Line 84: Line 143:
 
== Usage during execution ==
 
== Usage during execution ==
  
Before unit or rule execution parameters of kind ''in'' and ''inout'' have to be set.
+
Before unit or rule execution parameters of kind ''in'' and ''inout'' have to be set externally.
Parameters of kind ''unknown'' may be set depending on their usage in their units/rules.
+
Parameters of kind ''unknown'' may be set externally depending on their usage in their units/rules.
 
This can be done using the [[Henshin/Interpreter#Interpreter_Wizard|Interpreter Wizard]] or the [[Henshin/Interpreter#Interpreter_API|Interpreter API]].
 
This can be done using the [[Henshin/Interpreter#Interpreter_Wizard|Interpreter Wizard]] or the [[Henshin/Interpreter#Interpreter_API|Interpreter API]].
  
Line 98: Line 157:
 
=== Interpreter API ===
 
=== Interpreter API ===
  
<Code von anderer Wiki-Seite>
+
See ''Setting and Getting Parameter Values'' in [[Henshin/Interpreter#Transforming_and_more]].
 +
 
 +
== Remarkable usage examples ==
 +
 
 +
There may be some use cases for parameters, which do not obviously emerge from the documentation so far.
 +
The following sections will describe a variety of those use cases.
 +
 
 +
=== Populate values between sub-units ===
 +
 
 +
A common use case for parameters in sequential units is the passing of values between sub-units.
 +
This can be done with any parameter kind in the sequential unit to which the according units are sub-units.
 +
If you do not intend to use the value outside the unit, you should use the parameter kind ''var''.
 +
 
 +
[[File:Henshin_Parameters_Usage_Example.png|thumb|right|Usage example for parameters]]
 +
 
 +
In the example unit ''getFatherCreateChild'' the parameter ''temp'' stores the intermediate result mapped from ''getNode'''s ''out'' parameter.
 +
The ''var'' parameter ''temp'' is then mapped to ''createChild'''s ''in'' parameter.
 +
Further parameter passings between sub-units can reuse the same ''var'' parameter as an intermediate step to a subsequent sub-unit.
 +
 
 +
=== Alter parameter value during rule application ===
 +
 
 +
Especially when using the parameter kind ''inout'' you may want to alter the parameter value during rule application to output another value different from the input.
 +
While this is easily achievable for units by the use of parameter mappings, the approach for rules is less obvious.
 +
 
 +
In the depicted example the rule ''createChild'' has the parameter ''param'' of type ''Node'' and is of the parameter kind ''inout''.
 +
It creates a new node as child of the node passed in via ''param''.
 +
The notation "param->?:Node" in the preserved node indicates that this node is referred to by the name ''param'' before the transformation and is nameless afterwards.
 +
The newly created child node is assigned to the name ''param'' after the transformation.
 +
This automatically creates a parameter mapping to the rule's ''inout'' parameter of the same name.
 +
Overall the ''inout'' parameter's input value is replaced with the new child node.
 +
 
 +
Please note that you can only assign nodes to an already set parameter.
 +
It is not possible to assign the value of a node attribute to an already set parameter.
 +
 
 +
For an additional usage illustration, consider the rule ''extendColumn'' in the section ''Generation of a sparse grid'' of the [[Henshin/Examples/GridAndCombPattern|Grid and Comb Pattern]] example.

Latest revision as of 14:20, 12 February 2023


Parameters allow to shape the behavior of units, including rules, with variable information. A unit can have an arbitary number of parameters. Parameters have a name, a description, a kind, and, optionally, a type.

Parameter kinds

The kind specifies the time when the parameter is bound to a concrete value, and whether the parameter is intended to be accessed after the unit has been applied. There are four parameter kinds (in, out, inout, var) and an additional legacy parameter kind (unknown).

Feature comparison
Parameter kind IN OUT INOUT VAR UNKOWN
must be set externally before application x x (x)
must be set during application x x (x)
readable after application x x x (x)

Examples: Bank Accounts (in, var), Ecore2RDB (in, out, var), Ecore2GenModel (in, out, var), Grid and Comb Pattern (in, inout, out), Gossiping Girls (out), Probabilistic Broadcast, (in, var)

Parameter mappings

Parameters that need to be set externally can be set by the user using the API or the Interpreter Wizard. In addition, they can be passed in from another unit using a parameter mapping. A parameter mapping assigns a source parameter to a target parameter between a unit and its sub-unit. Parameters that need to be set automatically during unit application are either set during the match finding process (in the case of LHS elements) or after the creation of new elements (in the case of RHS elements). This behavior can be used to propagate values between LHS and RHS elements, as exemplified in the transferMoney rule in the Bank Accounts example.

Allowed mappings
From → / to ↓ IN OUT INOUT VAR
IN x x x
OUT x x x
INOUT x x x x
VAR x x x

The legacy parameter kind unknown can be mapped arbitrarily depending on its usage.

Examples: Ecore2RDB (inin, outout), Ecore2GenModel (inin, outout), Grid and Comb Pattern (inin, outout, ininout, inoutin, inoutout)

Usage during definition

Parameters can be created using the tree-based or the graphical editor. They can be edited using the latter or the Properties view.

Declared parameters are used inside the unit by referencing them by name. Parameters can be used at any place in the unit where a string value is expected: in rules, this is the case for node names, attribute values, edge indices, and attribute conditions. In iterated units, this is the case for the iterations condition.

Parameter creation and editing in graphical editor

Henshin Parameters GraphicalEditor.png

To create or edit a parameter with the graphical editor open the according *.henshin_diagram file. Select the name of a unit or rule by clicking on it. Click a second time to edit the name. You can now - text-based - add, edit and remove parameters which follow the unit/rule name encompassed by parentheses and separated by commas. The parameter entries adhere to the following scheme: <kind> <name>:<type> . Both kind and type are optional. If you omit a kind the parameter kind will be unknown.

Parameter creation in tree-based editor

Henshin Parameters Creation TreeEditor.png

To create a parameter with the tree-based editor open the according *.henshin-file. Right-click on the desired rule or unit and navigate to New Child → Parameter. You can continue with editing the parameter in its Properties view.

Parameter editing in properties view

Henshin Parameters Editing PropertiesView.png

In the Properties view you can edit a parameter after selecting it in the tree-based editor. To edit a value click in the according row of the Value column.

Parameter mapping creation

In the graphical editor parameter mappings are maintained implicitly based on overlapping parameter names: each parameter of a unit is mapped to all parameters of the same name in all sub-units; mappings in the opposite direction exist as well.

Henshin ParameterMapping Creation TreeEditor.png

Using the tree-based editor mappings for parameters can be created manually. Therefore right-click the unit and select New Child → Parameter Mapping. The mapping can be edited using its Properties view.

Henshin ParameterMapping Editing PropertiesView.png

Usage during execution

Before unit or rule execution parameters of kind in and inout have to be set externally. Parameters of kind unknown may be set externally depending on their usage in their units/rules. This can be done using the Interpreter Wizard or the Interpreter API.

Interpreter Wizard

Interpreter wizard with parameters

To set parameters using the interpreter wizard you have to open the wizard for your unit or rule of interest. In the lower part of the popup window is a table with the available parameters. You can set them by editing the cells in the Values column.

Interpreter API

See Setting and Getting Parameter Values in Henshin/Interpreter#Transforming_and_more.

Remarkable usage examples

There may be some use cases for parameters, which do not obviously emerge from the documentation so far. The following sections will describe a variety of those use cases.

Populate values between sub-units

A common use case for parameters in sequential units is the passing of values between sub-units. This can be done with any parameter kind in the sequential unit to which the according units are sub-units. If you do not intend to use the value outside the unit, you should use the parameter kind var.

Usage example for parameters

In the example unit getFatherCreateChild the parameter temp stores the intermediate result mapped from getNode's out parameter. The var parameter temp is then mapped to createChild's in parameter. Further parameter passings between sub-units can reuse the same var parameter as an intermediate step to a subsequent sub-unit.

Alter parameter value during rule application

Especially when using the parameter kind inout you may want to alter the parameter value during rule application to output another value different from the input. While this is easily achievable for units by the use of parameter mappings, the approach for rules is less obvious.

In the depicted example the rule createChild has the parameter param of type Node and is of the parameter kind inout. It creates a new node as child of the node passed in via param. The notation "param->?:Node" in the preserved node indicates that this node is referred to by the name param before the transformation and is nameless afterwards. The newly created child node is assigned to the name param after the transformation. This automatically creates a parameter mapping to the rule's inout parameter of the same name. Overall the inout parameter's input value is replaced with the new child node.

Please note that you can only assign nodes to an already set parameter. It is not possible to assign the value of a node attribute to an already set parameter.

For an additional usage illustration, consider the rule extendColumn in the section Generation of a sparse grid of the Grid and Comb Pattern example.

Back to the top