Mapping - Records and Paths
So, starting from the source tree, we have two crucial design mechanisms.
Records
The first design mechanism is implicit and simply given by the records themselves. The destination structure is traversed once per record of the source tree. This determines the structure of the destination data at the highest level. Each (partial) source tree of a record on the source side thus always generates a record with a (partial) destination tree on the destination side.
More abstractly, the records order repeating structures of the input data on the top-level. How this is done is determined by the respective parser rules and how you built your source structure. You have already seen a simple example.
Paths
The second design mechanism is used in the records on the destination side.
When generating the source tree from the source structure and the input data, a node of the source structure in a record can be generated multiple times.
As we mentioned above, each (partial) source tree of a record on the source side always generates exactly one record with a (partial) destination tree on the destination side. However, repeat structures (nodes occurring multiple times) within the source tree are not transferred directly to the destination tree! By default, only the first node is transferred!
You must explicitly initiate a repetition of a node in the destination tree by giving that node in the destination structure a path. This is done by setting the destination structure node attribute Path. Specifically, you set the path of a node of the destination structure to a node of the source structure. The node in the destination tree is then repeated exactly as often as the node in the source tree to which the path is set.
Example
That sounds a bit complicated at first, but basically, it is very simple. Let us look at the slightly modified source structure (and almost identical destination structure) of the previous example and slightly adapted input data.
ADR;Randy;Random;Mainstreet 1TEL;00498157488364TEL;00491723374222ADR;Sharon;Fillerup;Treeway 3TEL;00498157483221If everything works as we want, then we get the same number of records as in the first example, but we should get two nodes phone_number_in in the first record.
Let us take a look at the result of a mapping test with the above input data.
As you can see, it works in the source structure, but in the destination structure, we only get one node phone_number_out. And the reason for this is, as you may already suspect, that we have not set a path from the node phone_number_out to the node phone_number_in.
We now do that in the attributes of the destination node phone_number_out.
We review the result in the mapping test and see that we now have what we wanted. The twice repeated node phone_number_in from the source tree now causes the node phone_number_out in the destination tree to repeat twice as well.
Summary
So you have two mechanisms in Lobster_data to model repeating parts of the input data on the way to your output data. First, the splitting into records during parsing and then the setting of paths to model repeated data within a record (e.g. the multiple occurrences of node X in the diagram above). In our concrete example, we first split our input data into addresses (one address per record). Then we used a path from our telephone number node in the destination structure to the telephone number node in the source structure to make sure the destination structure node will be repeated as often in destination tree as the source structure node in the source tree.
The next step is the filling of a record of the destination tree.