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.
The transformation is specified within a subclass of Transformer. Within the subclass, the ::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.
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.
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 #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.
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 #trans).
A more convenient way however is to define a special kind of method using the ::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.
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.
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 ::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 ::transform method should be
used to actually specify the transformation. If this transformation is also
mostly a copy, the helper method #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.
This class method specifies that all objects of class from
are
to be copied into an object of class to
. If to
is
omitted, from
is used as target class. The target class may
also be specified using the :to => <class> hash notation. During
copy, all attributes and references of the target object are set to their
transformed counterparts of the source object.
# File lib/rgen/transformer.rb, line 264 def self.copy(from, to=nil) raise StandardError.new("Specify target class either directly as second parameter or using :to => <class>") \ unless to.nil? || to.is_a?(Class) || (to.is_a?(Hash) && to[:to].is_a?(Class)) to = to[:to] if to.is_a?(Hash) transform(from, :to => to || from) do copy_features end end # Create copy rules for all classes of metamodel package (module) +from+ and its subpackages. # The target classes are the classes with the same name in the metamodel package # specified using named parameter :to. If no target metamodel is specified, source # and target classes will be the same. # The named parameter :except can be used to specify classes by qualified name for which # no copy rules should be created. Qualified names are relative to the metamodel package # specified. # def self.copy_all(from, hash={}) to = hash[:to] || from except = hash[:except] fromDepth = from.ecore.qualifiedName.split("::").size from.ecore.eAllClasses.each do |c| path = c.qualifiedName.split("::")[fromDepth..-1] next if except && except.include?(path.join("::")) copy c.instanceClass, :to => path.inject(to){|m,c| m.const_get(c)} end end # Define a transformer method for the current transformer class. # In contrast to regular Ruby methods, a method defined this way executes in the # context of the object currently being transformed. # def self.method(name, &block) _methods[name.to_s] = block end # Creates a new transformer # Optionally an input and output Environment can be specified. # If an elementMap is provided (normally a Hash) this map will be used to lookup # and store transformation results. This way results can be predefined # and it is possible to have several transformers work on the same result map. # def initialize(env_in=nil, env_out=nil, elementMap=nil) @env_in = env_in @env_out = env_out @transformer_results = elementMap || {} @transformer_jobs = [] end # Transforms a given model element according to the rules specified by means of # the Transformer.transform class method. # # The transformation result element is created in the output environment and returned. # In addition, the result is cached, i.e. a second invocation with the same parameter # object will return the same result object without any further evaluation of the # transformation rules. Nil will be transformed into nil. Ruby "singleton" objects # +true+, +false+, numerics and symbols will be returned without any change. Ruby strings # will be duplicated with the result being cached. # # The transformation input can be given as: # * a single object # * an array each element of which is transformed in turn # * a hash used as input to Environment#find with the result being transformed # def trans(obj) if obj.is_a?(Hash) raise StandardError.new("No input environment available to find model element.") unless @env_in obj = @env_in.find(obj) end return nil if obj.nil? return obj if obj.is_a?(TrueClass) or obj.is_a?(FalseClass) or obj.is_a?(Numeric) or obj.is_a?(Symbol) return @transformer_results[obj] if @transformer_results[obj] return @transformer_results[obj] = obj.dup if obj.is_a?(String) return obj.collect{|o| trans(o)}.compact if obj.is_a? Array raise StandardError.new("No transformer for class #{obj.class.name}") unless _transformerBlock(obj.class) block_desc = _evaluateCondition(obj) return nil unless block_desc @transformer_results[obj] = _instantiateTargetClass(obj, block_desc.target) # we will transform the properties later @transformer_jobs << TransformerJob.new(self, obj, block_desc) # if there have been jobs in the queue before, don't process them in this call # this way calls to trans are not nested; a recursive implementation # may cause a "Stack level too deep" exception for large models return @transformer_results[obj] if @transformer_jobs.size > 1 # otherwise this is the first call of trans, process all jobs here # more jobs will be added during job execution while @transformer_jobs.size > 0 @transformer_jobs.first.execute @transformer_jobs.shift end @transformer_results[obj] end # Create the hash required as return value of the block given to the Transformer.transform method. # The hash will assign feature values of the source class to the features of the target class, # assuming the features of both classes are the same. If the :except named parameter specifies # an Array of symbols, the listed features are not copied by the hash. In order to easily manipulate # the resulting hash, a block may be given which should also return a feature assignmet hash. This # hash should be created manually and will extend/overwrite the automatically created hash. # def copy_features(options={}) hash = {} @current_object.class.ecore.eAllStructuralFeatures.each do |f| next if f.derived next if options[:except] && options[:except].include?(f.name.to_sym) hash[f.name.to_sym] = trans(@current_object.send(f.name)) end hash.merge!(yield) if block_given? hash end def _transformProperties(obj, block_desc) #:nodoc: old_object, @current_object = @current_object, obj block_result = instance_eval(&block_desc.block) raise StandardError.new("Transformer must return a hash") unless block_result.is_a? Hash @current_object = old_object _attributesFromHash(@transformer_results[obj], block_result) end class TransformerJob #:nodoc: def initialize(transformer, obj, block_desc) @transformer, @obj, @block_desc = transformer, obj, block_desc end def execute @transformer._transformProperties(@obj, @block_desc) end end # Each call which is not handled by the transformer object is passed to the object # currently being transformed. # If that object also does not respond to the call, it is treated as a transformer # method call (see Transformer.method). # def method_missing(m, *args) #:nodoc: if @current_object.respond_to?(m) @current_object.send(m, *args) else _invokeMethod(m, *args) end end private # returns _transformer_blocks content for clazz or one of its superclasses def _transformerBlock(clazz) # :nodoc: block = self.class._transformer_blocks[clazz] block = _transformerBlock(clazz.superclass) if block.nil? && clazz != Object block end # returns the first TransformationDescription for clazz or one of its superclasses # for which condition is true def _evaluateCondition(obj, clazz=obj.class) # :nodoc: tb = self.class._transformer_blocks[clazz] block_description = nil if tb.is_a?(TransformationDescription) # non-conditional block_description = tb elsif tb old_object, @current_object = @current_object, obj tb.each_pair {|condition, block| if condition.is_a?(Proc) result = instance_eval(&condition) elsif condition.is_a?(Symbol) result = _invokeMethod(condition) else result = condition end if result block_description = block break end } @current_object = old_object end block_description = _evaluateCondition(obj, clazz.superclass) if block_description.nil? && clazz != Object block_description end def _instantiateTargetClass(obj, target_desc) # :nodoc: old_object, @current_object = @current_object, obj if target_desc.is_a?(Proc) target_class = instance_eval(&target_desc) elsif target_desc.is_a?(Symbol) target_class = _invokeMethod(target_desc) else target_class = target_desc end @current_object = old_object result = target_class.new @env_out << result if @env_out result end def _invokeMethod(m) # :nodoc: raise StandardError.new("Method not found: #{m}") unless self.class._methods[m.to_s] instance_eval(&self.class._methods[m.to_s]) end def _attributesFromHash(obj, hash) # :nodoc: hash.delete(:class) hash.each_pair{|k,v| obj.send("#{k}=", v) } obj end end
Create copy rules for all classes of metamodel package (module)
from
and its subpackages. The target classes are the classes
with the same name in the metamodel package specified using named parameter
:to. If no target metamodel is specified, source and target classes will be
the same. The named parameter :except can be used to specify classes by
qualified name for which no copy rules should be created. Qualified names
are relative to the metamodel package specified.
# File lib/rgen/transformer.rb, line 281 def self.copy_all(from, hash={}) to = hash[:to] || from except = hash[:except] fromDepth = from.ecore.qualifiedName.split("::").size from.ecore.eAllClasses.each do |c| path = c.qualifiedName.split("::")[fromDepth..-1] next if except && except.include?(path.join("::")) copy c.instanceClass, :to => path.inject(to){|m,c| m.const_get(c)} end end
Define a transformer method for the current transformer class. In contrast to regular Ruby methods, a method defined this way executes in the context of the object currently being transformed.
# File lib/rgen/transformer.rb, line 296 def self.method(name, &block) _methods[name.to_s] = block end
Creates a new transformer Optionally an input and output Environment can be specified. If an elementMap is provided (normally a Hash) this map will be used to lookup and store transformation results. This way results can be predefined and it is possible to have several transformers work on the same result map.
# File lib/rgen/transformer.rb, line 307 def initialize(env_in=nil, env_out=nil, elementMap=nil) @env_in = env_in @env_out = env_out @transformer_results = elementMap || {} @transformer_jobs = [] end
This class method is used to specify a transformation rule.
The first argument specifies the class of elements for which this rule applies. The second argument must be a hash including the target class (as value of key ':to') and an optional condition (as value of key ':if').
The target class is specified by passing the actual Ruby class object. The condition is either the name of a transformer method (see Transfomer.method) as a symbol or a proc object. In either case the block is evaluated at transformation time and its result value determines if the rule applies.
# File lib/rgen/transformer.rb, line 243 def self.transform(from, desc=nil, &block) to = (desc && desc.is_a?(Hash) && desc[:to]) condition = (desc && desc.is_a?(Hash) && desc[:if]) raise StandardError.new("No transformation target specified.") unless to block_desc = TransformationDescription.new(block, to) if condition _transformer_blocks[from] ||= {} raise StandardError.new("Multiple (non-conditional) transformations for class #{from.name}.") unless _transformer_blocks[from].is_a?(Hash) _transformer_blocks[from][condition] = block_desc else raise StandardError.new("Multiple (non-conditional) transformations for class #{from.name}.") unless _transformer_blocks[from].nil? _transformer_blocks[from] = block_desc end end
Create the hash required as return value of the block given to the ::transform method. The hash will assign feature values of the source class to the features of the target class, assuming the features of both classes are the same. If the :except named parameter specifies an Array of symbols, the listed features are not copied by the hash. In order to easily manipulate the resulting hash, a block may be given which should also return a feature assignmet hash. This hash should be created manually and will extend/overwrite the automatically created hash.
# File lib/rgen/transformer.rb, line 366 def copy_features(options={}) hash = {} @current_object.class.ecore.eAllStructuralFeatures.each do |f| next if f.derived next if options[:except] && options[:except].include?(f.name.to_sym) hash[f.name.to_sym] = trans(@current_object.send(f.name)) end hash.merge!(yield) if block_given? hash end
Transforms a given model element according to the rules specified by means of the ::transform class method.
The transformation result element is created in the output environment and
returned. In addition, the result is cached, i.e. a second invocation with
the same parameter object will return the same result object without any
further evaluation of the transformation rules. Nil will be transformed
into nil. Ruby “singleton” objects true
, false
,
numerics and symbols will be returned without any change. Ruby strings will
be duplicated with the result being cached.
The transformation input can be given as:
a single object
an array each element of which is transformed in turn
a hash used as input to RGen::Environment#find with the result being transformed
# File lib/rgen/transformer.rb, line 330 def trans(obj) if obj.is_a?(Hash) raise StandardError.new("No input environment available to find model element.") unless @env_in obj = @env_in.find(obj) end return nil if obj.nil? return obj if obj.is_a?(TrueClass) or obj.is_a?(FalseClass) or obj.is_a?(Numeric) or obj.is_a?(Symbol) return @transformer_results[obj] if @transformer_results[obj] return @transformer_results[obj] = obj.dup if obj.is_a?(String) return obj.collect{|o| trans(o)}.compact if obj.is_a? Array raise StandardError.new("No transformer for class #{obj.class.name}") unless _transformerBlock(obj.class) block_desc = _evaluateCondition(obj) return nil unless block_desc @transformer_results[obj] = _instantiateTargetClass(obj, block_desc.target) # we will transform the properties later @transformer_jobs << TransformerJob.new(self, obj, block_desc) # if there have been jobs in the queue before, don't process them in this call # this way calls to trans are not nested; a recursive implementation # may cause a "Stack level too deep" exception for large models return @transformer_results[obj] if @transformer_jobs.size > 1 # otherwise this is the first call of trans, process all jobs here # more jobs will be added during job execution while @transformer_jobs.size > 0 @transformer_jobs.first.execute @transformer_jobs.shift end @transformer_results[obj] end