Debian Codegraph @

doc/SystemTap_Tapset_Reference/overload.py

raw
1 # XML tree transformation for systemtap function overloading
2 # This script merges all overloaded tapset function entries
3 # into one entry.
4
5 import sys
6 from lxml import etree
7
8 DEBUG = 0
9
10 def collect_overloads(refentries):
11 """
12 Collect overloads into lists.
13 """
14 functions = {}
15 for entry in refentries:
16 name = entry.xpath("refnamediv/refname")[0].text
17 if name not in functions:
18 functions[name] = []
19 functions[name].append(entry)
20 return {k: v for (k, v) in functions.items() if len(v) > 1}
21
22 def get_params(functions):
23 """
24 Return a parameter list containing the parameters for all overloads.
25 """
26 seen = set()
27 params = []
28 for overload in functions:
29 refsect = overload.xpath("refsect1[1]")[0]
30 # add variablelist node for future construction
31 if len(refsect.xpath("variablelist")) == 0:
32 refsect.remove(refsect[1])
33 etree.SubElement(refsect, "variablelist")
34 continue
35 param_list = refsect.xpath("variablelist")[0].getchildren()
36 for param in param_list:
37 name = param.xpath("term/parameter")[0].text
38 if name not in seen:
39 seen.add(name)
40 params.append(param)
41 return params
42
43 def annotate(entry):
44 """
45 Numbers all overloaded entries.
46 """
47 num_overloads = len(entry.xpath("refsynopsisdiv/programlisting"))
48 synopsis = entry.xpath("refsynopsisdiv/programlisting")
49 description = entry.xpath("refsect1[2]/para")
50 for i in range(num_overloads):
51 synopsis[i].text = str(i+1) + ")" + " " + synopsis[i].text.strip()
52 description[i].text = str(i+1) + ")" + " " + description[i].text.strip()
53
54 def merge(functions):
55 """
56 Merge matching refentries into one and delete them from their parents.
57 """
58 merged = functions[0]
59
60 # merge params
61 new_params = get_params(functions)
62 param_list = merged.xpath("refsect1[1]/variablelist")[0]
63 for param in param_list:
64 param.getparent().remove(param)
65 for param in new_params:
66 param_list.append(param)
67
68 # merge synopsis and descriptions
69 description = merged.xpath("refsect1[2]")[0]
70 synopsis = merged.xpath("refsynopsisdiv")[0]
71 for overload in functions[1:]:
72 synopsis.append(overload.xpath("refsynopsisdiv/programlisting")[0])
73 description.append(overload.xpath("refsect1[2]/para")[0])
74 overload.getparent().remove(overload)
75
76 annotate(merged)
77
78 def merge_overloads(functions_list):
79 for functions in functions_list.values():
80 merge(functions)
81
82 def usage():
83 print("Usage: ./overload.py <xml>")
84
85 def main():
86 if len(sys.argv) != 2:
87 usage()
88 sys.exit()
89 parser = etree.XMLParser(remove_comments=False)
90 tree = etree.parse(sys.argv[1], parser=parser)
91 root = tree.getroot()
92 refentries = [r for r in root.iter("refentry")]
93 functions = collect_overloads(refentries)
94 merge_overloads(functions)
95 output_file = getattr(sys.stdout, "buffer", sys.stdout)
96 tree.write(output_file, encoding="UTF-8", xml_declaration=True)
97
98 if __name__ == '__main__':
99 main()