The Transformer class can be used to specify model transformations.

Model transformations take place between a source model (located in the source environment being an instance of the source metamodel) and a target model (located in the target environment being an instance of the target metamodel). Normally a "model" consists of several model elements associated with each other.

Transformation Rules

The transformation is specified within a subclass of Transformer. Within the subclass, the Transformer.transform class method can be used to specify transformation blocks for specific metamodel classes of the source metamodel.

If there is no transformation rule for the current object's class, a rule for the superclass is used instead. If there's no rule for the superclass, the class hierarchy is searched this way until Object.

Here is an example:

class MyTransformer < RGen::Transformer

        transform InputClass, :to => OutputClass do
                { :name => name, :otherClass => trans(otherClass) }
        end

        transform OtherInputClass, :to => OtherOutputClass do
                { :name => name }
        end
end

In this example a transformation rule is specified for model elements of class InputClass as well as for elements of class OtherInputClass. The former is to be transformed into an instance of OutputClass, the latter into an instance of OtherOutputClass. Note that the Ruby class objects are used to specifiy the classes.

Transforming Attributes

Besides the target class of a transformation, the attributes of the result object are specified in the above example. This is done by providing a Ruby block with the call of transform. Within this block arbitrary Ruby code may be placed, however the block must return a hash. This hash object specifies the attribute assignment of the result object using key/value pairs: The key must be a Symbol specifying the attribute which is to be assigned by name, the value is the value that will be assigned.

For convenience, the transformation block will be evaluated in the context of the source model element which is currently being converted. This way it is possible to just write :name => name in the example in order to assign the name of the source object to the name attribute of the target object.

Transforming References

When attributes of elements are references to other elements, those referenced elements have to be transformed as well. As shown above, this can be done by calling the Transformer#trans method. This method initiates a transformation of the element or array of elements passed as parameter according to transformation rules specified using transform. In fact the trans method is the only way to start the transformation at all.

For convenience and performance reasons, the result of trans is cached with respect to the parameter object. I.e. calling trans on the same source object a second time will return the same result object without a second evaluation of the corresponding transformation rules.

This way the trans method can be used to lookup the target element for some source element without the need to locally store a reference to the target element. In addition this can be useful if it is not clear if certain element has already been transformed when it is required within some other transformation block. See example below.

Special care has been taken to allow the transformation of elements which reference each other cyclically. The key issue here is that the target element of some transformation is created before the transformation's block is evaluated, i.e before the elements attributes are set. Otherwise a call to trans within the transformation's block could lead to a trans of the element itself.

Here is an example:

transform ModelAIn, :to => ModelAOut do
        { :name => name, :modelB => trans(modelB) }
end

transform ModelBIn, :to => ModelBOut do
        { :name => name, :modelA => trans(modelA) }
end

Note that in this case it does not matter if the transformation is initiated by calling trans with a ModelAIn element or ModelBIn element due to the caching feature described above.

Transformer Methods

When code in transformer blocks becomes more complex it might be useful to refactor it into smaller methods. If regular Ruby methods within the Transformer subclass are used for this purpose, it is necessary to know the source element being transformed. This could be achieved by explicitly passing the +@current_object+ as parameter of the method (see Transformer#trans).

A more convenient way however is to define a special kind of method using the Transformer.method class method. Those methods are evaluated within the context of the current source element being transformed just the same as transformer blocks are.

Here is an example:

transform ModelIn, :to => ModelOut do
        { :number => doubleNumber }
end

method :doubleNumber do
        number * 2;
end

In this example the transformation assigns the 'number' attribute of the source element multiplied by 2 to the target element. The multiplication is done in a dedicated method called 'doubleNumber'. Note that the 'number' attribute of the source element is accessed without an explicit reference to the source element as the method's body evaluates in the source element's context.

Conditional Transformations

Using the transformations as described above, all elements of the same class are transformed the same way. Conditional transformations allow to transform elements of the same class into elements of different target classes as well as applying different transformations on the attributes.

Conditional transformations are defined by specifying multiple transformer blocks for the same source class and providing a condition with each block. Since it is important to create the target object before evaluation of the transformation block (see above), the conditions must also be evaluated separately before the transformer block.

Conditions are specified using transformer methods as described above. If the return value is true, the corresponding block is used for transformation. If more than one conditions are true, only the first transformer block will be evaluated.

If there is no rule with a condition evaluating to true, rules for superclasses will be checked as described above.

Here is an example:

transform ModelIn, :to => ModelOut, :if => :largeNumber do
        { :number => number * 2}
end

transform ModelIn, :to => ModelOut, :if => :smallNumber do
        { :number => number / 2 }
end

method :largeNumber do
        number > 1000
end

method :smallNumber do
        number < 500
end

In this case the transformation of an element of class ModelIn depends on the value of the element's 'number' attribute. If the value is greater than 1000, the first rule as taken and the number is doubled. If the value is smaller than 500, the second rule is taken and the number is divided by two.

Note that it is up to the user to avoid cycles within the conditions. A cycle could occure if the condition are based on transformation target elements, i.e. if trans is used within the condition to lookup or transform other elements.

Copy Transformations

In some cases, transformations should just copy a model, either in the same metamodel or in another metamodel with the same package/class structure. Sometimes, a transformation is not exactly a copy, but a copy with slight modifications. Also in this case most classes need to be copied verbatim.

The class method Transformer.copy can be used to specify a copy rule for a single metamodel class. If no target class is specified using the :to named parameter, the target class will be the same as the source class (i.e. in the same metamodel).

copy MM1::ClassA                          # copy within the same metamodel
copy MM1::ClassA, :to => MM2::ClassA

The class method Transfomer.copy_all can be used to specify copy rules for all classes of a particular metamodel package. Again with :to, the target metamodel package may be specified which must have the same package/class structure. If :to is omitted, the target metamodel is the same as the source metamodel. In case that for some classes specific transformation rules should be used instead of copy rules, exceptions may be specified using the :except named parameter. copy_all also provides an easy way to copy (clone) a model within the same metamodel.

copy_all MM1                              # copy rules for the whole metamodel MM1, 
                                          # used to clone models of MM1

copy_all MM1, :to => MM2, :except => %w(  # copy rules for all classes of MM1 to
  ClassA                                  # equally named classes in MM2, except
  Sub1::ClassB                            # "ClassA" and "Sub1::ClassB"
)

If a specific class transformation is not an exact copy, the Transformer.transform method should be used to actually specify the transformation. If this transformation is also mostly a copy, the helper method Transformer#copy_features can be used to create the transformation Hash required by the transform method. Any changes to this hash may be done in a hash returned by a block given to copy_features. This hash will extend or overwrite the default copy hash. In case a particular feature should not be part of the copy hash (e.g. because it does not exist in the target metamodel), exceptions can be specified using the :except named parameter. Here is an example:

transform ClassA, :to => ClassAx do
  copy_features :except => [:featA] do 
    { :featB => featA }
  end
end

In this example, ClassAx is a copy of ClassA except, that feature "featA" in ClassA is renamed into "featB" in ClassAx. Using copy_features all features are copied except "featA". Then "featB" of the target class is assigned the value of "featA" of the source class.