Debian Codegraph @

homepage/script-docs/stag-diff.html

raw
1 <HTML>
2 <HEAD>
3 <TITLE>stag-diff</TITLE>
4 <LINK REV="made" HREF="mailto:[email protected]">
5 </HEAD>
6
7 <BODY>
8
9 <A NAME="__index__"></A>
10 <!-- INDEX BEGIN -->
11
12 <UL>
13
14 <LI><A HREF="#name">NAME</A></LI>
15 <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
16 <LI><A HREF="#description">DESCRIPTION</A></LI>
17 <UL>
18
19 <LI><A HREF="#output">OUTPUT</A></LI>
20 <LI><A HREF="#algorithm">ALGORITHM</A></LI>
21 <LI><A HREF="#author">AUTHOR</A></LI>
22 </UL>
23
24 <LI><A HREF="#see also">SEE ALSO</A></LI>
25 </UL>
26 <!-- INDEX END -->
27
28 <HR>
29 <P>
30 <H1><A NAME="name">NAME</A></H1>
31 <P>stag-diff.pl - finds the difference between two stag files</P>
32 <P>
33 <HR>
34 <H1><A NAME="synopsis">SYNOPSIS</A></H1>
35 <PRE>
36 stag-diff.pl -ignore foo-id -ignore bar-id file1.xml file2.xml</PRE>
37 <P>
38 <HR>
39 <H1><A NAME="description">DESCRIPTION</A></H1>
40 <P>Compares two data trees and reports whether they match. If they do not
41 match, the mismatch is reported.</P>
42 <DL>
43 <DT><STRONG><A NAME="item_%2Dhelp%7Ch">-help|h</A></STRONG><BR>
44 <DD>
45 shows this document
46 <P></P>
47 <DT><STRONG><A NAME="item_%2Dignore%7Ci_ELEMENT">-ignore|i ELEMENT</A></STRONG><BR>
48 <DD>
49 these nodes are ignored for the purposes of comparison. Note that
50 attributes are treated as elements, prefixed by the containing element
51 id. For example, if you have
52 <PRE>
53 &lt;foo ID=&quot;wibble&quot;&gt;</PRE>
54 <P>And you wish to ignore the ID attribute, then you would use the switch</P>
55 <PRE>
56 -ignore foo-ID</PRE>
57 <P>You can specify multiple elements to ignore like this</P>
58 <PRE>
59 -i foo -i bar -i baz</PRE>
60 <P>You can also specify paths</P>
61 <PRE>
62 -i foo/bar/bar-id</PRE>
63 <P></P>
64 <DT><STRONG><A NAME="item_%2Dparser%7Cp_FORMAT">-parser|p FORMAT</A></STRONG><BR>
65 <DD>
66 which parser to use. The default is XML. This can also be autodetected
67 by the file suffix. Other alternatives are <STRONG>sxpr</STRONG> and <STRONG>itext</STRONG>. See
68 <A HREF="./Data/Stag.html">the Data::Stag manpage</A> for details.
69 <P></P>
70 <DT><STRONG><A NAME="item_%2Dreport%7Cr_ELEMENT">-report|r ELEMENT</A></STRONG><BR>
71 <DD>
72 report mismatches as they occur on each element of type ELEMENT
73 <P>multiple elements can be specified</P>
74 <P></P>
75 <DT><STRONG><A NAME="item_%2Dverbose%7Cv">-verbose|v</A></STRONG><BR>
76 <DD>
77 used in conjunction with the <STRONG>-report</STRONG> switch
78 <P>shows the tree of the mismatching element</P>
79 <P></P></DL>
80 <P>
81 <H2><A NAME="output">OUTPUT</A></H2>
82 <P>If a mismatch is reported, a report is generated displaying the
83 subpart of the tree that could not be matched. This will look like
84 this:</P>
85 <P>REASON:
86 no_matching_node: annotation
87 no_matching_node: feature_set
88 no_matching_node: feature_span
89 no_matching_node: evidence
90 no_matching_node: evidence-id
91 data_mismatch(:15077290 ne :15077291): evidence-id AND evidence-id</P>
92 <P>Due to the nature of tree matching, it can be difficult to specify
93 exactly how trees do not match. To investigate this, you may need to
94 use the <STRONG>-r</STRONG> and <STRONG>-v</STRONG> options. For the above output, I would
95 recommend using</P>
96 <PRE>
97 stag-diff.pl -r feature_span -v</PRE>
98 <P>
99 <H2><A NAME="algorithm">ALGORITHM</A></H2>
100 <P>Both trees are recursively traversed... see the actual code for how this works</P>
101 <P>The order of elements is not important; eg
102 </P>
103 <PRE>
104
105 &lt;foo&gt;
106 &lt;bar&gt;
107 &lt;baz&gt;1&lt;/baz&gt;
108 &lt;/bar&gt;
109 &lt;bar&gt;
110 &lt;baz&gt;2&lt;/baz&gt;
111 &lt;/bar&gt;
112 &lt;/foo&gt;</PRE>
113 <P>matches</P>
114 <PRE>
115 &lt;foo&gt;
116 &lt;bar&gt;
117 &lt;baz&gt;2&lt;/baz&gt;
118 &lt;/bar&gt;
119 &lt;bar&gt;
120 &lt;baz&gt;1&lt;/baz&gt;
121 &lt;/bar&gt;
122 &lt;/foo&gt;</PRE>
123 <P>The recursive nature of this algorithm means that certain tree
124 comparisons will explode wrt time and memory. I think this will only
125 happen with very deep trees where nodes high up in the tree can only
126 be differentiated by nodes low down in the tree.</P>
127 <P>Both trees are loaded into memory to begin with, so it may thrash with
128 very large documents</P>
129 <P>
130 <H2><A NAME="author">AUTHOR</A></H2>
131 <P>Chris Mungall
132 cjm at fruitfly dot org</P>
133 <P>
134 <HR>
135 <H1><A NAME="see also">SEE ALSO</A></H1>
136 <P><A HREF="./Data/Stag.html">the Data::Stag manpage</A></P>
137
138 </BODY>
139
140 </HTML>