1Merge(3) User Contributed Perl Documentation Merge(3)
2
6 XML::Merge - flexibly merge XML documents
7
9 This documentation refers to version 1.2.565EgGd of XML::Merge, which
10 was released on Sun Jun 5 14:42:16:39 2005.
11
13 use XML::Merge;
14 # create new XML::Merge object from MainFile.xml
16 my $merge_obj = XML::Merge->new('filename' => 'MainFile.xml');
17 # Merge File2Add.xml into MainFile.xml
19 $merge_obj->merge( 'filename' => 'File2Add.xml');
20 # Tidy up the indenting that resulted from the merge
22 $merge_obj->tidy();
23 # Write out changes back to MainFile.xml
25 $merge_obj->write();
26
28 This module inherits from XML::Tidy which in turn inherits from
29 XML::XPath. This ensures that Merge objects' indenting can be tidied
30 up after any merge operation since such modification usually spells the
31 ruination of indentation. Polymorphism allows Merge objects to be
32 utilized as normal XML::XPath objects as well.
33 The merging behavior is setup to combine separate XML documents
35 according to certain rules && configurable options. If both documents
36 have root nodes which are elements of the same name, the documents are
37 merged directly. Otherwise, one is merged as a child of the other. An
38 optional XPath location can be specified as the place to perform the
39 merge. If no location is specified, the merge is attempted at the
40 first matching element or is appended as the new last child of the
41 other root if no match is found.
42
44 - mk namespaces && attz stay in order after merge()
45 - mk txt apnd merg optn
46 - handle comment joins && stamping && options
47 - support modification-time _cres
48 - add _ignr ignore list of merg xplc's to not merge (pre-prune())
49 - support _idea options where several attz together are single id
50 - What else does Merge need?
51
53 new()
54 This is the standard Merge object constructor. It can take the same
55 parameters as an XML::XPath object constructor to initialize the
56 primary XML document object (the object which subsequent XML documents
57 will be merged into). These parameters can be any one of:
58 'filename' => 'SomeFile.xml'
60 'xml' => $variable_which_holds_a_bunch_of_XML_data
61 'ioref' => $file_InputOutput_reference
62 'context' => $existing_node_at_specified_context_to_become_new_obj
63 Merge's new() can also accept merge-option parameters to override the
65 default merge behavior. These include:
66 'conflict_resolution_method' => 'main', # main file wins
68 'conflict_resolution_method' => 'merg', # merge file wins
69 # 'last-in_wins' is an alias for 'merg'
70 'conflict_resolution_method' => 'warn', # croak conflicts
71 'conflict_resolution_method' => 'test', # just test, 0 if conflict
72 # this option is not implemented yet, please say if you need it
73 'comment_join_method' => 'none',
74 merge()
76 The merge() member function can accept the same XML::XPath constructor
77 options as new() but this time they are for the temporary file which
78 will be merged into the main object. Merge-options from new() can also
79 be specified && they will only impact one particular invokation of
80 merge(). The specified document will be merged into the primary XML
81 document object according to the following default merge rules:
82 0. If both documents share the same root element name, they are
84 merged directly.
85 1. If they don't share root elements but the temporary merge file's
86 root element is found anywhere within the main file, the merge
87 occurs at the match.
88 2. If no root element match is found, the merge document becomes the
89 new last child of the main file's root element.
90 3. Whenever a deeper level is found with an element of the same name
91 in both documents && either it does not contain any
92 distinguishing attributes or it has attributes which are
93 recognized as 'identifier' (id) attributes (by default, for any
94 element, these are attributes named: 'id', 'name', && 'handle'),
95 a corresponding element is searched for to match && merge with.
96 4. Any remaining (non-id) nodes are merged in document order.
97 5. When a conflict arises as non-id attributes or other nodes merge,
98 the specified conflict_resolution_method merge-option is
99 applied (which by default has the main file data persist at the
100 expense of the merging file data).
101 Some of the above rules can be overridden first by the object's merge-
103 options && second by the particular method call's merge-options. Thus,
104 if the default merge-option for conflict resolution is to have the main
105 object win && you use the following constructor:
106 my $merge_obj = XML::Merge->new(
108 'filename' => 'MainFile.xml',
109 'conflict_resolution_method' => 'last-in_wins');
110 ... then any $merge_obj->merge() call would override the default merge
112 behavior by letting the document being merged have priority over the
113 main object's document. However, you could supply additional merge-
114 options in the parameter list of your specific merge() call like:
115 $merge_obj->merge(
117 'filename' => 'File2Add.xml',
118 'conflict_resolution_method' => 'warn');
119 ... then the latest option would override the already overridden.
121 The 'test' conflict_resolution_method merge-option does not modify the
123 object at all. It solely returns true if no conflict is encountered.
124 It should be used like:
125 foreach(@files) {
127 if($merge_obj->merge('cres' => 'test', $_)) {
128 $merge_obj->merge($_); # only do it if there are no conflicts
129 } else {
130 croak("Yipes! Conflict with file:$_!\n");
131 }
132 }
133 merge() can also accept another XML::Merge object as a parameter for
135 what to be merged with the main object instead of a filename. An
136 example of this is:
137 $merge_obj->merge($another_merge_obj);
139 Along with the merge options that can be specified in the object
141 constructor, merge() also accepts the following options to specify
142 where to perform the merge relative to:
143 'merge_destination_path' => $main_obj_xpath_location,
145 'merge_source_path' => $merging_obj_xpath_location,
146 unmerge()
148 The unmerge() member function is a shorthand for calling both write()
149 && prune() on a certain XPath location which should be written out to a
150 disk file before being removed from the Merge object. Please see
151 XML::Tidy for documentation of the inherited write() && prune() member
152 functions.
153 This unmerge() process could be the opposite of merge() if no original
155 elements or attributes overlapped && combined but if combining did
156 happen, this would remove original sections of your primary XML
157 document's data from your Merge object so please use this carefully.
158 It is meant to help separate a giant object (probably the result of
159 myriad merge() calls) back into separate useful well-formed XML
160 documents on disk.
161 unmerge() takes a filename && an xpath_location parameter.
163
165 get_object_to_merge()
166 Returns the object which was last merged into the main object.
167 set_object_to_merge()
169 Assigns the object which was last merged into the main object.
170 get_conflict_resolution_method()
172 Returns the underlying merge-option conflict_resolution_method.
173 set_conflict_resolution_method()
175 A new value can be provided as a parameter to be assigned as the
176 XML::Merge object's merge-option.
177 get_comment_join_method()
179 Returns the underlying merge-option comment_join_method.
180 set_comment_join_method()
182 A new value can be provided as a parameter to be assigned as the
183 XML::Merge object's merge-option.
184 get_id_xpath_list()
186 Returns the underlying id_xpath_list. This is normally just a list of
187 attributes (eg. '@id', '@name', '@handle') which are unique identifiers
188 for any XML element. When these attribute names are encountered during
189 a merge(), another element with the same name && attribute value are
190 matched for further merging && conflict resolution.
191 set_id_xpath_list()
193 A new list can assigned to the XML::Merge object's id_xpath_list.
194 Please note that this list normally contains XPath attributes so they
196 must be preceded by an at-symbol (@) like: '@example_id_attribute'.
197
199 Revision history for Perl extension XML::Merge:
200 - 1.2.565EgGd Sun Jun 5 14:42:16:39 2005
202 * added use XML::Tidy to make sure exports are available
203 * removed 02prune.t && moved 03keep.t to 02keep.t ... passing tests
205 is good
206 - 1.2.4CCJWiB Sun Dec 12 19:32:44:11 2004
208 * guessing how to fix Darwin test failure @ t/02prune.t first
209 prune() call
210 - 1.0.4CAL5IS Fri Dec 10 21:05:18:28 2004
212 * fixed buggy _recmerge
213 - 1.0.4CAEU0I Fri Dec 10 14:30:00:18 2004
215 * made accessors for _id_xpath_list
216 * made _id_xpath_list take XPath locations instead of elem names
218 (old _idea)
219 * made test _cres (at Marc's request)
221 * made warn _cres croak
223 * made Merge inherit from Tidy (which inherits from XPath)
225 * separated reload(), strip(), tidy(), prune(), && write() into own
227 XML::Tidy module
228 - 1.0.4C2Nf0R Thu Dec 2 23:41:00:27 2004
230 * updated license && prep'd for release
231 - 1.0.4C2BcI2 Thu Dec 2 11:38:18:02 2004
233 * updated reload(), strip(), && tidy() to verify _xpob exists
234 - 1.0.4C1JHOl Wed Dec 1 19:17:24:47 2004
236 * commented out override stuff since it's probably bad form &&
237 dumps crap
238 warnings all over tests && causes them to fail... so I guess
239 just
240 uncomment that stuff if you care to preserve PI's && escapes
241 - 1.0.4C1J7gt Wed Dec 1 19:07:42:55 2004
243 * made merge() accept merge_source_xpath && merge_destination_xpath
244 params
245 * made merge() accept other Merge objects
247 * made reload() not clobber basic escapes (by overriding Text
249 toString())
250 * made tidy() not kill processing-instructions (by overriding
252 node_test())
253 * made tidy() not kill comments
255 - 1.0.4BOHGjm Wed Nov 24 17:16:45:48 2004
257 * fixed merge() same elems with diff ids bug
258 - 1.0.4BNBCZL Tue Nov 23 11:12:35:21 2004
260 * rewrote both merge() && _recmerge() _cres stuff since it was
261 buggy before... so hopefully consistently good now
262 - 1.0.4BMJCPm Mon Nov 22 19:12:25:48 2004
264 * fixed merge() for empty elem matching && _cres on text kids
265 - 1.0.4BMGTLF Mon Nov 22 16:29:21:15 2004
267 * separated reload() from strip() so that prune() can call it too
268 - 1.0.4BM0B3x Mon Nov 22 00:11:03:59 2004
270 * fixed tidy() empty elem bug && implemented prune() && unmerge()
271 - 1.0.4BJAZpM Fri Nov 19 10:35:51:22 2004
273 * fixing e() ABSTRACT gen bug
274 - 1.0.4BJAMR6 Fri Nov 19 10:22:27:06 2004
276 * fleshed out pod && members
277 - 1.0.4AIDqmR Mon Oct 18 13:52:48:27 2004
279 * original version
280
282 From your command shell, please run:
283 `perl -MCPAN -e "install XML::Merge"`
285 or uncompress the package && run the standard:
287 `perl Makefile.PL; make; make test; make install`
289
291 XML::Merge requires:
292 Carp to allow errors to croak() from calling sub
294 XML::Tidy to use objects derived from XPath to update XML
296
298 Most source code should be Free!
299 Code I have lawful authority over is && shall be! Copyright: (c)
300 2004, Pip Stuart. Copyleft : This software is licensed under the GNU
301 General Public
302 License (version 2), && as such comes with NO WARRANTY. Please
303 consult the Free Software Foundation (http://FSF.Org) for
304 important information about your freedom.
305
307 Pip Stuart <Pip@CPAN.Org>
308perl v5.12.0 2005-06-05 Merge(3)