h_generator.py revision 58537e28ecd584eab876aee8be7156509866d23a
1# Copyright (c) 2012 The Chromium Authors. All rights reserved.
2# Use of this source code is governed by a BSD-style license that can be
3# found in the LICENSE file.
4
5from code import Code
6from model import PropertyType
7import cpp_util
8import schema_util
9
10class HGenerator(object):
11  def __init__(self, type_generator, cpp_namespace):
12    self._type_generator = type_generator
13    self._cpp_namespace = cpp_namespace
14
15  def Generate(self, namespace):
16    return _Generator(namespace,
17                      self._type_generator,
18                      self._cpp_namespace).Generate()
19
20
21class _Generator(object):
22  """A .h generator for a namespace.
23  """
24  def __init__(self, namespace, cpp_type_generator, cpp_namespace):
25    self._namespace = namespace
26    self._type_helper = cpp_type_generator
27    self._cpp_namespace = cpp_namespace
28    self._target_namespace = (
29        self._type_helper.GetCppNamespaceName(self._namespace))
30    self._generate_error_messages = namespace.compiler_options.get(
31        'generate_error_messages', False)
32
33  def Generate(self):
34    """Generates a Code object with the .h for a single namespace.
35    """
36    c = Code()
37    (c.Append(cpp_util.CHROMIUM_LICENSE)
38      .Append()
39      .Append(cpp_util.GENERATED_FILE_MESSAGE % self._namespace.source_file)
40      .Append()
41    )
42
43    ifndef_name = cpp_util.GenerateIfndefName(self._namespace.source_file_dir,
44                                              self._target_namespace)
45    (c.Append('#ifndef %s' % ifndef_name)
46      .Append('#define %s' % ifndef_name)
47      .Append()
48      .Append('#include <map>')
49      .Append('#include <string>')
50      .Append('#include <vector>')
51      .Append()
52      .Append('#include "base/basictypes.h"')
53      .Append('#include "base/logging.h"')
54      .Append('#include "base/memory/linked_ptr.h"')
55      .Append('#include "base/memory/scoped_ptr.h"')
56      .Append('#include "base/values.h"')
57      .Cblock(self._type_helper.GenerateIncludes())
58      .Append()
59    )
60
61    c.Concat(cpp_util.OpenNamespace(self._cpp_namespace))
62    # TODO(calamity): These forward declarations should be #includes to allow
63    # $ref types from other files to be used as required params. This requires
64    # some detangling of windows and tabs which will currently lead to circular
65    # #includes.
66    forward_declarations = (
67        self._type_helper.GenerateForwardDeclarations())
68    if not forward_declarations.IsEmpty():
69      (c.Append()
70        .Cblock(forward_declarations)
71      )
72
73    c.Concat(self._type_helper.GetNamespaceStart())
74    c.Append()
75    if self._namespace.properties:
76      (c.Append('//')
77        .Append('// Properties')
78        .Append('//')
79        .Append()
80      )
81      for property in self._namespace.properties.values():
82        property_code = self._type_helper.GeneratePropertyValues(
83            property,
84            'extern const %(type)s %(name)s;')
85        if property_code:
86          c.Cblock(property_code)
87    if self._namespace.types:
88      (c.Append('//')
89        .Append('// Types')
90        .Append('//')
91        .Append()
92        .Cblock(self._GenerateTypes(self._FieldDependencyOrder(),
93                                    is_toplevel=True,
94                                    generate_typedefs=True))
95      )
96    if self._namespace.functions:
97      (c.Append('//')
98        .Append('// Functions')
99        .Append('//')
100        .Append()
101      )
102      for function in self._namespace.functions.values():
103        c.Cblock(self._GenerateFunction(function))
104    if self._namespace.events:
105      (c.Append('//')
106        .Append('// Events')
107        .Append('//')
108        .Append()
109      )
110      for event in self._namespace.events.values():
111        c.Cblock(self._GenerateEvent(event))
112    (c.Concat(self._type_helper.GetNamespaceEnd())
113      .Concat(cpp_util.CloseNamespace(self._cpp_namespace))
114      .Append('#endif  // %s' % ifndef_name)
115      .Append()
116    )
117    return c
118
119  def _FieldDependencyOrder(self):
120    """Generates the list of types in the current namespace in an order in which
121    depended-upon types appear before types which depend on them.
122    """
123    dependency_order = []
124
125    def ExpandType(path, type_):
126      if type_ in path:
127        raise ValueError("Illegal circular dependency via cycle " +
128                         ", ".join(map(lambda x: x.name, path + [type_])))
129      for prop in type_.properties.values():
130        if (prop.type_ == PropertyType.REF and
131            schema_util.GetNamespace(prop.ref_type) == self._namespace.name):
132          ExpandType(path + [type_], self._namespace.types[prop.ref_type])
133      if not type_ in dependency_order:
134        dependency_order.append(type_)
135
136    for type_ in self._namespace.types.values():
137      ExpandType([], type_)
138    return dependency_order
139
140  def _GenerateEnumDeclaration(self, enum_name, type_):
141    """Generate the declaration of a C++ enum.
142    """
143    c = Code()
144    c.Sblock('enum %s {' % enum_name)
145    c.Append(self._type_helper.GetEnumNoneValue(type_) + ',')
146    for value in type_.enum_values:
147      c.Append(self._type_helper.GetEnumValue(type_, value) + ',')
148    return c.Eblock('};')
149
150  def _GenerateFields(self, props):
151    """Generates the field declarations when declaring a type.
152    """
153    c = Code()
154    needs_blank_line = False
155    for prop in props:
156      if needs_blank_line:
157        c.Append()
158      needs_blank_line = True
159      if prop.description:
160        c.Comment(prop.description)
161      # ANY is a base::Value which is abstract and cannot be a direct member, so
162      # we always need to wrap it in a scoped_ptr.
163      is_ptr = prop.optional or prop.type_.property_type == PropertyType.ANY
164      (c.Append('%s %s;' % (
165           self._type_helper.GetCppType(prop.type_, is_ptr=is_ptr),
166           prop.unix_name))
167      )
168    return c
169
170  def _GenerateType(self, type_, is_toplevel=False, generate_typedefs=False):
171    """Generates a struct for |type_|.
172
173    |is_toplevel|       implies that the type was declared in the "types" field
174                        of an API schema. This determines the correct function
175                        modifier(s).
176    |generate_typedefs| controls whether primitive types should be generated as
177                        a typedef. This may not always be desired. If false,
178                        primitive types are ignored.
179    """
180    classname = cpp_util.Classname(schema_util.StripNamespace(type_.name))
181    c = Code()
182
183    if type_.functions:
184      # Wrap functions within types in the type's namespace.
185      (c.Append('namespace %s {' % classname)
186        .Append()
187      )
188      for function in type_.functions.values():
189        c.Cblock(self._GenerateFunction(function))
190      c.Append('}  // namespace %s' % classname)
191    elif type_.property_type == PropertyType.ARRAY:
192      if generate_typedefs and type_.description:
193        c.Comment(type_.description)
194      c.Cblock(self._GenerateType(type_.item_type))
195      if generate_typedefs:
196        (c.Append('typedef std::vector<%s > %s;' % (
197                       self._type_helper.GetCppType(type_.item_type),
198                       classname))
199        )
200    elif type_.property_type == PropertyType.STRING:
201      if generate_typedefs:
202        if type_.description:
203          c.Comment(type_.description)
204        c.Append('typedef std::string %(classname)s;')
205    elif type_.property_type == PropertyType.ENUM:
206      if type_.description:
207        c.Comment(type_.description)
208      c.Sblock('enum %(classname)s {')
209      c.Append('%s,' % self._type_helper.GetEnumNoneValue(type_))
210      for value in type_.enum_values:
211        c.Append('%s,' % self._type_helper.GetEnumValue(type_, value))
212      # Top level enums are in a namespace scope so the methods shouldn't be
213      # static. On the other hand, those declared inline (e.g. in an object) do.
214      maybe_static = '' if is_toplevel else 'static '
215      (c.Eblock('};')
216        .Append()
217        .Append('%sstd::string ToString(%s as_enum);' %
218                    (maybe_static, classname))
219        .Append('%s%s Parse%s(const std::string& as_string);' %
220                    (maybe_static, classname, classname))
221      )
222    elif type_.property_type in (PropertyType.CHOICES,
223                                 PropertyType.OBJECT):
224      if type_.description:
225        c.Comment(type_.description)
226      (c.Sblock('struct %(classname)s {')
227          .Append('%(classname)s();')
228          .Append('~%(classname)s();')
229      )
230      if type_.origin.from_json:
231        (c.Append()
232          .Comment('Populates a %s object from a base::Value. Returns'
233                   ' whether |out| was successfully populated.' % classname)
234          .Append('static bool Populate(%s);' % self._GenerateParams(
235              ('const base::Value& value', '%s* out' % classname)))
236        )
237        if is_toplevel:
238          (c.Append()
239            .Comment('Creates a %s object from a base::Value, or NULL on '
240                     'failure.' % classname)
241            .Append('static scoped_ptr<%s> FromValue(%s);' % (
242                classname, self._GenerateParams(('const base::Value& value',))))
243          )
244      if type_.origin.from_client:
245        value_type = ('base::Value'
246                      if type_.property_type is PropertyType.CHOICES else
247                      'base::DictionaryValue')
248        (c.Append()
249          .Comment('Returns a new %s representing the serialized form of this '
250                   '%s object.' % (value_type, classname))
251          .Append('scoped_ptr<%s> ToValue() const;' % value_type)
252        )
253      if type_.property_type == PropertyType.CHOICES:
254        # Choices are modelled with optional fields for each choice. Exactly one
255        # field of the choice is guaranteed to be set by the compiler.
256        c.Cblock(self._GenerateTypes(type_.choices))
257        c.Append('// Choices:')
258        for choice_type in type_.choices:
259          c.Append('%s as_%s;' % (
260              self._type_helper.GetCppType(choice_type, is_ptr=True),
261              choice_type.unix_name))
262      else:
263        properties = type_.properties.values()
264        (c.Append()
265          .Cblock(self._GenerateTypes(p.type_ for p in properties))
266          .Cblock(self._GenerateFields(properties)))
267        if type_.additional_properties is not None:
268          # Most additionalProperties actually have type "any", which is better
269          # modelled as a DictionaryValue rather than a map of string -> Value.
270          if type_.additional_properties.property_type == PropertyType.ANY:
271            c.Append('base::DictionaryValue additional_properties;')
272          else:
273            (c.Cblock(self._GenerateType(type_.additional_properties))
274              .Append('std::map<std::string, %s> additional_properties;' %
275                  cpp_util.PadForGenerics(
276                      self._type_helper.GetCppType(type_.additional_properties,
277                                                   is_in_container=True)))
278            )
279      (c.Eblock()
280        .Append()
281        .Sblock(' private:')
282          .Append('DISALLOW_COPY_AND_ASSIGN(%(classname)s);')
283        .Eblock('};')
284      )
285    return c.Substitute({'classname': classname})
286
287  def _GenerateEvent(self, event):
288    """Generates the namespaces for an event.
289    """
290    c = Code()
291    # TODO(kalman): use event.unix_name not Classname.
292    event_namespace = cpp_util.Classname(event.name)
293    (c.Append('namespace %s {' % event_namespace)
294      .Append()
295      .Concat(self._GenerateEventNameConstant(event))
296      .Concat(self._GenerateCreateCallbackArguments(event))
297      .Eblock('}  // namespace %s' % event_namespace)
298    )
299    return c
300
301  def _GenerateFunction(self, function):
302    """Generates the namespaces and structs for a function.
303    """
304    c = Code()
305    # TODO(kalman): Use function.unix_name not Classname here.
306    function_namespace = cpp_util.Classname(function.name)
307    # Windows has a #define for SendMessage, so to avoid any issues, we need
308    # to not use the name.
309    if function_namespace == 'SendMessage':
310      function_namespace = 'PassMessage'
311    (c.Append('namespace %s {' % function_namespace)
312      .Append()
313      .Cblock(self._GenerateFunctionParams(function))
314    )
315    if function.callback:
316      c.Cblock(self._GenerateFunctionResults(function.callback))
317    c.Append('}  // namespace %s' % function_namespace)
318    return c
319
320  def _GenerateFunctionParams(self, function):
321    """Generates the struct for passing parameters from JSON to a function.
322    """
323    if not function.params:
324      return Code()
325
326    c = Code()
327    (c.Sblock('struct Params {')
328      .Append('static scoped_ptr<Params> Create(%s);' % self._GenerateParams(
329          ('const base::ListValue& args',)))
330      .Append('~Params();')
331      .Append()
332      .Cblock(self._GenerateTypes(p.type_ for p in function.params))
333      .Cblock(self._GenerateFields(function.params))
334      .Eblock()
335      .Append()
336      .Sblock(' private:')
337        .Append('Params();')
338        .Append()
339        .Append('DISALLOW_COPY_AND_ASSIGN(Params);')
340      .Eblock('};')
341    )
342    return c
343
344  def _GenerateTypes(self, types, is_toplevel=False, generate_typedefs=False):
345    """Generate the structures required by a property such as OBJECT classes
346    and enums.
347    """
348    c = Code()
349    for type_ in types:
350      c.Cblock(self._GenerateType(type_,
351                                  is_toplevel=is_toplevel,
352                                  generate_typedefs=generate_typedefs))
353    return c
354
355  def _GenerateCreateCallbackArguments(self, function):
356    """Generates functions for passing parameters to a callback.
357    """
358    c = Code()
359    params = function.params
360    c.Cblock(self._GenerateTypes((p.type_ for p in params), is_toplevel=True))
361
362    declaration_list = []
363    for param in params:
364      if param.description:
365        c.Comment(param.description)
366      declaration_list.append(cpp_util.GetParameterDeclaration(
367          param, self._type_helper.GetCppType(param.type_)))
368    c.Append('scoped_ptr<base::ListValue> Create(%s);' %
369             ', '.join(declaration_list))
370    return c
371
372  def _GenerateEventNameConstant(self, event):
373    """Generates a constant string array for the event name.
374    """
375    c = Code()
376    c.Append('extern const char kEventName[];  // "%s.%s"' % (
377                 self._namespace.name, event.name))
378    c.Append()
379    return c
380
381  def _GenerateFunctionResults(self, callback):
382    """Generates namespace for passing a function's result back.
383    """
384    c = Code()
385    (c.Append('namespace Results {')
386      .Append()
387      .Concat(self._GenerateCreateCallbackArguments(callback))
388      .Append('}  // namespace Results')
389    )
390    return c
391
392  def _GenerateParams(self, params):
393    """Builds the parameter list for a function, given an array of parameters.
394    """
395    if self._generate_error_messages:
396      params += ('base::string16* error = NULL',)
397    return ', '.join(str(p) for p in params)
398