giscanner/girparser.py

   1 # -*- Mode: Python -*-
   2 # GObject-Introspection - a framework for introspecting GObject libraries
   3 # Copyright (C) 2008  Johan Dahlin
   4 #
   5 # This library is free software; you can redistribute it and/or
   6 # modify it under the terms of the GNU Lesser General Public
   7 # License as published by the Free Software Foundation; either
   8 # version 2 of the License, or (at your option) any later version.
   9 #
  10 # This library is distributed in the hope that it will be useful,
  11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 # Lesser General Public License for more details.
  14 #
  15 # You should have received a copy of the GNU Lesser General Public
  16 # License along with this library; if not, write to the
  17 # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18 # Boston, MA 02111-1307, USA.
  19 #
  20
  21 import os
  22
  23 from xml.etree.cElementTree import parse
  24
  25 from . import ast
  26 from .girwriter import COMPATIBLE_GIR_VERSION
  27
  28 CORE_NS = "http://www.gtk.org/introspection/core/1.0"
  29 C_NS = "http://www.gtk.org/introspection/c/1.0"
  30 GLIB_NS = "http://www.gtk.org/introspection/glib/1.0"
  31
  32
  33 def _corens(tag):
  34     return '{%s}%s' % (CORE_NS, tag)
  35
  36
  37 def _glibns(tag):
  38     return '{%s}%s' % (GLIB_NS, tag)
  39
  40
  41 def _cns(tag):
  42     return '{%s}%s' % (C_NS, tag)
  43
  44
  45 class GIRParser(object):
  46
  47     def __init__(self, types_only=False):
  48         self._types_only = types_only
  49         self._shared_libraries = []
  50         self._includes = set()
  51         self._pkgconfig_packages = set()
  52         self._namespace = None
  53         self._filename_stack = []
  54
  55     # Public API
  56
  57     def parse(self, filename):
  58         filename = os.path.abspath(filename)
  59         self._filename_stack.append(filename)
  60         tree = parse(filename)
  61         self.parse_tree(tree)
  62         self._filename_stack.pop()
  63
  64     def parse_tree(self, tree):
  65         self._includes.clear()
  66         self._namespace = None
  67         self._shared_libraries = []
  68         self._pkgconfig_packages = set()
  69         self._c_includes = set()
  70         self._c_prefix = None
  71         self._parse_api(tree.getroot())
  72
  73     def get_namespace(self):
  74         return self._namespace
  75
  76     def get_shared_libraries(self):
  77         return self._shared_libraries
  78
  79     def get_includes(self):
  80         return self._includes
  81
  82     def get_c_includes(self):
  83         return self._c_includes
  84
  85     def get_c_prefix(self):
  86         return self._c_prefix
  87
  88     def get_pkgconfig_packages(self):
  89         if not hasattr(self, '_pkgconfig_packages'):
  90             self._pkgconfig_packages = []
  91         return self._pkgconfig_packages
  92
  93     def get_doc(self):
  94         return parse(self._filename)
  95
  96     # Private
  97
  98     def _find_first_child(self, node, name_or_names):
  99         if isinstance(name_or_names, str):
 100             for child in node.getchildren():
 101                 if child.tag == name_or_names:
 102                     return child
 103         else:
 104             for child in node.getchildren():
 105                 if child.tag in name_or_names:
 106                     return child
 107         return None
 108
 109     def _find_children(self, node, name):
 110         return [child for child in node.getchildren() if child.tag == name]
 111
 112     def _get_current_file(self):
 113         if not self._filename_stack:
 114             return None
 115         cwd = os.getcwd() + os.sep
 116         curfile = self._filename_stack[-1]
 117         if curfile.startswith(cwd):
 118             return curfile[len(cwd):]
 119         return curfile
 120
 121     def _parse_api(self, root):
 122         assert root.tag == _corens('repository')
 123         version = root.attrib['version']
 124         if version != COMPATIBLE_GIR_VERSION:
 125             raise SystemExit("%s: Incompatible version %s (supported: %s)" \
 126                              % (self._get_current_file(),
 127                                 version, COMPATIBLE_GIR_VERSION))
 128
 129         for node in root.getchildren():
 130             if node.tag == _corens('include'):
 131                 self._parse_include(node)
 132             elif node.tag == _corens('package'):
 133                 self._parse_pkgconfig_package(node)
 134             elif node.tag == _cns('include'):
 135                 self._parse_c_include(node)
 136
 137         ns = root.find(_corens('namespace'))
 138         assert ns is not None
 139         identifier_prefixes = ns.attrib.get(_cns('identifier-prefixes'))
 140         if identifier_prefixes:
 141             identifier_prefixes = identifier_prefixes.split(',')
 142         symbol_prefixes = ns.attrib.get(_cns('symbol-prefixes'))
 143         if symbol_prefixes:
 144             symbol_prefixes = symbol_prefixes.split(',')
 145         self._namespace = ast.Namespace(ns.attrib['name'],
 146                                     ns.attrib['version'],
 147                                     identifier_prefixes=identifier_prefixes,
 148                                     symbol_prefixes=symbol_prefixes)
 149         if 'shared-library' in ns.attrib:
 150             self._shared_libraries.extend(
 151                 ns.attrib['shared-library'].split(','))
 152
 153         parser_methods = {
 154             _corens('alias'): self._parse_alias,
 155             _corens('bitfield'): self._parse_enumeration_bitfield,
 156             _corens('callback'): self._parse_callback,
 157             _corens('class'): self._parse_object_interface,
 158             _corens('enumeration'): self._parse_enumeration_bitfield,
 159             _corens('interface'): self._parse_object_interface,
 160             _corens('record'): self._parse_record,
 161             _corens('union'): self._parse_union,
 162             _glibns('boxed'): self._parse_boxed,
 163             }
 164
 165         if not self._types_only:
 166             parser_methods[_corens('constant')] = self._parse_constant
 167             parser_methods[_corens('function')] = self._parse_function
 168
 169         for node in ns.getchildren():
 170             method = parser_methods.get(node.tag)
 171             if method is not None:
 172                 method(node)
 173
 174     def _parse_include(self, node):
 175         include = ast.Include(node.attrib['name'],
 176                           node.attrib['version'])
 177         self._includes.add(include)
 178
 179     def _parse_pkgconfig_package(self, node):
 180         self._pkgconfig_packages.add(node.attrib['name'])
 181
 182     def _parse_c_include(self, node):
 183         self._c_includes.add(node.attrib['name'])
 184
 185     def _parse_alias(self, node):
 186         typeval = self._parse_type(node)
 187         alias = ast.Alias(node.attrib['name'],
 188                       typeval,
 189                       node.attrib.get(_cns('type')))
 190         self._parse_generic_attribs(node, alias)
 191         self._namespace.append(alias)
 192
 193     def _parse_generic_attribs(self, node, obj):
 194         assert isinstance(obj, ast.Annotated)
 195         introspectable = node.attrib.get('introspectable')
 196         if introspectable:
 197             obj.introspectable = int(introspectable) > 0
 198         if self._types_only:
 199             return
 200         doc = node.find(_corens('doc'))
 201         if doc is not None:
 202             if doc.text:
 203                 obj.doc = doc.text
 204         version = node.attrib.get('version')
 205         if version:
 206             obj.version = version
 207         deprecated = node.attrib.get('deprecated')
 208         if deprecated:
 209             obj.deprecated = deprecated
 210         deprecated_version = node.attrib.get('deprecated-version')
 211         if deprecated_version:
 212             obj.deprecated_version = deprecated_version
 213
 214     def _parse_object_interface(self, node):
 215         parent = node.attrib.get('parent')
 216         if parent:
 217             parent_type = self._namespace.type_from_name(parent)
 218         else:
 219             parent_type = None
 220
 221         ctor_args = [node.attrib['name'],
 222                      parent_type]
 223         ctor_kwargs = {'gtype_name': node.attrib[_glibns('type-name')],
 224                        'get_type': node.attrib[_glibns('get-type')],
 225                        'c_symbol_prefix': node.attrib.get(_cns('symbol-prefix')),
 226                        'ctype': node.attrib.get(_cns('type'))}
 227         if node.tag == _corens('interface'):
 228             klass = ast.Interface
 229         elif node.tag == _corens('class'):
 230             klass = ast.Class
 231             is_abstract = node.attrib.get('abstract')
 232             is_abstract = is_abstract and is_abstract != '0'
 233             ctor_kwargs['is_abstract'] = is_abstract
 234         else:
 235             raise AssertionError(node)
 236
 237         obj = klass(*ctor_args, **ctor_kwargs)
 238         self._parse_generic_attribs(node, obj)
 239         type_struct = node.attrib.get(_glibns('type-struct'))
 240         if type_struct:
 241             obj.glib_type_struct = self._namespace.type_from_name(type_struct)
 242         if klass == ast.Class:
 243             is_fundamental = node.attrib.get(_glibns('fundamental'))
 244             if is_fundamental and is_fundamental != '0':
 245                 obj.fundamental = True
 246             for func_id in ['ref-func', 'unref-func',
 247                             'set-value-func', 'get-value-func']:
 248                 func_name = node.attrib.get(_glibns(func_id))
 249                 obj.__dict__[func_id.replace('-', '_')] = func_name
 250         self._namespace.append(obj)
 251
 252         if self._types_only:
 253             return
 254         for iface in self._find_children(node, _corens('implements')):
 255             obj.interfaces.append(self._namespace.type_from_name(iface.attrib['name']))
 256         for iface in self._find_children(node, _corens('prerequisite')):
 257             obj.prerequisites.append(self._namespace.type_from_name(iface.attrib['name']))
 258         for func_node in self._find_children(node, _corens('function')):
 259             func = self._parse_function_common(func_node, ast.Function, obj)
 260             obj.static_methods.append(func)
 261         for method in self._find_children(node, _corens('method')):
 262             func = self._parse_function_common(method, ast.Function, obj)
 263             func.is_method = True
 264             obj.methods.append(func)
 265         for method in self._find_children(node, _corens('virtual-method')):
 266             func = self._parse_function_common(method, ast.VFunction, obj)
 267             self._parse_generic_attribs(method, func)
 268             func.is_method = True
 269             func.invoker = method.get('invoker')
 270             obj.virtual_methods.append(func)
 271         for ctor in self._find_children(node, _corens('constructor')):
 272             func = self._parse_function_common(ctor, ast.Function, obj)
 273             func.is_constructor = True
 274             obj.constructors.append(func)
 275         obj.fields.extend(self._parse_fields(node))
 276         for prop in self._find_children(node, _corens('property')):
 277             obj.properties.append(self._parse_property(prop, obj))
 278         for signal in self._find_children(node, _glibns('signal')):
 279             obj.signals.append(self._parse_function_common(signal, ast.Signal, obj))
 280
 281     def _parse_callback(self, node):
 282         callback = self._parse_function_common(node, ast.Callback)
 283         self._namespace.append(callback)
 284
 285     def _parse_function(self, node):
 286         function = self._parse_function_common(node, ast.Function)
 287         self._namespace.append(function)
 288
 289     def _parse_function_common(self, node, klass, parent=None):
 290         name = node.attrib['name']
 291         returnnode = node.find(_corens('return-value'))
 292         if not returnnode:
 293             raise ValueError('node %r has no return-value' % (name, ))
 294         transfer = returnnode.attrib.get('transfer-ownership')
 295         retval = ast.Return(self._parse_type(returnnode), transfer)
 296         self._parse_generic_attribs(returnnode, retval)
 297         parameters = []
 298
 299         throws = (node.attrib.get('throws') == '1')
 300
 301         if klass is ast.Callback:
 302             func = klass(name, retval, parameters, throws,
 303                          node.attrib.get(_cns('type')))
 304         elif klass is ast.Function:
 305             identifier = node.attrib.get(_cns('identifier'))
 306             func = klass(name, retval, parameters, throws, identifier)
 307         elif klass is ast.VFunction:
 308             func = klass(name, retval, parameters, throws)
 309         elif klass is ast.Signal:
 310             func = klass(name, retval, parameters,
 311                          when=node.attrib.get('when'),
 312                          no_recurse=node.attrib.get('no-recurse', '0') == '1',
 313                          detailed=node.attrib.get('detailed', '0') == '1',
 314                          action=node.attrib.get('action', '0') == '1',
 315                          no_hooks=node.attrib.get('no-hooks', '0') == '1')
 316         else:
 317             assert False
 318
 319         func.shadows = node.attrib.get('shadows', None)
 320         func.shadowed_by = node.attrib.get('shadowed-by', None)
 321         func.moved_to = node.attrib.get('moved-to', None)
 322         func.parent = parent
 323
 324         parameters_node = node.find(_corens('parameters'))
 325         if (parameters_node is not None):
 326             for paramnode in self._find_children(parameters_node, _corens('parameter')):
 327                 typeval = self._parse_type(paramnode)
 328                 param = ast.Parameter(paramnode.attrib.get('name'),
 329                                   typeval,
 330                                   paramnode.attrib.get('direction') or ast.PARAM_DIRECTION_IN,
 331                                   paramnode.attrib.get('transfer-ownership'),
 332                                   paramnode.attrib.get('allow-none') == '1',
 333                                   paramnode.attrib.get('scope'),
 334                                   paramnode.attrib.get('caller-allocates') == '1')
 335                 self._parse_generic_attribs(paramnode, param)
 336                 parameters.append(param)
 337             for i, paramnode in enumerate(self._find_children(parameters_node,
 338                                                               _corens('parameter'))):
 339                 param = parameters[i]
 340                 self._parse_type_second_pass(func, paramnode, param.type)
 341                 closure = paramnode.attrib.get('closure')
 342                 if closure:
 343                     idx = int(closure)
 344                     assert idx < len(parameters), "%d >= %d" % (idx, len(parameters))
 345                     param.closure_name = parameters[idx].argname
 346                 destroy = paramnode.attrib.get('destroy')
 347                 if destroy:
 348                     idx = int(destroy)
 349                     assert idx < len(parameters), "%d >= %d" % (idx, len(parameters))
 350                     param.destroy_name = parameters[idx].argname
 351
 352         self._parse_type_second_pass(func, returnnode, retval.type)
 353
 354         self._parse_generic_attribs(node, func)
 355
 356         return func
 357
 358     def _parse_fields(self, node):
 359         res = []
 360         names = (_corens('field'), _corens('record'), _corens('union'), _corens('callback'))
 361         for child in node.getchildren():
 362             if child.tag in names:
 363                 fieldobj = self._parse_field(child)
 364                 res.append(fieldobj)
 365         return res
 366
 367     def _parse_compound(self, cls, node):
 368         compound = cls(node.attrib.get('name'),
 369                        ctype=node.attrib.get(_cns('type')),
 370                        disguised=node.attrib.get('disguised') == '1',
 371                        gtype_name=node.attrib.get(_glibns('type-name')),
 372                        get_type=node.attrib.get(_glibns('get-type')),
 373                        c_symbol_prefix=node.attrib.get(_cns('symbol-prefix')))
 374         if node.attrib.get('foreign') == '1':
 375             compound.foreign = True
 376         self._parse_generic_attribs(node, compound)
 377         if not self._types_only:
 378             compound.fields.extend(self._parse_fields(node))
 379             for method in self._find_children(node, _corens('method')):
 380                 compound.methods.append(
 381                     self._parse_function_common(method, ast.Function, compound))
 382             for func in self._find_children(node, _corens('function')):
 383                 compound.static_methods.append(
 384                     self._parse_function_common(func, ast.Function, compound))
 385             for ctor in self._find_children(node, _corens('constructor')):
 386                 compound.constructors.append(
 387                     self._parse_function_common(ctor, ast.Function, compound))
 388         return compound
 389
 390     def _parse_record(self, node, anonymous=False):
 391         struct = self._parse_compound(ast.Record, node)
 392         is_gtype_struct_for = node.attrib.get(_glibns('is-gtype-struct-for'))
 393         if is_gtype_struct_for is not None:
 394             struct.is_gtype_struct_for = self._namespace.type_from_name(is_gtype_struct_for)
 395         if not anonymous:
 396             self._namespace.append(struct)
 397         return struct
 398
 399     def _parse_union(self, node, anonymous=False):
 400         union = self._parse_compound(ast.Union, node)
 401         if not anonymous:
 402             self._namespace.append(union)
 403         return union
 404
 405     def _parse_type_simple(self, typenode):
 406         # ast.Fields can contain inline callbacks
 407         if typenode.tag == _corens('callback'):
 408             typeval = self._namespace.type_from_name(typenode.attrib['name'])
 409             typeval.ctype = typenode.attrib.get(_cns('type'))
 410             return typeval
 411         # ast.Arrays have their own toplevel XML
 412         elif typenode.tag == _corens('array'):
 413             array_type = typenode.attrib.get('name')
 414             element_type = self._parse_type(typenode)
 415             array_ctype = typenode.attrib.get(_cns('type'))
 416             ret = ast.Array(array_type, element_type, ctype=array_ctype)
 417             # zero-terminated defaults to true...
 418             zero = typenode.attrib.get('zero-terminated')
 419             if zero and zero == '0':
 420                 ret.zeroterminated = False
 421             fixed_size = typenode.attrib.get('fixed-size')
 422             if fixed_size:
 423                 ret.size = int(fixed_size)
 424
 425             return ret
 426         elif typenode.tag == _corens('varargs'):
 427             return ast.Varargs()
 428         elif typenode.tag == _corens('type'):
 429             name = typenode.attrib.get('name')
 430             ctype = typenode.attrib.get(_cns('type'))
 431             if name is None:
 432                 if ctype is None:
 433                     return ast.TypeUnknown()
 434                 return ast.Type(ctype=ctype)
 435             elif name in ['GLib.List', 'GLib.SList']:
 436                 subchild = self._find_first_child(typenode,
 437                                map(_corens, ('callback', 'array', 'varargs', 'type')))
 438                 if subchild is not None:
 439                     element_type = self._parse_type(typenode)
 440                 else:
 441                     element_type = ast.TYPE_ANY
 442                 return ast.List(name, element_type, ctype=ctype)
 443             elif name == 'GLib.HashTable':
 444                 subchildren = self._find_children(typenode, _corens('type'))
 445                 subchildren_types = map(self._parse_type_simple, subchildren)
 446                 while len(subchildren_types) < 2:
 447                     subchildren_types.append(ast.TYPE_ANY)
 448                 return ast.Map(subchildren_types[0],
 449                            subchildren_types[1],
 450                            ctype=ctype)
 451             else:
 452                 return self._namespace.type_from_name(name, ctype)
 453         else:
 454             assert False, "Failed to parse inner type"
 455
 456     def _parse_type(self, node):
 457         for name in map(_corens, ('callback', 'array', 'varargs', 'type')):
 458             typenode = node.find(name)
 459             if typenode is not None:
 460                 return self._parse_type_simple(typenode)
 461         assert False, "Failed to parse toplevel type"
 462
 463     def _parse_type_second_pass(self, parent, node, typeval):
 464         """A hack necessary to handle the integer parameter indexes on
 465            array types."""
 466         typenode = node.find(_corens('array'))
 467         if typenode is None:
 468             return
 469         lenidx = typenode.attrib.get('length')
 470         if lenidx is not None:
 471             idx = int(lenidx)
 472             assert idx < len(parent.parameters), "%r %d >= %d" \
 473                       % (parent, idx, len(parent.parameters))
 474             typeval.length_param_name = parent.parameters[idx].argname
 475
 476     def _parse_boxed(self, node):
 477         obj = ast.Boxed(node.attrib[_glibns('name')],
 478                         gtype_name=node.attrib[_glibns('type-name')],
 479                         get_type=node.attrib[_glibns('get-type')],
 480                         c_symbol_prefix=node.attrib.get(_cns('symbol-prefix')))
 481         self._parse_generic_attribs(node, obj)
 482         self._namespace.append(obj)
 483         if self._types_only:
 484             return
 485         for method in self._find_children(node, _corens('method')):
 486             func = self._parse_function_common(method, ast.Function, obj)
 487             func.is_method = True
 488             obj.methods.append(func)
 489         for ctor in self._find_children(node, _corens('constructor')):
 490             obj.constructors.append(
 491                 self._parse_function_common(ctor, ast.Function, obj))
 492         for callback in self._find_children(node, _corens('callback')):
 493             obj.fields.append(
 494                 self._parse_function_common(callback, ast.Callback, obj))
 495
 496     def _parse_field(self, node):
 497         type_node = None
 498         anonymous_node = None
 499         if node.tag in map(_corens, ('record', 'union')):
 500             anonymous_elt = node
 501         else:
 502             anonymous_elt = self._find_first_child(node, _corens('callback'))
 503         if anonymous_elt is not None:
 504             if anonymous_elt.tag == _corens('callback'):
 505                 anonymous_node = self._parse_function_common(anonymous_elt, ast.Callback)
 506             elif anonymous_elt.tag == _corens('record'):
 507                 anonymous_node = self._parse_record(anonymous_elt, anonymous=True)
 508             elif anonymous_elt.tag == _corens('union'):
 509                 anonymous_node = self._parse_union(anonymous_elt, anonymous=True)
 510             else:
 511                 assert False, anonymous_elt.tag
 512         else:
 513             assert node.tag == _corens('field'), node.tag
 514             type_node = self._parse_type(node)
 515         field = ast.Field(node.attrib.get('name'),
 516                       type_node,
 517                       node.attrib.get('readable') != '0',
 518                       node.attrib.get('writable') == '1',
 519                       node.attrib.get('bits'),
 520                       anonymous_node=anonymous_node)
 521         field.private = node.attrib.get('private') == '1'
 522         self._parse_generic_attribs(node, field)
 523         return field
 524
 525     def _parse_property(self, node, parent):
 526         prop = ast.Property(node.attrib['name'],
 527                         self._parse_type(node),
 528                         node.attrib.get('readable') != '0',
 529                         node.attrib.get('writable') == '1',
 530                         node.attrib.get('construct') == '1',
 531                         node.attrib.get('construct-only') == '1',
 532                         node.attrib.get('transfer-ownership'))
 533         self._parse_generic_attribs(node, prop)
 534         prop.parent = parent
 535         return prop
 536
 537     def _parse_member(self, node):
 538         member = ast.Member(node.attrib['name'],
 539                             node.attrib['value'],
 540                             node.attrib.get(_cns('identifier')),
 541                             node.attrib.get(_glibns('nick')))
 542         self._parse_generic_attribs(node, member)
 543         return member
 544
 545     def _parse_constant(self, node):
 546         type_node = self._parse_type(node)
 547         constant = ast.Constant(node.attrib['name'],
 548                                 type_node,
 549                                 node.attrib['value'],
 550                                 node.attrib.get(_cns('type')))
 551         self._parse_generic_attribs(node, constant)
 552         self._namespace.append(constant)
 553
 554     def _parse_enumeration_bitfield(self, node):
 555         name = node.attrib.get('name')
 556         ctype = node.attrib.get(_cns('type'))
 557         get_type = node.attrib.get(_glibns('get-type'))
 558         type_name = node.attrib.get(_glibns('type-name'))
 559         glib_error_domain = node.attrib.get(_glibns('error-domain'))
 560         if node.tag == _corens('bitfield'):
 561             klass = ast.Bitfield
 562         else:
 563             klass = ast.Enum
 564         members = []
 565         obj = klass(name, ctype,
 566                     members=members,
 567                     gtype_name=type_name,
 568                     get_type=get_type)
 569         obj.error_domain = glib_error_domain
 570         obj.ctype = ctype
 571         self._parse_generic_attribs(node, obj)
 572         self._namespace.append(obj)
 573
 574         if self._types_only:
 575             return
 576         for member in self._find_children(node, _corens('member')):
 577             members.append(self._parse_member(member))
 578         for func_node in self._find_children(node, _corens('function')):
 579             func = self._parse_function_common(func_node, ast.Function)
 580             obj.static_methods.append(func)