giscanner/girwriter.py

   1 # -*- Mode: Python -*-
   2 # GObject-Introspection - a framework for introspecting GObject libraries
   3 # Copyright (C) 2008  Johan Dahlin
   4 # Copyright (C) 2008, 2009 Red Hat, Inc.
   5 #
   6 # This library is free software; you can redistribute it and/or
   7 # modify it under the terms of the GNU Lesser General Public
   8 # License as published by the Free Software Foundation; either
   9 # version 2 of the License, or (at your option) any later version.
  10 #
  11 # This library is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 # Lesser General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU Lesser General Public
  17 # License along with this library; if not, write to the
  18 # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19 # Boston, MA 02111-1307, USA.
  20 #
  21
  22 from __future__ import with_statement
  23
  24 from . import ast
  25 from .xmlwriter import XMLWriter
  26
  27 # Bump this for *incompatible* changes to the .gir.
  28 # Compatible changes we just make inline
  29 COMPATIBLE_GIR_VERSION = '1.2'
  30
  31 class GIRWriter(XMLWriter):
  32
  33     def __init__(self, namespace, shlibs, includes, pkgs, c_includes):
  34         super(GIRWriter, self).__init__()
  35         self.write_comment(
  36 '''This file was automatically generated from C sources - DO NOT EDIT!
  37 To affect the contents of this file, edit the original C definitions,
  38 and/or use gtk-doc annotations. ''')
  39         self._write_repository(namespace, shlibs, includes, pkgs,
  40                                c_includes)
  41
  42     def _write_repository(self, namespace, shlibs, includes=None,
  43                           packages=None, c_includes=None):
  44         if includes is None:
  45             includes = frozenset()
  46         if packages is None:
  47             packages = frozenset()
  48         if c_includes is None:
  49             c_includes = frozenset()
  50         attrs = [
  51             ('version', COMPATIBLE_GIR_VERSION),
  52             ('xmlns', 'http://www.gtk.org/introspection/core/1.0'),
  53             ('xmlns:c', 'http://www.gtk.org/introspection/c/1.0'),
  54             ('xmlns:glib', 'http://www.gtk.org/introspection/glib/1.0'),
  55             ]
  56         with self.tagcontext('repository', attrs):
  57             for include in sorted(includes):
  58                 self._write_include(include)
  59             for pkg in sorted(set(packages)):
  60                 self._write_pkgconfig_pkg(pkg)
  61             for c_include in sorted(set(c_includes)):
  62                 self._write_c_include(c_include)
  63             self._namespace = namespace
  64             self._write_namespace(namespace, shlibs)
  65             self._namespace = None
  66
  67     def _write_include(self, include):
  68         attrs = [('name', include.name), ('version', include.version)]
  69         self.write_tag('include', attrs)
  70
  71     def _write_pkgconfig_pkg(self, package):
  72         attrs = [('name', package)]
  73         self.write_tag('package', attrs)
  74
  75     def _write_c_include(self, c_include):
  76         attrs = [('name', c_include)]
  77         self.write_tag('c:include', attrs)
  78
  79     def _write_namespace(self, namespace, shlibs):
  80         attrs = [('name', namespace.name),
  81                  ('version', namespace.version),
  82                  ('shared-library', ','.join(shlibs)),
  83                  ('c:identifier-prefixes', ','.join(namespace.identifier_prefixes)),
  84                  ('c:symbol-prefixes', ','.join(namespace.symbol_prefixes))]
  85         with self.tagcontext('namespace', attrs):
  86             # We define a custom sorting function here because
  87             # we want aliases to be first.  They're a bit
  88             # special because the typelib compiler expands them.
  89             def nscmp(a, b):
  90                 if isinstance(a, ast.Alias):
  91                     if isinstance(b, ast.Alias):
  92                         return cmp(a.name, b.name)
  93                     else:
  94                         return -1
  95                 elif isinstance(b, ast.Alias):
  96                     return 1
  97                 else:
  98                     return cmp(a, b)
  99             for node in sorted(namespace.itervalues(), cmp=nscmp):
 100                 self._write_node(node)
 101
 102     def _write_node(self, node):
 103         if isinstance(node, ast.Function):
 104             self._write_function(node)
 105         elif isinstance(node, ast.Enum):
 106             self._write_enum(node)
 107         elif isinstance(node, ast.Bitfield):
 108             self._write_bitfield(node)
 109         elif isinstance(node, (ast.Class, ast.Interface)):
 110             self._write_class(node)
 111         elif isinstance(node, ast.Callback):
 112             self._write_callback(node)
 113         elif isinstance(node, ast.Record):
 114             self._write_record(node)
 115         elif isinstance(node, ast.Union):
 116             self._write_union(node)
 117         elif isinstance(node, ast.Boxed):
 118             self._write_boxed(node)
 119         elif isinstance(node, ast.Member):
 120             # FIXME: atk_misc_instance singleton
 121             pass
 122         elif isinstance(node, ast.Alias):
 123             self._write_alias(node)
 124         elif isinstance(node, ast.Constant):
 125             self._write_constant(node)
 126         else:
 127             print 'WRITER: Unhandled node', node
 128
 129     def _append_version(self, node, attrs):
 130         if node.version:
 131             attrs.append(('version', node.version))
 132
 133     def _write_generic(self, node):
 134         for key, value in node.attributes:
 135             self.write_tag('attribute', [('name', key), ('value', value)])
 136         if hasattr(node, 'doc') and node.doc:
 137             self.write_tag('doc', [('xml:whitespace', 'preserve')],
 138                            node.doc)
 139
 140     def _append_node_generic(self, node, attrs):
 141         if node.skip or not node.introspectable:
 142             attrs.append(('introspectable', '0'))
 143         if node.deprecated:
 144             attrs.append(('deprecated', node.deprecated))
 145             if node.deprecated_version:
 146                 attrs.append(('deprecated-version',
 147                               node.deprecated_version))
 148
 149     def _append_throws(self, func, attrs):
 150         if func.throws:
 151             attrs.append(('throws', '1'))
 152
 153     def _write_alias(self, alias):
 154         attrs = [('name', alias.name)]
 155         if alias.ctype is not None:
 156             attrs.append(('c:type', alias.ctype))
 157         self._append_node_generic(alias, attrs)
 158         with self.tagcontext('alias', attrs):
 159             self._write_generic(alias)
 160             self._write_type_ref(alias.target)
 161
 162     def _write_callable(self, callable, tag_name, extra_attrs):
 163         attrs = [('name', callable.name)]
 164         attrs.extend(extra_attrs)
 165         self._append_version(callable, attrs)
 166         self._append_node_generic(callable, attrs)
 167         self._append_throws(callable, attrs)
 168         with self.tagcontext(tag_name, attrs):
 169             self._write_generic(callable)
 170             self._write_return_type(callable.retval, parent=callable)
 171             self._write_parameters(callable, callable.parameters)
 172
 173     def _write_function(self, func, tag_name='function'):
 174         attrs = []
 175         if hasattr(func, 'symbol'):
 176             attrs.append(('c:identifier', func.symbol))
 177         if func.shadowed_by:
 178             attrs.append(('shadowed-by', func.shadowed_by))
 179         elif func.shadows:
 180             attrs.append(('shadows', func.shadows))
 181         if func.moved_to is not None:
 182             attrs.append(('moved-to', func.moved_to))
 183         self._write_callable(func, tag_name, attrs)
 184
 185     def _write_method(self, method):
 186         self._write_function(method, tag_name='method')
 187
 188     def _write_static_method(self, method):
 189         self._write_function(method, tag_name='function')
 190
 191     def _write_constructor(self, method):
 192         self._write_function(method, tag_name='constructor')
 193
 194     def _write_return_type(self, return_, parent=None):
 195         if not return_:
 196             return
 197
 198         attrs = []
 199         if return_.transfer:
 200             attrs.append(('transfer-ownership', return_.transfer))
 201         if return_.skip:
 202             attrs.append(('skip', '1'))
 203         with self.tagcontext('return-value', attrs):
 204             self._write_generic(return_)
 205             self._write_type(return_.type, function=parent)
 206
 207     def _write_parameters(self, parent, parameters):
 208         if not parameters:
 209             return
 210         with self.tagcontext('parameters'):
 211             for parameter in parameters:
 212                 self._write_parameter(parent, parameter)
 213
 214     def _write_parameter(self, parent, parameter):
 215         attrs = []
 216         if parameter.argname is not None:
 217             attrs.append(('name', parameter.argname))
 218         if (parameter.direction is not None) and (parameter.direction != 'in'):
 219             attrs.append(('direction', parameter.direction))
 220             attrs.append(('caller-allocates',
 221                           '1' if parameter.caller_allocates else '0'))
 222         if parameter.transfer:
 223             attrs.append(('transfer-ownership',
 224                           parameter.transfer))
 225         if parameter.allow_none:
 226             attrs.append(('allow-none', '1'))
 227         if parameter.scope:
 228             attrs.append(('scope', parameter.scope))
 229         if parameter.closure_name is not None:
 230             idx = parent.get_parameter_index(parameter.closure_name)
 231             attrs.append(('closure', '%d' % (idx, )))
 232         if parameter.destroy_name is not None:
 233             idx = parent.get_parameter_index(parameter.destroy_name)
 234             attrs.append(('destroy', '%d' % (idx, )))
 235         if parameter.skip:
 236             attrs.append(('skip', '1'))
 237         with self.tagcontext('parameter', attrs):
 238             self._write_generic(parameter)
 239             self._write_type(parameter.type, function=parent)
 240
 241     def _type_to_name(self, typeval):
 242         if not typeval.resolved:
 243             raise AssertionError("Caught unresolved type %r (ctype=%r)" % (typeval, typeval.ctype))
 244         assert typeval.target_giname is not None
 245         prefix = self._namespace.name + '.'
 246         if typeval.target_giname.startswith(prefix):
 247             return typeval.target_giname[len(prefix):]
 248         return typeval.target_giname
 249
 250     def _write_type_ref(self, ntype):
 251         """ Like _write_type, but only writes the type name rather than the full details """
 252         assert isinstance(ntype, ast.Type), ntype
 253         attrs = []
 254         if ntype.ctype:
 255             attrs.append(('c:type', ntype.ctype))
 256         if isinstance(ntype, ast.Array):
 257             if ntype.array_type != ast.Array.C:
 258                 attrs.insert(0, ('name', ntype.array_type))
 259         elif isinstance(ntype, ast.List):
 260             if ntype.name:
 261                 attrs.insert(0, ('name', ntype.name))
 262         elif isinstance(ntype, ast.Map):
 263             attrs.insert(0, ('name', 'GLib.HashTable'))
 264         else:
 265             if ntype.target_giname:
 266                 attrs.insert(0, ('name', self._type_to_name(ntype)))
 267             elif ntype.target_fundamental:
 268                 attrs.insert(0, ('name', ntype.target_fundamental))
 269
 270         self.write_tag('type', attrs)
 271
 272     def _write_type(self, ntype, relation=None, function=None):
 273         assert isinstance(ntype, ast.Type), ntype
 274         attrs = []
 275         if ntype.ctype:
 276             attrs.append(('c:type', ntype.ctype))
 277         if isinstance(ntype, ast.Varargs):
 278             with self.tagcontext('varargs', []):
 279                 pass
 280         elif isinstance(ntype, ast.Array):
 281             if ntype.array_type != ast.Array.C:
 282                 attrs.insert(0, ('name', ntype.array_type))
 283             # we insert an explicit 'zero-terminated' attribute
 284             # when it is false, or when it would not be implied
 285             # by the absence of length and fixed-size
 286             if not ntype.zeroterminated:
 287                 attrs.insert(0, ('zero-terminated', '0'))
 288             elif (ntype.zeroterminated
 289                   and (ntype.size is not None or ntype.length_param_name is not None)):
 290                 attrs.insert(0, ('zero-terminated', '1'))
 291             if ntype.size is not None:
 292                 attrs.append(('fixed-size', '%d' % (ntype.size, )))
 293             if ntype.length_param_name is not None:
 294                 assert function
 295                 attrs.insert(0, ('length', '%d'
 296                             % (function.get_parameter_index(ntype.length_param_name, ))))
 297
 298             with self.tagcontext('array', attrs):
 299                 self._write_type(ntype.element_type)
 300         elif isinstance(ntype, ast.List):
 301             if ntype.name:
 302                 attrs.insert(0, ('name', ntype.name))
 303             with self.tagcontext('type', attrs):
 304                 self._write_type(ntype.element_type)
 305         elif isinstance(ntype, ast.Map):
 306             attrs.insert(0, ('name', 'GLib.HashTable'))
 307             with self.tagcontext('type', attrs):
 308                 self._write_type(ntype.key_type)
 309                 self._write_type(ntype.value_type)
 310         else:
 311             # REWRITEFIXME - enable this for 1.2
 312             if ntype.target_giname:
 313                 attrs.insert(0, ('name', self._type_to_name(ntype)))
 314             elif ntype.target_fundamental:
 315                 # attrs = [('fundamental', ntype.target_fundamental)]
 316                 attrs.insert(0, ('name', ntype.target_fundamental))
 317             elif ntype.target_foreign:
 318                 attrs.insert(0, ('foreign', '1'))
 319             self.write_tag('type', attrs)
 320
 321     def _append_registered(self, node, attrs):
 322         assert isinstance(node, ast.Registered)
 323         if node.get_type:
 324             attrs.extend([('glib:type-name', node.gtype_name),
 325                           ('glib:get-type', node.get_type)])
 326
 327     def _write_enum(self, enum):
 328         attrs = [('name', enum.name)]
 329         self._append_version(enum, attrs)
 330         self._append_node_generic(enum, attrs)
 331         self._append_registered(enum, attrs)
 332         attrs.append(('c:type', enum.ctype))
 333         if enum.error_domain:
 334             attrs.append(('glib:error-domain', enum.error_domain))
 335
 336         with self.tagcontext('enumeration', attrs):
 337             self._write_generic(enum)
 338             for member in enum.members:
 339                 self._write_member(member)
 340             for method in sorted(enum.static_methods):
 341                 self._write_static_method(method)
 342
 343     def _write_bitfield(self, bitfield):
 344         attrs = [('name', bitfield.name)]
 345         self._append_version(bitfield, attrs)
 346         self._append_node_generic(bitfield, attrs)
 347         self._append_registered(bitfield, attrs)
 348         attrs.append(('c:type', bitfield.ctype))
 349         with self.tagcontext('bitfield', attrs):
 350             self._write_generic(bitfield)
 351             for member in bitfield.members:
 352                 self._write_member(member)
 353             for method in sorted(bitfield.static_methods):
 354                 self._write_static_method(method)
 355
 356     def _write_member(self, member):
 357         attrs = [('name', member.name),
 358                  ('value', str(member.value)),
 359                  ('c:identifier', member.symbol)]
 360         if member.nick is not None:
 361             attrs.append(('glib:nick', member.nick))
 362         self.write_tag('member', attrs)
 363
 364     def _write_constant(self, constant):
 365         attrs = [('name', constant.name),
 366                  ('value', constant.value),
 367                  ('c:type', constant.ctype)]
 368         with self.tagcontext('constant', attrs):
 369             self._write_type(constant.value_type)
 370
 371     def _write_class(self, node):
 372         attrs = [('name', node.name),
 373                  ('c:symbol-prefix', node.c_symbol_prefix),
 374                  ('c:type', node.ctype)]
 375         self._append_version(node, attrs)
 376         self._append_node_generic(node, attrs)
 377         if isinstance(node, ast.Class):
 378             tag_name = 'class'
 379             if node.parent is not None:
 380                 attrs.append(('parent',
 381                               self._type_to_name(node.parent)))
 382             if node.is_abstract:
 383                 attrs.append(('abstract', '1'))
 384         else:
 385             assert isinstance(node, ast.Interface)
 386             tag_name = 'interface'
 387         attrs.append(('glib:type-name', node.gtype_name))
 388         if node.get_type is not None:
 389             attrs.append(('glib:get-type', node.get_type))
 390         if node.glib_type_struct is not None:
 391             attrs.append(('glib:type-struct',
 392                           self._type_to_name(node.glib_type_struct)))
 393         if isinstance(node, ast.Class):
 394             if node.fundamental:
 395                 attrs.append(('glib:fundamental', '1'))
 396             if node.ref_func:
 397                 attrs.append(('glib:ref-func', node.ref_func))
 398             if node.unref_func:
 399                 attrs.append(('glib:unref-func', node.unref_func))
 400             if node.set_value_func:
 401                 attrs.append(('glib:set-value-func', node.set_value_func))
 402             if node.get_value_func:
 403                 attrs.append(('glib:get-value-func', node.get_value_func))
 404         with self.tagcontext(tag_name, attrs):
 405             self._write_generic(node)
 406             if isinstance(node, ast.Class):
 407                 for iface in sorted(node.interfaces):
 408                     self.write_tag('implements',
 409                                    [('name', self._type_to_name(iface))])
 410             if isinstance(node, ast.Interface):
 411                 for iface in sorted(node.prerequisites):
 412                     self.write_tag('prerequisite',
 413                                    [('name', self._type_to_name(iface))])
 414             if isinstance(node, ast.Class):
 415                 for method in sorted(node.constructors):
 416                     self._write_constructor(method)
 417             if isinstance(node, (ast.Class, ast.Interface)):
 418                 for method in sorted(node.static_methods):
 419                     self._write_static_method(method)
 420             for vfunc in sorted(node.virtual_methods):
 421                 self._write_vfunc(vfunc)
 422             for method in sorted(node.methods):
 423                 self._write_method(method)
 424             for prop in sorted(node.properties):
 425                 self._write_property(prop)
 426             for field in node.fields:
 427                 self._write_field(field)
 428             for signal in sorted(node.signals):
 429                 self._write_signal(signal)
 430
 431     def _write_boxed(self, boxed):
 432         attrs = [('glib:name', boxed.name)]
 433         if boxed.c_symbol_prefix is not None:
 434             attrs.append(('c:symbol-prefix', boxed.c_symbol_prefix))
 435         self._append_registered(boxed, attrs)
 436         with self.tagcontext('glib:boxed', attrs):
 437             self._write_generic(boxed)
 438             for method in sorted(boxed.constructors):
 439                 self._write_constructor(method)
 440             for method in sorted(boxed.methods):
 441                 self._write_method(method)
 442             for method in sorted(boxed.static_methods):
 443                 self._write_static_method(method)
 444
 445     def _write_property(self, prop):
 446         attrs = [('name', prop.name)]
 447         self._append_version(prop, attrs)
 448         self._append_node_generic(prop, attrs)
 449         # Properties are assumed to be readable (see also generate.c)
 450         if not prop.readable:
 451             attrs.append(('readable', '0'))
 452         if prop.writable:
 453             attrs.append(('writable', '1'))
 454         if prop.construct:
 455             attrs.append(('construct', '1'))
 456         if prop.construct_only:
 457             attrs.append(('construct-only', '1'))
 458         if prop.transfer:
 459             attrs.append(('transfer-ownership', prop.transfer))
 460         with self.tagcontext('property', attrs):
 461             self._write_generic(prop)
 462             self._write_type(prop.type)
 463
 464     def _write_vfunc(self, vf):
 465         attrs = []
 466         if vf.invoker:
 467             attrs.append(('invoker', vf.invoker))
 468         self._write_callable(vf, 'virtual-method', attrs)
 469
 470     def _write_callback(self, callback):
 471         attrs = []
 472         if callback.namespace:
 473             attrs.append(('c:type', callback.ctype or callback.c_name))
 474         self._write_callable(callback, 'callback', attrs)
 475
 476     def _write_record(self, record, extra_attrs=[]):
 477         is_gtype_struct = False
 478         attrs = list(extra_attrs)
 479         if record.name is not None:
 480             attrs.append(('name', record.name))
 481         if record.ctype is not None: # the record might be anonymous
 482             attrs.append(('c:type', record.ctype))
 483         if record.disguised:
 484             attrs.append(('disguised', '1'))
 485         if record.foreign:
 486             attrs.append(('foreign', '1'))
 487         if record.is_gtype_struct_for is not None:
 488             is_gtype_struct = True
 489             attrs.append(('glib:is-gtype-struct-for',
 490                           self._type_to_name(record.is_gtype_struct_for)))
 491         self._append_version(record, attrs)
 492         self._append_node_generic(record, attrs)
 493         self._append_registered(record, attrs)
 494         if record.c_symbol_prefix:
 495             attrs.append(('c:symbol-prefix', record.c_symbol_prefix))
 496         with self.tagcontext('record', attrs):
 497             self._write_generic(record)
 498             if record.fields:
 499                 for field in record.fields:
 500                     self._write_field(field, is_gtype_struct)
 501             for method in sorted(record.constructors):
 502                 self._write_constructor(method)
 503             for method in sorted(record.methods):
 504                 self._write_method(method)
 505             for method in sorted(record.static_methods):
 506                 self._write_static_method(method)
 507
 508     def _write_union(self, union):
 509         attrs = []
 510         if union.name is not None:
 511             attrs.append(('name', union.name))
 512         if union.ctype is not None: # the union might be anonymous
 513             attrs.append(('c:type', union.ctype))
 514         self._append_version(union, attrs)
 515         self._append_node_generic(union, attrs)
 516         self._append_registered(union, attrs)
 517         if union.c_symbol_prefix:
 518             attrs.append(('c:symbol-prefix', union.c_symbol_prefix))
 519         with self.tagcontext('union', attrs):
 520             self._write_generic(union)
 521             if union.fields:
 522                 for field in union.fields:
 523                     self._write_field(field)
 524             for method in sorted(union.constructors):
 525                 self._write_constructor(method)
 526             for method in sorted(union.methods):
 527                 self._write_method(method)
 528             for method in sorted(union.static_methods):
 529                 self._write_static_method(method)
 530
 531     def _write_field(self, field, is_gtype_struct=False):
 532         if field.anonymous_node:
 533             if isinstance(field.anonymous_node, ast.Callback):
 534                 attrs = [('name', field.name)]
 535                 self._append_node_generic(field, attrs)
 536                 with self.tagcontext('field', attrs):
 537                     self._write_callback(field.anonymous_node)
 538             elif isinstance(field.anonymous_node, ast.Record):
 539                 self._write_record(field.anonymous_node)
 540             elif isinstance(field.anonymous_node, ast.Union):
 541                 self._write_union(field.anonymous_node)
 542             else:
 543                 raise AssertionError("Unknown field anonymous: %r" \
 544                                          % (field.anonymous_node, ))
 545         else:
 546             attrs = [('name', field.name)]
 547             self._append_node_generic(field, attrs)
 548             # Fields are assumed to be read-only
 549             # (see also girparser.c and generate.c)
 550             if not field.readable:
 551                 attrs.append(('readable', '0'))
 552             if field.writable:
 553                 attrs.append(('writable', '1'))
 554             if field.bits:
 555                 attrs.append(('bits', str(field.bits)))
 556             if field.private:
 557                 attrs.append(('private', '1'))
 558             with self.tagcontext('field', attrs):
 559                 self._write_generic(field)
 560                 self._write_type(field.type)
 561
 562     def _write_signal(self, signal):
 563         attrs = [('name', signal.name)]
 564         if signal.when:
 565             attrs.append(('when', signal.when))
 566         if signal.no_recurse:
 567             attrs.append(('no-recurse', '1'))
 568         if signal.detailed:
 569             attrs.append(('detailed', '1'))
 570         if signal.action:
 571             attrs.append(('action', '1'))
 572         if signal.no_hooks:
 573             attrs.append(('no-hooks', '1'))
 574
 575         self._append_version(signal, attrs)
 576         self._append_node_generic(signal, attrs)
 577         with self.tagcontext('glib:signal', attrs):
 578             self._write_generic(signal)
 579             self._write_return_type(signal.retval)
 580             self._write_parameters(signal, signal.parameters)