| 1 |
#!/usr/bin/env python |
| 2 |
# |
| 3 |
# Copyright 2015 The Geany contributors |
| 4 |
# Copyright 2021 Collabora Ltd. |
| 5 |
# @author George Kiagiadakis <[email protected]> |
| 6 |
# |
| 7 |
# This program is free software; you can redistribute it and/or modify |
| 8 |
# it under the terms of the GNU General Public License as published by |
| 9 |
# the Free Software Foundation; either version 2 of the License, or |
| 10 |
# (at your option) any later version. |
| 11 |
# |
| 12 |
# This program is distributed in the hope that it will be useful, |
| 13 |
# but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 14 |
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 15 |
# GNU General Public License for more details. |
| 16 |
# |
| 17 |
# You should have received a copy of the GNU General Public License |
| 18 |
# along with this program; if not, write to the Free Software |
| 19 |
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, |
| 20 |
# MA 02110-1301, USA. |
| 21 |
|
| 22 |
import os |
| 23 |
import sys |
| 24 |
import re |
| 25 |
from lxml import etree |
| 26 |
from optparse import OptionParser |
| 27 |
|
| 28 |
|
| 29 |
def normalize_text(s): |
| 30 |
r""" |
| 31 |
Normalizes whitespace in text. |
| 32 |
>>> normalize_text("asd xxx") |
| 33 |
'asd xxx' |
| 34 |
>>> normalize_text(" asd\nxxx ") |
| 35 |
'asd xxx' |
| 36 |
""" |
| 37 |
return s.replace("\n", " ").strip() |
| 38 |
|
| 39 |
|
| 40 |
CXX_NAMESPACE_RE = re.compile(r'[_a-zA-Z][_0-9a-zA-Z]*::') |
| 41 |
def fix_definition(s): |
| 42 |
""" |
| 43 |
Removes C++ name qualifications from some definitions. |
| 44 |
For example: |
| 45 |
>>> fix_definition("bool flag") |
| 46 |
'bool flag' |
| 47 |
>>> fix_definition("bool FooBar::flag") |
| 48 |
'bool flag' |
| 49 |
>>> fix_definition("void(* _GeanyObjectClass::project_open) (GKeyFile *keyfile)") |
| 50 |
'void(* project_open) (GKeyFile *keyfile)' |
| 51 |
""" |
| 52 |
return CXX_NAMESPACE_RE.sub(r"", s) |
| 53 |
|
| 54 |
|
| 55 |
class AtDoc(object): |
| 56 |
def __init__(self): |
| 57 |
self.retval = None |
| 58 |
self.since = "" |
| 59 |
self.annot = [] |
| 60 |
|
| 61 |
def cb(self, type, str): |
| 62 |
if (type == "param"): |
| 63 |
words = str.split(" ", 2) |
| 64 |
self.annot = [] |
| 65 |
elif (type == "return"): |
| 66 |
self.annot = [] |
| 67 |
elif (type == "since"): |
| 68 |
self.since = str.rstrip() |
| 69 |
elif (type == "see"): |
| 70 |
return "See " + str |
| 71 |
elif type in ("a", "c") and str in ("NULL", "TRUE", "FALSE"): |
| 72 |
return "%" + str |
| 73 |
elif (type == "a"): |
| 74 |
return "@" + str |
| 75 |
else: |
| 76 |
return str |
| 77 |
|
| 78 |
return "" |
| 79 |
|
| 80 |
|
| 81 |
class DoxygenProcess(object): |
| 82 |
def __init__(self): |
| 83 |
self.at = None |
| 84 |
|
| 85 |
# http://stackoverflow.com/questions/4624062/get-all-text-inside-a-tag-in-lxml |
| 86 |
@staticmethod |
| 87 |
def stringify_children(node): |
| 88 |
from lxml.etree import tostring |
| 89 |
from itertools import chain |
| 90 |
parts = ([node.text] + |
| 91 |
list(chain(*([c.text, tostring(c).decode("utf-8"), c.tail] for c in node.getchildren()))) + |
| 92 |
[node.tail]) |
| 93 |
# filter removes possible Nones in texts and tails |
| 94 |
return "".join(filter(None, parts)) |
| 95 |
|
| 96 |
def get_program_listing(self, xml): |
| 97 |
from lxml.etree import tostring |
| 98 |
arr = ["", "|[<!-- language=\"C\" -->"] |
| 99 |
for l in xml.getchildren(): |
| 100 |
if (l.tag == "codeline"): |
| 101 |
# a codeline is of the form |
| 102 |
# <highlight class="normal">GeanyDocument<sp/>*doc<sp/>=<sp/>...;</highlight> |
| 103 |
# <sp/> tags must be replaced with spaces, then just use the text |
| 104 |
h = l.find("highlight") |
| 105 |
if h is not None: |
| 106 |
html = tostring(h).decode("utf-8") |
| 107 |
html = html.replace("<sp/>", " ") |
| 108 |
arr.append(" " + tostring(etree.HTML(html), method="text").decode("utf-8")) |
| 109 |
arr.append("]|") |
| 110 |
return "\n".join(arr) |
| 111 |
|
| 112 |
def join_annot(self): |
| 113 |
s = " ".join(map(lambda x: "(%s)" % x, self.at.annot)) |
| 114 |
return s + ": " if s else "" |
| 115 |
|
| 116 |
def process_element(self, xml): |
| 117 |
self.at = AtDoc() |
| 118 |
s = self.__process_element(xml) |
| 119 |
return s |
| 120 |
|
| 121 |
def get_extra(self): |
| 122 |
return self.join_annot() |
| 123 |
|
| 124 |
def get_return(self): |
| 125 |
return self.at.retval |
| 126 |
|
| 127 |
def get_since(self): |
| 128 |
return self.at.since |
| 129 |
|
| 130 |
def __process_element(self, xml): |
| 131 |
s = "" |
| 132 |
|
| 133 |
if xml.text and re.search(r'\S', xml.text): |
| 134 |
s += xml.text |
| 135 |
for n in xml.getchildren(): |
| 136 |
if n.tag == "emphasis": |
| 137 |
s += self.at.cb("a", self.__process_element(n)) |
| 138 |
if n.tag == "computeroutput": |
| 139 |
s += self.at.cb("c", self.__process_element(n)) |
| 140 |
if n.tag == "itemizedlist": |
| 141 |
s += "\n" + self.__process_element(n) |
| 142 |
if n.tag == "listitem": |
| 143 |
s += " - " + self.__process_element(n) |
| 144 |
if n.tag == "para": |
| 145 |
p = self.__process_element(n) |
| 146 |
if re.search(r'\S', p): |
| 147 |
s += p + "\n" |
| 148 |
if n.tag == "ref": |
| 149 |
s += n.text if n.text else "" |
| 150 |
if n.tag == "simplesect": |
| 151 |
ss = self.at.cb(n.get("kind"), self.__process_element(n)) |
| 152 |
s += ss + "\n" if ss else "" |
| 153 |
if n.tag == "programlisting": |
| 154 |
s += self.get_program_listing(n) |
| 155 |
if n.tag == "xrefsect": |
| 156 |
s += self.__process_element(n) |
| 157 |
if n.tag == "xreftitle": |
| 158 |
s += self.__process_element(n) + ": " |
| 159 |
if n.tag == "xrefdescription": |
| 160 |
s += self.__process_element(n) |
| 161 |
if n.tag == "ulink": |
| 162 |
s += self.__process_element(n) |
| 163 |
if n.tag == "linebreak": |
| 164 |
s += "\n" |
| 165 |
if n.tag == "ndash": |
| 166 |
s += "--" |
| 167 |
# workaround for doxygen bug #646002 |
| 168 |
if n.tag == "htmlonly": |
| 169 |
s += "" |
| 170 |
if n.tail: |
| 171 |
if re.search(r'\S', n.tail): |
| 172 |
s += n.tail |
| 173 |
if n.tag.startswith("param"): |
| 174 |
pass # parameters are handled separately in DoxyFunction::from_memberdef() |
| 175 |
return s |
| 176 |
|
| 177 |
|
| 178 |
class DoxyMember(object): |
| 179 |
def __init__(self, name, brief, extra=""): |
| 180 |
self.name = name |
| 181 |
self.brief = brief |
| 182 |
self.extra = extra |
| 183 |
|
| 184 |
|
| 185 |
class DoxyElement(object): |
| 186 |
|
| 187 |
def __init__(self, name, definition, **kwargs): |
| 188 |
self.name = name |
| 189 |
self.definition = definition |
| 190 |
self.brief = kwargs.get('brief', "") |
| 191 |
self.detail = kwargs.get('detail', "") |
| 192 |
self.members = kwargs.get('members', []) |
| 193 |
self.since = kwargs.get('since', "") |
| 194 |
self.extra = kwargs.get('extra', "") |
| 195 |
self.retval = kwargs.get('retval', None) |
| 196 |
|
| 197 |
def is_documented(self): |
| 198 |
return (normalize_text(self.brief) != "" or |
| 199 |
normalize_text(self.detail) != "" or |
| 200 |
normalize_text(self.since) != "") |
| 201 |
|
| 202 |
def add_brief(self, xml): |
| 203 |
proc = DoxygenProcess() |
| 204 |
self.brief = proc.process_element(xml) |
| 205 |
self.extra += proc.get_extra() |
| 206 |
|
| 207 |
def add_detail(self, xml): |
| 208 |
proc = DoxygenProcess() |
| 209 |
self.detail = proc.process_element(xml) |
| 210 |
self.extra += proc.get_extra() |
| 211 |
self.since = proc.get_since() |
| 212 |
|
| 213 |
def add_member(self, xml): |
| 214 |
name = xml.find("name").text |
| 215 |
proc = DoxygenProcess() |
| 216 |
brief = proc.process_element(xml.find("briefdescription")) |
| 217 |
# optional doxygen command output appears within <detaileddescription /> |
| 218 |
proc.process_element(xml.find("detaileddescription")) |
| 219 |
self.members.append(DoxyMember(name, normalize_text(brief), proc.get_extra())) |
| 220 |
|
| 221 |
def add_param(self, xml): |
| 222 |
name = xml.find("parameternamelist").find("parametername").text |
| 223 |
proc = DoxygenProcess() |
| 224 |
brief = proc.process_element(xml.find("parameterdescription")) |
| 225 |
self.members.append(DoxyMember(name, normalize_text(brief), proc.get_extra())) |
| 226 |
|
| 227 |
def add_return(self, xml): |
| 228 |
proc = DoxygenProcess() |
| 229 |
brief = proc.process_element(xml) |
| 230 |
self.retval = DoxyMember("ret", normalize_text(brief), proc.get_extra()) |
| 231 |
|
| 232 |
def to_gtkdoc(self): |
| 233 |
s = [] |
| 234 |
s.append("/**") |
| 235 |
s.append(" * %s: %s" % (self.name, self.extra)) |
| 236 |
for p in self.members: |
| 237 |
s.append(" * @%s: %s %s" % (p.name, p.extra, p.brief)) |
| 238 |
s.append(" *") |
| 239 |
s.append(" * %s" % self.brief.replace("\n", "\n * ")) |
| 240 |
s.append(" *") |
| 241 |
s.append(" * %s" % self.detail.replace("\n", "\n * ")) |
| 242 |
s.append(" *") |
| 243 |
if self.retval: |
| 244 |
s.append(" * Returns: %s %s" % (self.retval.extra, self.retval.brief)) |
| 245 |
if self.since: |
| 246 |
s.append(" *") |
| 247 |
s.append(" * Since: %s" % self.since) |
| 248 |
s.append(" */") |
| 249 |
s.append("") |
| 250 |
return "\n".join(s) |
| 251 |
|
| 252 |
|
| 253 |
class DoxyTypedef(DoxyElement): |
| 254 |
@staticmethod |
| 255 |
def from_memberdef(xml): |
| 256 |
name = xml.find("name").text |
| 257 |
d = normalize_text(xml.find("definition").text) |
| 258 |
d += ";" |
| 259 |
return DoxyTypedef(name, d) |
| 260 |
|
| 261 |
|
| 262 |
class DoxyEnum(DoxyElement): |
| 263 |
@staticmethod |
| 264 |
def from_memberdef(xml): |
| 265 |
name = xml.find("name").text |
| 266 |
d = "typedef enum {\n" |
| 267 |
for member in xml.findall("enumvalue"): |
| 268 |
v = member.find("initializer") |
| 269 |
d += "\t%s%s,\n" % (member.find("name").text, " "+v.text if v is not None else "") |
| 270 |
d += "} %s;\n" % name |
| 271 |
|
| 272 |
e = DoxyEnum(name, d) |
| 273 |
e.add_brief(xml.find("briefdescription")) |
| 274 |
e.add_detail(xml.find("detaileddescription")) |
| 275 |
for p in xml.findall("enumvalue"): |
| 276 |
e.add_member(p) |
| 277 |
return e |
| 278 |
|
| 279 |
|
| 280 |
class DoxyStruct(DoxyElement): |
| 281 |
@staticmethod |
| 282 |
def from_compounddef(xml, typedefs=[]): |
| 283 |
name = xml.find("compoundname").text |
| 284 |
d = "struct %s {\n" % name |
| 285 |
memberdefs = xml.xpath(".//sectiondef[@kind='public-attrib']/memberdef") |
| 286 |
for p in memberdefs: |
| 287 |
# workaround for struct members. g-ir-scanner can't properly map struct members |
| 288 |
# (beginning with struct GeanyFoo) to the typedef and assigns a generic type for them |
| 289 |
# thus we fix that up here and enforce usage of the typedef. These are written |
| 290 |
# out first, before any struct definition, for this reason |
| 291 |
# Exception: there are no typedefs for GeanyFooPrivate so skip those. Their exact |
| 292 |
# type isn't needed anyway |
| 293 |
s = fix_definition(p.find("definition").text).lstrip() |
| 294 |
proc = DoxygenProcess() |
| 295 |
brief = proc.process_element(p.find("briefdescription")) |
| 296 |
private = (normalize_text(brief) == "") |
| 297 |
words = s.split() |
| 298 |
if (words[0] == "struct"): |
| 299 |
if not (words[1].endswith("Private") or words[1].endswith("Private*")): |
| 300 |
s = " ".join(words[1:]) |
| 301 |
d += "\t/*< %s >*/\n\t%s;\n" % ("private" if private else "public", s) |
| 302 |
|
| 303 |
d += "};\n" |
| 304 |
e = DoxyStruct(name, d) |
| 305 |
e.add_brief(xml.find("briefdescription")) |
| 306 |
e.add_detail(xml.find("detaileddescription")) |
| 307 |
for p in memberdefs: |
| 308 |
e.add_member(p) |
| 309 |
return e |
| 310 |
|
| 311 |
|
| 312 |
class DoxyFunction(DoxyElement): |
| 313 |
@staticmethod |
| 314 |
def from_memberdef(xml): |
| 315 |
name = xml.find("name").text |
| 316 |
d = normalize_text(xml.find("definition").text) |
| 317 |
if ((xml.find("argsstring").text) is not None): |
| 318 |
d += " " + xml.find("argsstring").text + ";" |
| 319 |
d = normalize_text(d) |
| 320 |
|
| 321 |
e = DoxyFunction(name, d) |
| 322 |
if (xml.get("prot") == "private"): |
| 323 |
e.extra = "(skip)" |
| 324 |
e.add_brief(xml.find("briefdescription")) |
| 325 |
e.add_detail(xml.find("detaileddescription")) |
| 326 |
for p in xml.xpath(".//detaileddescription/*/parameterlist[@kind='param']/parameteritem"): |
| 327 |
e.add_param(p) |
| 328 |
x = xml.xpath(".//detaileddescription/*/simplesect[@kind='return']") |
| 329 |
if (len(x) > 0): |
| 330 |
e.add_return(x[0]) |
| 331 |
return e |
| 332 |
|
| 333 |
|
| 334 |
class DoxyVariable(DoxyElement): |
| 335 |
@staticmethod |
| 336 |
def from_memberdef(xml): |
| 337 |
name = xml.find("name").text |
| 338 |
d = normalize_text(xml.find("definition").text) |
| 339 |
d += ";" |
| 340 |
e = DoxyVariable(name, d) |
| 341 |
e.add_brief(xml.find("briefdescription")) |
| 342 |
t = xml.find("type") |
| 343 |
if t is not None: |
| 344 |
typestr = "".join(t.itertext()).strip() |
| 345 |
if typestr.startswith("const "): |
| 346 |
typestr = typestr[6:] |
| 347 |
e.type = "("+typestr+") " |
| 348 |
else: |
| 349 |
e.type = "" |
| 350 |
v = xml.find("initializer") |
| 351 |
e.value = v.text.replace("=","").replace("\n","") if v is not None else "" |
| 352 |
return e |
| 353 |
def to_gtkdoc(self): |
| 354 |
s = super().to_gtkdoc() |
| 355 |
# need this to get g-ir-scanner to recognize this as a constant |
| 356 |
s += "#define "+self.name+" ("+self.type+self.value+")\n" |
| 357 |
s += "#undef "+self.name+"\n" |
| 358 |
return s |
| 359 |
|
| 360 |
|
| 361 |
def main(args): |
| 362 |
xml_dir = None |
| 363 |
outfile = None |
| 364 |
|
| 365 |
parser = OptionParser(usage="usage: %prog [options] XML_DIR") |
| 366 |
parser.add_option("-o", "--output", metavar="FILE", help="Write output to FILE", |
| 367 |
action="store", dest="outfile") |
| 368 |
opts, args = parser.parse_args(args[1:]) |
| 369 |
|
| 370 |
xml_dir = args[0] |
| 371 |
|
| 372 |
if not (os.path.exists(xml_dir)): |
| 373 |
sys.stderr.write("invalid xml directory\n") |
| 374 |
return 1 |
| 375 |
|
| 376 |
symbols = [] |
| 377 |
transform = etree.XSLT(etree.parse(os.path.join(xml_dir, "combine.xslt"))) |
| 378 |
doc = etree.parse(os.path.join(xml_dir, "index.xml")) |
| 379 |
root = transform(doc) |
| 380 |
h_files = root.xpath(".//compounddef[@kind='file']/compoundname[substring(.,string-length(.)-1)='.h']/..") |
| 381 |
|
| 382 |
for f in h_files: |
| 383 |
for n0 in f.xpath(".//*/memberdef[@kind='enum']"): |
| 384 |
e = DoxyEnum.from_memberdef(n0) |
| 385 |
symbols.append(e) |
| 386 |
|
| 387 |
for n0 in root.xpath(".//compounddef[@kind='struct']"): |
| 388 |
e = DoxyStruct.from_compounddef(n0) |
| 389 |
symbols.append(e) |
| 390 |
|
| 391 |
for n0 in root.xpath(".//compounddef[@kind='group']"): |
| 392 |
for n1 in n0.xpath(".//*/memberdef[@kind='function']"): |
| 393 |
e = DoxyFunction.from_memberdef(n1) |
| 394 |
symbols.append(e) |
| 395 |
for n1 in n0.xpath(".//*/memberdef[@kind='variable']"): |
| 396 |
e = DoxyVariable.from_memberdef(n1) |
| 397 |
symbols.append(e) |
| 398 |
|
| 399 |
if (opts.outfile): |
| 400 |
try: |
| 401 |
outfile = open(opts.outfile, "w+") |
| 402 |
except OSError as err: |
| 403 |
sys.stderr.write("failed to open \"%s\" for writing (%s)\n" % (opts.outfile, err.strerror)) |
| 404 |
return 1 |
| 405 |
else: |
| 406 |
outfile = sys.stdout |
| 407 |
|
| 408 |
try: |
| 409 |
outfile.write("/*\n * Automatically generated file - do not edit\n */\n\n") |
| 410 |
|
| 411 |
for e in filter(lambda x: x.is_documented(), symbols): |
| 412 |
outfile.write("\n") |
| 413 |
outfile.write(e.to_gtkdoc()) |
| 414 |
outfile.write("\n") |
| 415 |
|
| 416 |
except BrokenPipeError: |
| 417 |
# probably piped to head or tail |
| 418 |
return 0 |
| 419 |
|
| 420 |
return 0 |
| 421 |
|
| 422 |
if __name__ == "__main__": |
| 423 |
sys.exit(main(sys.argv)) |