Add IDL capability to json_schema_compiler.

tools/json_schema_compiler/idl_schema.py

+# Copyright (c) 2012 The Chromium Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

nit: might be worth having an overview comment here explaining what the code in
this file is for.

+import os.path
+import sys
+
+idl_generators_path = os.path.join(os.path.dirname(os.path.realpath(__file__)),
+                                  os.pardir, os.pardir, 'ppapi', 'generators')
+if idl_generators_path not in sys.path:
+  sys.path.insert(0, idl_generators_path)
+import idl_parser
+
+class Callspec(object):
+  '''
+  Given a Callspec node representing an IDL namespace, converts into a Python

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

"an IDL namespace" -> "an IDL function declaration"

"a Python dictionary" -> "a name, value pair where the value is a list of
parameters for the function"

+  dictionary that the JSON schema compiler expects to see.
+  '''
+  def __init__(self, callspec_node):
+    self.node = callspec_node
+
+  def process(self, refs):
+    parameters = []
+    for node in self.node.children:
+      parameters.append(Param(node).process(refs))
+    return self.node.GetName(), parameters
+
+class Param(object):
+  '''
+  Given a Param node representing an IDL namespace, converts into a Python

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

"an IDL namespace" -> "a function parameter"

+  dictionary that the JSON schema compiler expects to see.
+  '''
+  def __init__(self, param_node):
+    self.node = param_node
+
+  def process(self, refs):
+    properties = { 'name': self.node.GetName() }
+    return dict(properties.items() +
+                Typeref(self.node.GetProperty(
+                    'TYPEREF'), self.node).process(refs).items())
+
+class Dictionary(object):
+  '''
+  Given a Dictionary node representing an IDL namespace, converts into a Python

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

"an IDL namespace" -> "an IDL dictionary"

+  dictionary that the JSON schema compiler expects to see.
+  '''
+  def __init__(self, dictionary_node):
+    self.node = dictionary_node
+
+  def process(self, refs):
+    properties = {}
+    for node in self.node.children:
+      if node.cls == 'Member':
+        k, v = Member(node).process(refs)
+        properties[k] = v
+    return { 'id': self.node.GetName(),
+             'properties': properties,
+             'type': 'object' }
+
+class Member(object):
+  '''
+  Given a Member node representing an IDL namespace, converts into a Python

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

"an IDL namespace" -> "an IDL dictionary or interface member"

"converts into a Python dictionary..." -> "converts into a name, value pair
where the value is a dictionary the JSON schema compiler expects to see"

+  dictionary that the JSON schema compiler expects to see.
+  '''
+  def __init__(self, member_node):
+    self.node = member_node
+
+  def process(self, refs):
+    properties = {}
+    name = self.node.GetName()
+    if self.node.GetProperty('OPTIONAL'):
+      properties['optional'] = True
+    if self.node.GetProperty('nodoc'):
+      properties['nodoc'] = True
+    for node in self.node.children:
+      if node.cls == 'Callspec':
+        name, parameters = Callspec(node).process(refs)

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

It would be nice to enforce somewhere that this callspec member has the "STATIC"
attribute, since we don't support object-oriented interfaces. We could either do
that here or in a separate idl linter that is run by a presubmit check or
something.

(We may someday want to support object-oriented interfaces, in which case
non-static methods would be required to be called on an object that implements
an interface).

+        properties['parameters'] = parameters
+    properties['name'] = name
+    typeref = self.node.GetProperty('TYPEREF')
+    if typeref == 'void':

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

Instead of looking for typeref==void to tell if this is a function, we should
instead look to see if this node has a Callspec node attached. (We actually have
a few extension functions that return a non-void value synchronously, e.g.
chrome.contextMenus.create, chrome.i18n.getMessage).

Or if for some reason that isn't sufficient, we could attach an additional
property or something in the idl parser - we know from the grammar whether this
is a member variable or a member function. 

[miket_OOO, 2012/03/07 00:23:01]

Done.

+      properties['type'] = 'function'
+    else:
+      properties = dict(properties.items() +
+                        Typeref(typeref, self.node).process(refs).items())

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

