1# -*- Mode: Python -*- 2 3# GDBus - GLib D-Bus Library 4# 5# Copyright (C) 2008-2011 Red Hat, Inc. 6# 7# This library is free software; you can redistribute it and/or 8# modify it under the terms of the GNU Lesser General Public 9# License as published by the Free Software Foundation; either 10# version 2.1 of the License, or (at your option) any later version. 11# 12# This library 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 GNU 15# Lesser General Public License for more details. 16# 17# You should have received a copy of the GNU Lesser General 18# Public License along with this library; if not, see <http://www.gnu.org/licenses/>. 19# 20# Author: David Zeuthen <davidz@redhat.com> 21 22import sys 23import re 24from os import path 25 26from . import config 27from . import utils 28from . import dbustypes 29from . import parser 30 31# ---------------------------------------------------------------------------------------------------- 32 33class DocbookCodeGenerator: 34 def __init__(self, ifaces): 35 self.ifaces = ifaces 36 self.generate_expand_dicts() 37 38 def print_method_prototype(self, i, m, in_synopsis): 39 max_method_len = 0 40 if in_synopsis: 41 for _m in i.methods: 42 max_method_len = max(len(_m.name), max_method_len) 43 else: 44 max_method_len = max(len(m.name), max_method_len) 45 46 max_signature_len = 0 47 if in_synopsis: 48 for _m in i.methods: 49 for a in _m.in_args: 50 max_signature_len = max(len(a.signature), max_signature_len) 51 for a in _m.out_args: 52 max_signature_len = max(len(a.signature), max_signature_len) 53 else: 54 for a in m.in_args: 55 max_signature_len = max(len(a.signature), max_signature_len) 56 for a in m.out_args: 57 max_signature_len = max(len(a.signature), max_signature_len) 58 59 if in_synopsis: 60 self.out.write('<link linkend="gdbus-method-%s.%s">%s</link>%*s (' 61 %(utils.dots_to_hyphens(i.name), m.name, m.name, max_method_len - len(m.name), '')) 62 else: 63 self.out.write('%s%*s (' 64 %(m.name, max_method_len - len(m.name), '')) 65 count = 0 66 for a in m.in_args: 67 if (count > 0): 68 self.out.write(',\n%*s'%(max_method_len + 2, '')) 69 self.out.write('IN %s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name)) 70 count = count + 1 71 for a in m.out_args: 72 if (count > 0): 73 self.out.write(',\n%*s'%(max_method_len + 2, '')) 74 self.out.write('OUT %s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name)) 75 count = count + 1 76 self.out.write(');\n') 77 78 def print_signal_prototype(self, i, s, in_synopsis): 79 max_signal_len = 0 80 if in_synopsis: 81 for _s in i.signals: 82 max_signal_len = max(len(_s.name), max_signal_len) 83 else: 84 max_signal_len = max(len(s.name), max_signal_len) 85 86 max_signature_len = 0 87 if in_synopsis: 88 for _s in i.signals: 89 for a in _s.args: 90 max_signature_len = max(len(a.signature), max_signature_len) 91 else: 92 for a in s.args: 93 max_signature_len = max(len(a.signature), max_signature_len) 94 95 if in_synopsis: 96 self.out.write('<link linkend="gdbus-signal-%s.%s">%s</link>%*s (' 97 %(utils.dots_to_hyphens(i.name), s.name, s.name, max_signal_len - len(s.name), '')) 98 else: 99 self.out.write('%s%*s (' 100 %(s.name, max_signal_len - len(s.name), '')) 101 count = 0 102 for a in s.args: 103 if (count > 0): 104 self.out.write(',\n%*s'%(max_signal_len + 2, '')) 105 self.out.write('%s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name)) 106 count = count + 1 107 self.out.write(');\n') 108 109 def print_property_prototype(self, i, p, in_synopsis): 110 max_property_len = 0 111 if in_synopsis: 112 for _p in i.properties: 113 max_property_len = max(len(_p.name), max_property_len) 114 else: 115 max_property_len = max(len(p.name), max_property_len) 116 117 max_signature_len = 0 118 if in_synopsis: 119 for _p in i.properties: 120 max_signature_len = max(len(_p.signature), max_signature_len) 121 else: 122 max_signature_len = max(len(p.signature), max_signature_len) 123 124 if in_synopsis: 125 self.out.write('<link linkend="gdbus-property-%s.%s">%s</link>%*s' 126 %(utils.dots_to_hyphens(i.name), p.name, p.name, max_property_len - len(p.name), '')) 127 else: 128 self.out.write('%s%*s' 129 %(p.name, max_property_len - len(p.name), '')) 130 if p.readable and p.writable: 131 access = 'readwrite' 132 elif p.readable: 133 access = 'readable ' 134 else: 135 access = 'writable ' 136 self.out.write(' %s %s\n'%(access, p.signature)) 137 138 139 def print_synopsis_methods(self, i): 140 self.out.write(' <refsynopsisdiv role="synopsis">\n'%()) 141 self.out.write(' <title role="synopsis.title">Methods</title>\n'%()) 142 self.out.write(' <synopsis>\n'%()) 143 for m in i.methods: 144 self.print_method_prototype(i, m, in_synopsis=True) 145 self.out.write('</synopsis>\n'%()) 146 self.out.write(' </refsynopsisdiv>\n'%()) 147 148 def print_synopsis_signals(self, i): 149 self.out.write(' <refsect1 role="signal_proto">\n'%()) 150 self.out.write(' <title role="signal_proto.title">Signals</title>\n'%()) 151 self.out.write(' <synopsis>\n'%()) 152 for s in i.signals: 153 self.print_signal_prototype(i, s, in_synopsis=True) 154 self.out.write('</synopsis>\n'%()) 155 self.out.write(' </refsect1>\n'%()) 156 157 def print_synopsis_properties(self, i): 158 self.out.write(' <refsect1 role="properties">\n'%()) 159 self.out.write(' <title role="properties.title">Properties</title>\n'%()) 160 self.out.write(' <synopsis>\n'%()) 161 for p in i.properties: 162 self.print_property_prototype(i, p, in_synopsis=True) 163 self.out.write('</synopsis>\n'%()) 164 self.out.write(' </refsect1>\n'%()) 165 166 def print_method(self, i, m): 167 self.out.write('<refsect2 role="method" id="gdbus-method-%s.%s">\n'%(utils.dots_to_hyphens(i.name), m.name)) 168 self.out.write(' <title>The %s() method</title>\n'%(m.name)) 169 self.out.write(' <indexterm zone="gdbus-method-%s.%s"><primary sortas="%s.%s">%s.%s()</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), m.name, i.name_without_prefix, m.name, i.name, m.name)) 170 self.out.write('<programlisting>\n') 171 self.print_method_prototype(i, m, in_synopsis=False) 172 self.out.write('</programlisting>\n') 173 self.out.write('%s\n'%(self.expand_paras(m.doc_string, True))) 174 if m.in_args or m.out_args: 175 self.out.write('<variablelist role="params">\n') 176 for a in m.in_args: 177 self.out.write('<varlistentry>\n'%()) 178 self.out.write(' <term><literal>IN %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name)) 179 self.out.write(' <listitem>%s</listitem>\n'%(self.expand_paras(a.doc_string, True))) 180 self.out.write('</varlistentry>\n'%()) 181 for a in m.out_args: 182 self.out.write('<varlistentry>\n'%()) 183 self.out.write(' <term><literal>OUT %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name)) 184 self.out.write(' <listitem>%s</listitem>\n'%(self.expand_paras(a.doc_string, True))) 185 self.out.write('</varlistentry>\n'%()) 186 self.out.write('</variablelist>\n') 187 if len(m.since) > 0: 188 self.out.write('<para role="since">Since %s</para>\n'%(m.since)) 189 if m.deprecated: 190 self.out.write('<warning><para>The %s() method is deprecated.</para></warning>'%(m.name)) 191 self.out.write('</refsect2>\n') 192 193 def print_signal(self, i, s): 194 self.out.write('<refsect2 role="signal" id="gdbus-signal-%s.%s">\n'%(utils.dots_to_hyphens(i.name), s.name)) 195 self.out.write(' <title>The "%s" signal</title>\n'%(s.name)) 196 self.out.write(' <indexterm zone="gdbus-signal-%s.%s"><primary sortas="%s::%s">%s::%s</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), s.name, i.name_without_prefix, s.name, i.name, s.name)) 197 self.out.write('<programlisting>\n') 198 self.print_signal_prototype(i, s, in_synopsis=False) 199 self.out.write('</programlisting>\n') 200 self.out.write('%s\n'%(self.expand_paras(s.doc_string, True))) 201 if s.args: 202 self.out.write('<variablelist role="params">\n') 203 for a in s.args: 204 self.out.write('<varlistentry>\n'%()) 205 self.out.write(' <term><literal>%s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name)) 206 self.out.write(' <listitem>%s</listitem>\n'%(self.expand_paras(a.doc_string, True))) 207 self.out.write('</varlistentry>\n'%()) 208 self.out.write('</variablelist>\n') 209 if len(s.since) > 0: 210 self.out.write('<para role="since">Since %s</para>\n'%(s.since)) 211 if s.deprecated: 212 self.out.write('<warning><para>The "%s" signal is deprecated.</para></warning>'%(s.name)) 213 self.out.write('</refsect2>\n') 214 215 def print_property(self, i, p): 216 self.out.write('<refsect2 role="property" id="gdbus-property-%s.%s">\n'%(utils.dots_to_hyphens(i.name), p.name)) 217 self.out.write(' <title>The "%s" property</title>\n'%(p.name)) 218 self.out.write(' <indexterm zone="gdbus-property-%s.%s"><primary sortas="%s:%s">%s:%s</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), p.name, i.name_without_prefix, p.name, i.name, p.name)) 219 self.out.write('<programlisting>\n') 220 self.print_property_prototype(i, p, in_synopsis=False) 221 self.out.write('</programlisting>\n') 222 self.out.write('%s\n'%(self.expand_paras(p.doc_string, True))) 223 if len(p.since) > 0: 224 self.out.write('<para role="since">Since %s</para>\n'%(p.since)) 225 if p.deprecated: 226 self.out.write('<warning><para>The "%s" property is deprecated.</para></warning>'%(p.name)) 227 self.out.write('</refsect2>\n') 228 229 def expand(self, s, expandParamsAndConstants): 230 for key in self.expand_member_dict_keys: 231 s = s.replace(key, self.expand_member_dict[key]) 232 for key in self.expand_iface_dict_keys: 233 s = s.replace(key, self.expand_iface_dict[key]) 234 if expandParamsAndConstants: 235 # replace @foo with <parameter>foo</parameter> 236 s = re.sub('@[a-zA-Z0-9_]*', lambda m: '<parameter>' + m.group(0)[1:] + '</parameter>', s) 237 # replace e.g. %TRUE with <constant>TRUE</constant> 238 s = re.sub('%[a-zA-Z0-9_]*', lambda m: '<constant>' + m.group(0)[1:] + '</constant>', s) 239 return s 240 241 def expand_paras(self, s, expandParamsAndConstants): 242 s = self.expand(s, expandParamsAndConstants).strip() 243 if not s.startswith("<para"): 244 s = "<para>%s</para>" % s 245 return s 246 247 def generate_expand_dicts(self): 248 self.expand_member_dict = {} 249 self.expand_iface_dict = {} 250 for i in self.ifaces: 251 key = '#%s'%(i.name) 252 value = '<link linkend="gdbus-interface-%s.top_of_page">%s</link>'%(utils.dots_to_hyphens(i.name), i.name) 253 self.expand_iface_dict[key] = value 254 for m in i.methods: 255 key = '%s.%s()'%(i.name, m.name) 256 value = '<link linkend="gdbus-method-%s.%s">%s()</link>'%(utils.dots_to_hyphens(i.name), m.name, m.name) 257 self.expand_member_dict[key] = value 258 for s in i.signals: 259 key = '#%s::%s'%(i.name, s.name) 260 value = '<link linkend="gdbus-signal-%s.%s">"%s"</link>'%(utils.dots_to_hyphens(i.name), s.name, s.name) 261 self.expand_member_dict[key] = value 262 for p in i.properties: 263 key = '#%s:%s'%(i.name, p.name) 264 value = '<link linkend="gdbus-property-%s.%s">"%s"</link>'%(utils.dots_to_hyphens(i.name), p.name, p.name) 265 self.expand_member_dict[key] = value 266 # Make sure to expand the keys in reverse order so e.g. #org.foo.Iface:MediaCompat 267 # is evaluated before #org.foo.Iface:Media ... 268 self.expand_member_dict_keys = sorted(self.expand_member_dict.keys(), reverse=True) 269 self.expand_iface_dict_keys = sorted(self.expand_iface_dict.keys(), reverse=True) 270 271 def generate(self, docbook, outdir): 272 for i in self.ifaces: 273 self.out = open(path.join(outdir, '%s-%s.xml'%(docbook, i.name)), 'w') 274 self.out.write(''%()) 275 self.out.write('<?xml version="1.0" encoding="utf-8"?>\n'%()) 276 self.out.write('<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"\n'%()) 277 self.out.write(' "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [\n'%()) 278 self.out.write(']>\n'%()) 279 self.out.write('<refentry id="gdbus-%s">\n'%(i.name)) 280 self.out.write(' <refmeta>'%()) 281 self.out.write(' <refentrytitle role="top_of_page" id="gdbus-interface-%s.top_of_page">%s</refentrytitle>\n'%(utils.dots_to_hyphens(i.name), i.name)) 282 self.out.write(' <indexterm zone="gdbus-interface-%s.top_of_page"><primary sortas="%s">%s</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), i.name_without_prefix, i.name)) 283 self.out.write(' </refmeta>'%()) 284 285 self.out.write(' <refnamediv>'%()) 286 self.out.write(' <refname>%s</refname>'%(i.name)) 287 self.out.write(' <refpurpose>%s</refpurpose>'%(i.doc_string_brief)) 288 self.out.write(' </refnamediv>'%()) 289 290 if len(i.methods) > 0: 291 self.print_synopsis_methods(i) 292 if len(i.signals) > 0: 293 self.print_synopsis_signals(i) 294 if len(i.properties) > 0: 295 self.print_synopsis_properties(i) 296 297 self.out.write('<refsect1 role="desc" id="gdbus-interface-%s">\n'%(utils.dots_to_hyphens(i.name))) 298 self.out.write(' <title role="desc.title">Description</title>\n'%()) 299 self.out.write(' %s\n'%(self.expand_paras(i.doc_string, True))) 300 if len(i.since) > 0: 301 self.out.write(' <para role="since">Since %s</para>\n'%(i.since)) 302 if i.deprecated: 303 self.out.write('<warning><para>The %s interface is deprecated.</para></warning>'%(i.name)) 304 self.out.write('</refsect1>\n'%()) 305 306 if len(i.methods) > 0: 307 self.out.write('<refsect1 role="details" id="gdbus-methods-%s">\n'%(i.name)) 308 self.out.write(' <title role="details.title">Method Details</title>\n'%()) 309 for m in i.methods: 310 self.print_method(i, m) 311 self.out.write('</refsect1>\n'%()) 312 313 if len(i.signals) > 0: 314 self.out.write('<refsect1 role="details" id="gdbus-signals-%s">\n'%(i.name)) 315 self.out.write(' <title role="details.title">Signal Details</title>\n'%()) 316 for s in i.signals: 317 self.print_signal(i, s) 318 self.out.write('</refsect1>\n'%()) 319 320 if len(i.properties) > 0: 321 self.out.write('<refsect1 role="details" id="gdbus-properties-%s">\n'%(i.name)) 322 self.out.write(' <title role="details.title">Property Details</title>\n'%()) 323 for s in i.properties: 324 self.print_property(i, s) 325 self.out.write('</refsect1>\n'%()) 326 327 self.out.write('</refentry>\n') 328 self.out.write('\n') 329 330