| OLD | NEW |
| 1 # Copyright 2015 The Chromium Authors. All rights reserved. | 1 # Copyright 2015 The Chromium Authors. All rights reserved. |
| 2 # Use of this source code is governed by a BSD-style license that can be | 2 # Use of this source code is governed by a BSD-style license that can be |
| 3 # found in the LICENSE file. | 3 # found in the LICENSE file. |
| 4 """ | 4 """ |
| 5 Generator that produces an externs file for the Closure Compiler. | 5 Generator that produces an externs file for the Closure Compiler. |
| 6 Note: This is a work in progress, and generated externs may require tweaking. | 6 Note: This is a work in progress, and generated externs may require tweaking. |
| 7 | 7 |
| 8 See https://developers.google.com/closure/compiler/docs/api-tutorial3#externs | 8 See https://developers.google.com/closure/compiler/docs/api-tutorial3#externs |
| 9 """ | 9 """ |
| 10 | 10 |
| (...skipping 12 matching lines...) Expand all Loading... |
| 23 // See https://chromium.googlesource.com/chromium/src/+/master/docs/closure_comp
ilation.md | 23 // See https://chromium.googlesource.com/chromium/src/+/master/docs/closure_comp
ilation.md |
| 24 """ | 24 """ |
| 25 | 25 |
| 26 class JsExternsGenerator(object): | 26 class JsExternsGenerator(object): |
| 27 def Generate(self, namespace): | 27 def Generate(self, namespace): |
| 28 return _Generator(namespace).Generate() | 28 return _Generator(namespace).Generate() |
| 29 | 29 |
| 30 class _Generator(object): | 30 class _Generator(object): |
| 31 def __init__(self, namespace): | 31 def __init__(self, namespace): |
| 32 self._namespace = namespace | 32 self._namespace = namespace |
| 33 self._class_name = None | |
| 34 self._js_util = JsUtil() | 33 self._js_util = JsUtil() |
| 35 | 34 |
| 36 def Generate(self): | 35 def Generate(self): |
| 37 """Generates a Code object with the schema for the entire namespace. | 36 """Generates a Code object with the schema for the entire namespace. |
| 38 """ | 37 """ |
| 39 c = Code() | 38 c = Code() |
| 40 (c.Append(self._GetHeader(sys.argv[0], self._namespace.name)) | 39 (c.Append(self._GetHeader(sys.argv[0], self._namespace.name)) |
| 41 .Append()) | 40 .Append()) |
| 42 | 41 |
| 43 self._AppendNamespaceObject(c) | 42 self._AppendNamespaceObject(c) |
| (...skipping 29 matching lines...) Expand all Loading... |
| 73 c.Append() | 72 c.Append() |
| 74 | 73 |
| 75 def _AppendEnumJsDoc(self, c, js_type): | 74 def _AppendEnumJsDoc(self, c, js_type): |
| 76 """ Given an Enum Type object, generates the Code for the enum's definition. | 75 """ Given an Enum Type object, generates the Code for the enum's definition. |
| 77 """ | 76 """ |
| 78 (c.Sblock(line='/**', line_prefix=' * ') | 77 (c.Sblock(line='/**', line_prefix=' * ') |
| 79 .Append('@enum {string}') | 78 .Append('@enum {string}') |
| 80 .Append(self._js_util.GetSeeLink(self._namespace.name, 'type', | 79 .Append(self._js_util.GetSeeLink(self._namespace.name, 'type', |
| 81 js_type.simple_name)) | 80 js_type.simple_name)) |
| 82 .Eblock(' */')) | 81 .Eblock(' */')) |
| 83 c.Append('%s.%s = {' % (self._GetNamespace(), js_type.name)) | 82 c.Append('chrome.%s.%s = {' % (self._namespace.name, js_type.name)) |
| 84 | 83 |
| 85 def get_property_name(e): | 84 def get_property_name(e): |
| 86 # Enum properties are normified to be in ALL_CAPS_STYLE. | 85 # Enum properties are normified to be in ALL_CAPS_STYLE. |
| 87 # Assume enum '1ring-rulesThemAll'. | 86 # Assume enum '1ring-rulesThemAll'. |
| 88 # Transform to '1ring-rules_Them_All'. | 87 # Transform to '1ring-rules_Them_All'. |
| 89 e = re.sub(r'([a-z])([A-Z])', r'\1_\2', e) | 88 e = re.sub(r'([a-z])([A-Z])', r'\1_\2', e) |
| 90 # Transform to '1ring_rules_Them_All'. | 89 # Transform to '1ring_rules_Them_All'. |
| 91 e = re.sub(r'\W', '_', e) | 90 e = re.sub(r'\W', '_', e) |
| 92 # Transform to '_1ring_rules_Them_All'. | 91 # Transform to '_1ring_rules_Them_All'. |
| 93 e = re.sub(r'^(\d)', r'_\1', e) | 92 e = re.sub(r'^(\d)', r'_\1', e) |
| 94 # Transform to '_1RING_RULES_THEM_ALL'. | 93 # Transform to '_1RING_RULES_THEM_ALL'. |
| 95 return e.upper() | 94 return e.upper() |
| 96 | 95 |
| 97 c.Append('\n'.join( | 96 c.Append('\n'.join( |
| 98 [" %s: '%s'," % (get_property_name(v.name), v.name) | 97 [" %s: '%s'," % (get_property_name(v.name), v.name) |
| 99 for v in js_type.enum_values])) | 98 for v in js_type.enum_values])) |
| 100 c.Append('};') | 99 c.Append('};') |
| 101 | 100 |
| 102 def _IsTypeConstructor(self, js_type): | 101 def _IsTypeConstructor(self, js_type): |
| 103 """Returns true if the given type should be a @constructor. If this returns | 102 """Returns true if the given type should be a @constructor. If this returns |
| 104 false, the type is a typedef. | 103 false, the type is a typedef. |
| 105 """ | 104 """ |
| 106 return any(prop.type_.property_type is PropertyType.FUNCTION | 105 return any(prop.type_.property_type is PropertyType.FUNCTION |
| 107 for prop in js_type.properties.values()) | 106 for prop in js_type.properties.values()) |
| 108 | 107 |
| 109 def _AppendTypeJsDoc(self, c, js_type, optional=False): | 108 def _AppendTypeJsDoc(self, c, js_type): |
| 110 """Appends the documentation for a type as a Code. | 109 """Appends the documentation for a type as a Code. |
| 111 """ | 110 """ |
| 112 c.Sblock(line='/**', line_prefix=' * ') | 111 c.Sblock(line='/**', line_prefix=' * ') |
| 113 | 112 |
| 114 if js_type.description: | 113 if js_type.description: |
| 115 for line in js_type.description.splitlines(): | 114 for line in js_type.description.splitlines(): |
| 116 c.Append(line) | 115 c.Append(line) |
| 117 | 116 |
| 118 if js_type.jsexterns: | |
| 119 for line in js_type.jsexterns.splitlines(): | |
| 120 c.Append(line) | |
| 121 | |
| 122 is_constructor = self._IsTypeConstructor(js_type) | 117 is_constructor = self._IsTypeConstructor(js_type) |
| 123 if js_type.property_type is not PropertyType.OBJECT: | 118 if is_constructor: |
| 124 self._js_util.AppendTypeJsDoc(c, self._namespace.name, js_type, optional) | 119 c.Comment('@constructor', comment_prefix = ' * ', wrap_indent=4) |
| 125 elif is_constructor: | |
| 126 c.Comment('@constructor', comment_prefix = '', wrap_indent=4) | |
| 127 c.Comment('@private', comment_prefix = '', wrap_indent=4) | |
| 128 else: | 120 else: |
| 129 self._AppendTypedef(c, js_type.properties) | 121 self._AppendTypedef(c, js_type.properties) |
| 130 | 122 |
| 131 c.Append(self._js_util.GetSeeLink(self._namespace.name, 'type', | 123 c.Append(self._js_util.GetSeeLink(self._namespace.name, 'type', |
| 132 js_type.simple_name)) | 124 js_type.simple_name)) |
| 133 c.Eblock(' */') | 125 c.Eblock(' */') |
| 134 | 126 |
| 135 var = '%s.%s' % (self._GetNamespace(), js_type.simple_name) | 127 var = 'chrome.%s.%s' % (js_type.namespace.name, js_type.simple_name) |
| 136 if is_constructor: var += ' = function() {}' | 128 if is_constructor: var += ' = function() {}' |
| 137 var += ';' | 129 var += ';' |
| 138 c.Append(var) | 130 c.Append(var) |
| 139 | 131 |
| 140 if is_constructor: | |
| 141 c.Append() | |
| 142 self._class_name = js_type.name | |
| 143 for prop in js_type.properties.values(): | |
| 144 if prop.type_.property_type is PropertyType.FUNCTION: | |
| 145 self._AppendFunction(c, prop.type_.function) | |
| 146 else: | |
| 147 self._AppendTypeJsDoc(c, prop.type_, prop.optional) | |
| 148 c.Append() | |
| 149 self._class_name = None | |
| 150 | |
| 151 def _AppendTypedef(self, c, properties): | 132 def _AppendTypedef(self, c, properties): |
| 152 """Given an OrderedDict of properties, Appends code containing a @typedef. | 133 """Given an OrderedDict of properties, Appends code containing a @typedef. |
| 153 """ | 134 """ |
| 154 if not properties: return | 135 if not properties: return |
| 155 | 136 |
| 156 c.Append('@typedef {') | 137 c.Append('@typedef {') |
| 157 self._js_util.AppendObjectDefinition(c, self._namespace.name, properties, | 138 self._js_util.AppendObjectDefinition(c, self._namespace.name, properties, |
| 158 new_line=False) | 139 new_line=False) |
| 159 c.Append('}', new_line=False) | 140 c.Append('}', new_line=False) |
| 160 | 141 |
| 161 def _AppendFunction(self, c, function): | 142 def _AppendFunction(self, c, function): |
| 162 """Appends the code representing a function, including its documentation. | 143 """Appends the code representing a function, including its documentation. |
| 163 For example: | 144 For example: |
| 164 | 145 |
| 165 /** | 146 /** |
| 166 * @param {string} title The new title. | 147 * @param {string} title The new title. |
| 167 */ | 148 */ |
| 168 chrome.window.setTitle = function(title) {}; | 149 chrome.window.setTitle = function(title) {}; |
| 169 """ | 150 """ |
| 170 self._js_util.AppendFunctionJsDoc(c, self._namespace.name, function) | 151 self._js_util.AppendFunctionJsDoc(c, self._namespace.name, function) |
| 171 params = self._GetFunctionParams(function) | 152 params = self._GetFunctionParams(function) |
| 172 c.Append('%s.%s = function(%s) {};' % (self._GetNamespace(), | 153 c.Append('chrome.%s.%s = function(%s) {};' % (self._namespace.name, |
| 173 function.name, params)) | 154 function.name, params)) |
| 174 c.Append() | 155 c.Append() |
| 175 | 156 |
| 176 def _AppendEvent(self, c, event): | 157 def _AppendEvent(self, c, event): |
| 177 """Appends the code representing an event. | 158 """Appends the code representing an event. |
| 178 For example: | 159 For example: |
| 179 | 160 |
| 180 /** @type {!ChromeEvent} */ | 161 /** @type {!ChromeEvent} */ |
| 181 chrome.bookmarks.onChildrenReordered; | 162 chrome.bookmarks.onChildrenReordered; |
| 182 """ | 163 """ |
| 183 c.Sblock(line='/**', line_prefix=' * ') | 164 c.Sblock(line='/**', line_prefix=' * ') |
| 184 if (event.description): | 165 if (event.description): |
| 185 c.Comment(event.description, comment_prefix='') | 166 c.Comment(event.description, comment_prefix='') |
| 186 c.Append('@type {!ChromeEvent}') | 167 c.Append('@type {!ChromeEvent}') |
| 187 c.Append(self._js_util.GetSeeLink(self._namespace.name, 'event', | 168 c.Append(self._js_util.GetSeeLink(self._namespace.name, 'event', |
| 188 event.name)) | 169 event.name)) |
| 189 c.Eblock(' */') | 170 c.Eblock(' */') |
| 190 c.Append('%s.%s;' % (self._GetNamespace(), event.name)) | 171 c.Append('chrome.%s.%s;' % (self._namespace.name, event.name)) |
| 191 c.Append() | 172 c.Append() |
| 192 | 173 |
| 193 def _AppendNamespaceObject(self, c): | 174 def _AppendNamespaceObject(self, c): |
| 194 """Appends the code creating namespace object. | 175 """Appends the code creating namespace object. |
| 195 For example: | 176 For example: |
| 196 | 177 |
| 197 /** | 178 /** |
| 198 * @const | 179 * @const |
| 199 */ | 180 */ |
| 200 chrome.bookmarks = {}; | 181 chrome.bookmarks = {}; |
| 201 """ | 182 """ |
| 202 c.Append("""/** | 183 c.Append("""/** |
| 203 * @const | 184 * @const |
| 204 */""") | 185 */""") |
| 205 c.Append('chrome.%s = {};' % self._namespace.name) | 186 c.Append('chrome.%s = {};' % self._namespace.name) |
| 206 c.Append() | 187 c.Append() |
| 207 | 188 |
| 208 def _GetFunctionParams(self, function): | 189 def _GetFunctionParams(self, function): |
| 209 """Returns the function params string for function. | 190 """Returns the function params string for function. |
| 210 """ | 191 """ |
| 211 params = function.params[:] | 192 params = function.params[:] |
| 212 if function.callback: | 193 if function.callback: |
| 213 params.append(function.callback) | 194 params.append(function.callback) |
| 214 return ', '.join(param.name for param in params) | 195 return ', '.join(param.name for param in params) |
| 215 | |
| 216 def _GetNamespace(self): | |
| 217 """Returns the namespace to be prepended to a top-level typedef. | |
| 218 | |
| 219 For example, it might return "chrome.namespace". | |
| 220 | |
| 221 Also optionally includes the class name if this is in the context | |
| 222 of outputting the members of a class. | |
| 223 | |
| 224 For example, "chrome.namespace.ClassName.prototype" | |
| 225 """ | |
| 226 if self._class_name: | |
| 227 return 'chrome.%s.%s.prototype' % (self._namespace.name, self._class_name) | |
| 228 return 'chrome.%s' % self._namespace.name | |
| OLD | NEW |