would it be clearer if instead of merging dict's here, you just passed in
properties to the Typeref process method, and had it add the appropriate values
to that?

[miket_OOO, 2012/03/07 00:23:01]

Yes, great idea! Done.

+    return name, properties
+
+class Typeref(object):
+  '''
+  Given a TYPEREF property representing an IDL namespace, converts into a

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

"an IDL namespace" -> "the type of a dictionary member or function parameter"

+  Python dictionary that the JSON schema compiler expects to see.
+  '''
+  def __init__(self, typeref, parent):
+    self.typeref = typeref
+    self.parent = parent
+
+  def process(self, refs):
+    properties = {}
+    if self.typeref == 'DOMString':
+      properties['type'] = 'string'
+    elif self.typeref == 'boolean':
+      properties['type'] = 'boolean'
+    elif self.typeref == 'long':
+      properties['type'] = 'integer'
+    elif self.typeref is None:
+      properties['type'] = 'function'
+    else:
+      try:
+        properties = refs[self.typeref]
+      except KeyError, e:
+        properties['$ref'] = self.typeref

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

Someday it would be cool to take note of not-yet-defined types that we see
during compile, and compare that to the full list of defined types when we're
finished, and emit an error or warning for any that were never defined. That
could help catch cases of typos, etc. 

[miket_OOO, 2012/03/07 00:23:01]

Agreed -- though at present, it's caught loudly and fatally during C++
compilation.

[asargent_no_longer_on_chrome, 2012/03/07 00:42:09]

Good point!

+    return properties
+
+class Namespace(object):
+  '''
+  Given an IDLNode representing an IDL namespace, converts into a Python
+  dictionary that the JSON schema compiler expects to see.
+  '''
+
+  def __init__(self, namespace_node):
+    self.namespace = namespace_node
+    self.events = []
+    self.functions = []
+    self.types = []
+    self.refs = {}
+
+  def process(self):
+    for node in self.namespace.children:
+      cls = node.cls
+      if cls == "Dictionary":
+        self.types.append(Dictionary(node).process(self.refs))
+      elif cls == "Callback":
+        k, v = Member(node).process(self.refs)
+        self.refs[k] = v
+      elif cls == "Interface" and node.GetName() == "Functions":
+        self.functions = self.process_interface(node)
+      elif cls == "Interface" and node.GetName() == "Events":
+        self.events = self.process_interface(node)
+
+    return { 'events': self.events,
+             'functions': self.functions,
+             'types': self.types,
+             'namespace': self.namespace.GetName() }

[asargent_no_longer_on_chrome, 2012/03/06 22:27:57]

looks like you're missing the 'nodoc' attribute if it's present?

[miket_OOO, 2012/03/07 00:23:01]

Fixed. I know I'm being inconsistent here because I handled it elsewhere, but
what difference does nodoc make at this point (about to generate C code)?

[asargent_no_longer_on_chrome, 2012/03/07 00:42:09]

Good point. (It was actually seeing the code elsewhere to handle nodoc that made
me think about the fact that it's missing here, but I didn't stop to think about
what it's used for :) )

+
+  def process_interface(self, node):
+    members = []
+    for member in node.children:
+      if member.cls == 'Member':
+        name, properties = Member(member).process(self.refs)
+        members.append(properties)
+    return members
+
+class IDLSchema(object):
+  '''
+  Given a list of IDLNodes and IDLAttributes, converts into a Python list
+  of api_defs that the JSON schema compiler expects to see.
+  '''
+
+  def __init__(self, idl):
+    self.idl = idl
+
+  def process(self):
+    namespaces = []
+    for node in self.idl:
+      if node.cls == 'Namespace':
+        namespace = Namespace(node)
+        namespaces.append(namespace.process())
+    return namespaces
+
+def Load(filename):
+  '''
+  Given the filename of an IDL file, parses it and returns an equivalent
+  Python dictionary in a format that the JSON schema compiler expects to see.
+  '''
+
+  f = open(filename, 'r')
+  contents = f.read()
+  f.close()
+
+  idl = idl_parser.IDLParser().ParseData(contents, filename)
+  idl_schema = IDLSchema(idl)
+  return idl_schema.process()