Add js_interface_generator for generating extensions interfaces

tools/json_schema_compiler/js_interface_generator.py

+# Copyright 2015 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.
+"""
+Generator that produces an interface file for the Closure Compiler.
+Note: This is a work in progress, and generated externs may require tweaking.
+"""
+
+from code import Code
+from js_util import JsUtil
+from model import *
+from schema_util import *
+
+import os
+import sys
+from datetime import datetime
+import re
+
+LICENSE = ("""// Copyright %s The Chromium Authors. All rights reserved.

[Devlin, 2015/12/04 17:44:23]

Might almost be worth defining this as a constant in the util file?

[stevenjb, 2015/12/04 18:24:07]

Done.

+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+""" % datetime.now().year)
+
+INFO = """// This file was generated by:
+//   %s.
+"""
+
+class JsInterfaceGenerator(object):
+  def Generate(self, namespace):
+    return _Generator(namespace).Generate()
+
+  def GetHeader(tool, namespace):
+    """Returns the file header text.
+    """
+    return (LICENSE + '\n' + (INFO % tool) + '\n' +
+            ('/** @fileoverview Interface for %s that can be overriden. */' %
+             namespace))
+  GetHeader = staticmethod(GetHeader)
+
+class _Generator(object):
+  def __init__(self, namespace):
+    self._namespace = namespace
+    first = namespace.name[0].upper()
+    rest = namespace.name[1:]
+    self._interface = first + rest
+    self._js_util = JsUtil()
+
+  def Generate(self):
+    """Generates a Code object with the schema for the entire namespace.
+    """
+    c = Code()
+    (c.Append(JsInterfaceGenerator.GetHeader(sys.argv[0],
+                                             self._namespace.name))
+        .Append())
+
+    c.Cblock(self._GenerateInterfaceObject())
+
+    c.Sblock('%s.prototype = {' % self._interface)
+
+    for function in self._namespace.functions.values():
+      c.Cblock(self._GenerateFunction(function))
+
+    for event in self._namespace.events.values():
+      c.Cblock(self._GenerateEvent(event))
+

[Devlin, 2015/12/04 17:44:23]

What about enums?

[stevenjb, 2015/12/04 18:24:07]

We don't need them in the interface, they are already defined in the externs
file, same for types.

[Devlin, 2015/12/04 18:28:59]

Well, the enums are exposed as JS objects on the API, so code could say
something like chrome.myApi.MyEnum.FOO.  AFAIK, the externs define them, but
externs are only used for closure compilation, not for any code actually
running.  So if your page relies on an enum value (I know some of the extension
pages do), won't it break?

+    c.TrimTrailingNewlines()
+
+    c.Eblock('};')
+
+    return c
+
+  def _GenerateInterfaceObject(self):
+    """Generates the code creating the interface object.
+       For example:
+       /** @interface */
+       function SettingsPrivate() {}
+    """
+    c = Code()
+    (c.Append('/** @interface */')
+      .Append('function %s() {}' % self._interface))
+    return c
+
+  def _GenerateFunction(self, function):
+    """Generates the inteface for a function, including a JSDoc comment.
+    """
+    c = Code()
+    if function.deprecated:
+      return c
+
+    (c.Concat(self._js_util.GenerateFunctionJsDoc(self._namespace.name,
+                                                  function))
+      .Append('%s: assertNotReached,' % (function.name)))

[Devlin, 2015/12/04 17:44:23]

Do we want asssertNotReached over just function() {}?

[stevenjb, 2015/12/04 18:24:07]

asssertNotReached is what michael used in the existing (hand created)
settings_private_interface.js:
https://code.google.com/p/chromium/codesearch#chromium/src/chrome/browser/res...

It seems like a good idea to me; a Fake should implement any function it expects
to have called, even if many of the implementations are trivial.

+
+    return c
+
+  def _GenerateEvent(self, event):
+    """Generates the interface for an event.
+    """
+    c = Code()
+    c.Sblock(line='/**', line_prefix=' * ')
+    if (event.description):
+      c.Comment(event.description, comment_prefix='')
+    c.Append('@type {!ChromeEvent}')
+    c.Append(self._js_util.GenerateSeeLink(self._namespace.name, 'event',
+                                           event.name))
+    c.Eblock(' */')
+    c.Append('%s: new ChromeEvent(),' % (event.name))
+    return c