1Merge(3)              User Contributed Perl Documentation             Merge(3)
2
3
4

NAME

6       XML::Merge - flexibly merge XML documents
7

VERSION

9       This documentation refers to version 1.4 of XML::Merge, which was
10       released on Sat Jul 23 14:39:59:48 -0500 2016.
11

SYNOPSIS

13         #!/usr/bin/perl
14         use strict;use   warnings;
15         use   utf8;use XML::Merge;
16
17         # create new   XML::Merge object from         MainFile.xml
18         my $merge_obj= XML::Merge->new('filename' => 'MainFile.xml');
19
20         # Merge File2Add.xml             into         MainFile.xml
21            $merge_obj->merge(          'filename' => 'File2Add.xml');
22
23         # Tidy up the indenting that resulted from the merge
24            $merge_obj->tidy();
25
26         # Write out changes back           to         MainFile.xml
27            $merge_obj->write();
28

DESCRIPTION

30       This module inherits from XML::Tidy which in turn inherits from
31       XML::XPath. This ensures that Merge objects' indenting can be tidied up
32       after any merge operation since such modification usually ruins
33       indentation. Polymorphism allows Merge objects to be utilized as normal
34       XML::XPath objects as well.
35
36       The merging behavior is setup to combine separate XML documents
37       according to certain rules and configurable options. If both documents
38       have root nodes which are elements of the same name, the documents are
39       merged directly. Otherwise, one is merged as a child of the other. An
40       optional XPath location can be specified as the place to perform the
41       merge. If no location is specified, the merge is attempted at the first
42       matching element or is appended as the new last child of the other root
43       if no match is found.
44

USAGE

46   new()
47       This is the standard Merge object constructor. It can take the same
48       parameters as an XML::XPath object constructor to initialize the
49       primary XML document object (the object which subsequent XML documents
50       will be merged into). These parameters can be any one of:
51
52         'filename' => 'SomeFile.xml'
53         'xml'      => $variable_which_holds_a_bunch_of_XML_data
54         'ioref'    => $file_InputOutput_reference
55         'context'  => $existing_node_at_specified_context_to_become_new_obj
56
57       Merge's new() can also accept merge-option parameters to override the
58       default merge behavior. These include:
59
60         'conflict_resolution_method' => 'main', # main  file wins
61         'conflict_resolution_method' => 'merg', # merge file wins
62         # 'last-in_wins' is the same as 'merg'
63         'conflict_resolution_method' => 'warn', # croak conflicts
64         'conflict_resolution_method' => 'test', # just test, 1 if conflict
65
66   merge()
67       The merge() member function can accept the same XML::XPath constructor
68       options as new() but this time they are for the temporary file which
69       will be merged into the main object.  Merge-options from new() can also
70       be specified and they will only impact one particular invokation of
71       merge(). The specified document will be merged into the primary XML
72       document object according to the following default merge rules:
73
74       1. If both documents share the same root element name, they are merged
75       directly.
76
77       2. If they don't share root elements but the temporary merge file's
78       root element is found anywhere within the main file, the merge occurs
79       at the match.
80
81       3. If no root element match is found, the merge document becomes the
82       new last child of the main file's root element.
83
84       4. Whenever a deeper level is found with an element of the same name in
85       both documents and either it does not contain any distinguishing
86       attributes or it has attributes which are recognized as 'identifier'
87       (id) attributes (by default, for any element, these are attributes
88       named: 'id', 'idx', 'ndx', 'index', 'name', and 'handle'), a
89       corresponding element is searched for to match and merge with.
90
91       5. Any remaining (non-id) nodes are merged in document order.
92
93       6. When a conflict arises as non-id attributes or other nodes merge,
94       the specified conflict_resolution_method merge-option is applied (which
95       by default has the main file data persist at the expense of the merging
96       file data).
97
98       Some of the above rules can be overridden first by the object's merge-
99       options and second by the particular method call's merge-options.
100       Thus, if the default merge-option for conflict resolution is to have
101       the main object win and you use the following constructor:
102
103         my $merge_obj = XML::Merge->new(
104           'filename'                   => 'MainFile.xml',
105           'conflict_resolution_method' => 'last-in_wins');
106
107       ... then any $merge_obj->merge() call would override the default merge
108       behavior by letting the document being merged have priority over the
109       main object's document. However, you could supply additional merge-
110       options in the parameter list of your specific merge() call like:
111
112         $merge_obj->merge(
113           'filename'                   => 'File2Add.xml',
114           'conflict_resolution_method' => 'warn');
115
116       ... to have the latest option override further.
117
118       The 'test' conflict_resolution_method merge-option does not modify the
119       object at all. It solely returns zero (0) if no conflict was
120       encountered from a temporary attempted merge.
121
122       It should be used like:
123
124         for(@files) {
125           if($merge_obj->merge('cres' => 'test', $_)) {
126             croak("Yipes! Conflict with file:$_!\n");
127           } else {
128             $merge_obj->merge($_); # only do it if there are no conflicts
129           }
130         }
131
132       merge() can also accept another XML::Merge object as a parameter for
133       what to be merged with the main object instead of a filename.  An
134       example of this is:
135
136         $merge_obj->merge($another_merge_obj);
137
138       Along with the merge options that can be specified in the object
139       constructor, merge() also accepts the following options to specify
140       where to perform the merge relative to:
141
142         'merge_destination_path' => $main_obj_xpath_location,
143         'merge_source_path'      => $merging_obj_xpath_location,
144
145   unmerge()
146       The unmerge() member function is a shorthand for calling both write()
147       and prune() on a certain XPath location which should be written out to
148       a disk file before being removed from the Merge object. Please see
149       XML::Tidy for documentation of the inherited write() and prune() member
150       functions.
151
152       This unmerge() process could be the opposite of merge() if no original
153       elements or attributes overlapped and combined but if combining did
154       happen, this would remove original sections of your primary XML
155       document's data from your Merge object so please use this carefully.
156       It is meant to help separate a giant object (probably the result of
157       myriad merge() calls) back into separate useful well-formed XML
158       documents on disk.
159
160       unmerge() takes a filename and an xpath_location parameter.
161

