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 |