Syntax

Catalogue

To define maps one need to add them to the catalogue, to do it call Mappum.catalogue_add function:

Mappum.catalogue_add do

	
… maps go here …

end

Mappum.catalogue_add has one optional argument – catalogue name (defaults to ROOT) do one can call it like this:

Mappum.catalogue_add "SOME_NAME" do
	
… maps go here …

end

Map

RootMap

To define mapping between two documents be it XML or Ruby objects you need to call map function. Like this:

map Person, Client do |person_alias, client_alias|
  #... submaps go here ...
end

One can use symbols instead of class names for example :Person instead of Person.
Be careful! It is not possible now to use Person <=> CRM::Client syntax here, we know that it would be nice but have no idea how to fix it.

Simple map

To map (or bind) two elements of the structure you write:

person_alias.element1 <=> client_alias.element2

This will transform element1 from Person to element2 on Client when transforming Person to Client. And transform element2 from Client to element1 on Person when transforming Client to Person. We say transform instead of copy but it will be copied when types of elements are the same. If types are not same and no sub-map is defined map from catalogue for given types will be used.

Type declaration

When type will not be deduced from object definition (in runtime) one need to declare type of element. This is done like this:

map p.address(ERP::Address) <=> c.address(CRM::Address)

Sub-maps

Maps of substructures e.g. complex elements can be declared in line as sub-maps. Sub map is a do .. end block given to map function:

map p.address(ERP::Address) <=> c.address(CRM::Address) do |erp_address, crm_address|
  map erp_address.street <=> crm_address.street
  #etc.
end

Unidirectional map

Maps can point one direction only:

map p.text >> c.body
#or
map p.somefield << c.element

This map will work as normal bidirectional map when object will be transformed but:

• There is no sub-maps on unidirectional maps
• You can declare function calls on unidirectional maps

Simple function calls

Function calls work only on unidirectional maps. To call a function on mapped object simply add call after the element:

map p.text.upcase >> c.body
#or
map p.somefield << c.element[0..5]

Complex function calls

Function calls work only on unidirectional maps. To execute multiline Ruby code on element pass block of code to map function:

map p.text >> c.body do |text|
  return text.upcase
end
#or
map p.somefield << c.element do |elem|
  return elem[0..5]
end

Constant mapping

Constant values can be mapped to fields in both directions. One need to specify the constant value
in the unidirectional map.

    map p.type << "NaN"
    map "Last" >> c.order_by

Raw function

To provide the function with no arguments (named raw in here) to be evaluated in the moment of
mapping “func” keyword is used.

    map p.date_updated << func do
      Date.today
    end
    map func >> c.updated do 
      Time.now
    end

Dictionary

Dictionaries support bidirectional mapping. When mapping left to right element value matching key in the dictionary will be maped to value for that key. And when maping right to left element value matching value from dictionary will be maped to the matching key.

map p.name <=> c.sn, :dict => {"PTO" => "Point to Object",  "B2B" => "Business to Business"}

XML

XML attributes

Attributes are accessible via xmlattr_ prefix.

map p.xmlattr_name <=> c.name