Accessors

163   get_object_to_merge()
164       Returns the object which was last merged into the main object.
165
166   set_object_to_merge()
167       Assigns the object which was last merged into the main object.
168
169   get_conflict_resolution_method()
170       Returns the underlying merge-option conflict_resolution_method.
171
172   set_conflict_resolution_method()
173       A new value can be provided as a parameter to be assigned as the
174       XML::Merge object's merge-option.
175
176   get_id_xpath_list()
177       Returns the underlying id_xpath_list. This is normally just a list of
178       attributes (e.g., '@id', '@idx', '@ndx', '@index', '@name', '@handle')
179       which are unique identifiers for any XML element within merging
180       instance documents. When these attribute names are encountered during a
181       merge(), another element with the same name and attribute value are
182       searched for explicitly in order to align deeper merging and conflict
183       resolution.
184
185   set_id_xpath_list()
186       A new list can assigned to the XML::Merge object's id_xpath_list.
187
188       Please note that this list normally contains XPath attributes so they
189       must be preceded by an at-symbol (@) like: '@example_new_id_attribute'.
190

CHANGES

192       Revision history for Perl extension XML::Merge:
193
194       - 1.4 G7NMEdxm  Sat Jul 23 14:39:59:48 -0500 2016
195         * inverted conflict resolution 'test' value since true 1 for conflict
196         makes more sense
197
198         * renumbered t/*.t
199
200         * updated Makefile.PL and Build.PL to hopefully fix issue
201         <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=29898> (Thanks
202         Kevin.)
203
204         * removed DBUG printing
205
206         * removed PT from VERSION to fix issue
207         <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=106873> (Thanks
208         ppisar.)
209
210         * updated license to GPLv3
211
212       - 1.2.75BAJNl  Fri May 11 10:19:23:47 2007
213         * added default id @s: idx, ndx, and index
214
215       - 1.2.565EgGd  Sun Jun  5 14:42:16:39 2005
216         * added use XML::Tidy to make sure exports are available
217
218         * removed 02prune.t and moved 03keep.t to 02keep.t ... passing tests
219         is good
220
221       - 1.2.4CCJWiB  Sun Dec 12 19:32:44:11 2004
222         * guessing how to fix Darwin test failure @ t/02prune.t first prune()
223         call
224
225       - 1.0.4CAL5IS  Fri Dec 10 21:05:18:28 2004
226         * fixed buggy _recmerge
227
228       - 1.0.4CAEU0I  Fri Dec 10 14:30:00:18 2004
229         * made accessors for _id_xpath_list
230
231         * made _id_xpath_list take XPath locations instead of elem names (old
232         _idea)
233
234         * made test _cres (at Marc's request)
235
236         * made warn _cres croak
237
238         * made Merge inherit from Tidy (which inherits from XPath)
239
240         * separated reload(), strip(), tidy(), prune(), and write() into own
241             XML::Tidy module
242
243       - 1.0.4C2Nf0R  Thu Dec  2 23:41:00:27 2004
244         * updated license and prep'd for release
245
246       - 1.0.4C2BcI2  Thu Dec  2 11:38:18:02 2004
247         * updated reload(), strip(), and tidy() to verify _xpob exists
248
249       - 1.0.4C1JHOl  Wed Dec  1 19:17:24:47 2004
250         * commented out override stuff since it's probably bad form and dumps
251         crap
252             warnings all over tests and causes them to fail... so I guess
253         just
254             uncomment that stuff if you care to preserve PI's and escapes
255
256       - 1.0.4C1J7gt  Wed Dec  1 19:07:42:55 2004
257         * made merge() accept merge_source_xpath and merge_destination_xpath
258         params
259
260         * made merge() accept other Merge objects
261
262         * made reload() not clobber basic escapes (by overriding Text
263         toString())
264
265         * made tidy() not kill processing-instructions (by overriding
266         node_test())
267
268         * made tidy() not kill comments
269
270       - 1.0.4BOHGjm  Wed Nov 24 17:16:45:48 2004
271         * fixed merge() same elems with diff ids bug
272
273       - 1.0.4BNBCZL  Tue Nov 23 11:12:35:21 2004
274         * rewrote both merge() and _recmerge() _cres stuff since it was
275             buggy before... so hopefully consistently good now
276
277       - 1.0.4BMJCPm  Mon Nov 22 19:12:25:48 2004
278         * fixed merge() for empty elem matching and _cres on text kids
279
280       - 1.0.4BMGTLF  Mon Nov 22 16:29:21:15 2004
281         * separated reload() from strip() so that prune() can call it too
282
283       - 1.0.4BM0B3x  Mon Nov 22 00:11:03:59 2004
284         * fixed tidy() empty elem bug and implemented prune() and unmerge()
285
286       - 1.0.4BJAZpM  Fri Nov 19 10:35:51:22 2004
287         * fixing e() ABSTRACT gen bug
288
289       - 1.0.4BJAMR6  Fri Nov 19 10:22:27:06 2004
290         * fleshed out POD and members
291
292       - 1.0.4AIDqmR  Mon Oct 18 13:52:48:27 2004
293         * original version
294

TODO

296       - add Kevin's multiple _idea option where several element attributes
297       are an ID together, from:
298       <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=29897>
299       - make namespaces and attributes stay in order after merge()
300       - make text append merge option
301       - handle comment joins and stamping options
302       - support modification-time conflict resolution method
303       - add _ignr ignore list of merge XPath locations to not merge
304       (pre-prune())
305

INSTALL

307       From the command shell, please run:
308
309         `perl -MCPAN -e "install XML::Merge"`
310
311       or uncompress the package and run the standard:
312
313         `perl Makefile.PL;       make;       make test;       make install`
314           or if you don't have  `make` but Module::Build is installed, try:
315         `perl    Build.PL; perl Build; perl Build test; perl Build install`
316

FILES

318       XML::Merge requires:
319
320       Carp                to allow errors to croak() from calling sub
321
322       XML::Tidy           to use objects derived from XPath to update XML
323

LICENSE

325       Most source code should be Free! Code I have lawful authority over is
326       and shall be!  Copyright: (c) 2004-2016, Pip Stuart.  Copyleft :  This
327       software is licensed under the GNU General Public License
328         (version 3 or later). Please consult
329       <HTTP://GNU.Org/licenses/gpl-3.0.txt>
330         for important information about your freedom. This is Free Software:
331       you
332         are free to change and redistribute it. There is NO WARRANTY, to the
333         extent permitted by law. See <HTTP://FSF.Org> for further
334       information.
335

AUTHOR

337       Pip Stuart <Pip@CPAN.Org>
338
339
340
341perl v5.34.0                      2022-01-21                          Merge(3)
Impressum