OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * A script to assist in documenting the difference between the dart:html API | 6 * A script to assist in documenting the difference between the dart:html API |
7 * and the old DOM API. | 7 * and the old DOM API. |
8 */ | 8 */ |
9 #library('html_diff'); | 9 #library('html_diff'); |
10 | 10 |
11 #import('dart:coreimpl'); | 11 #import('dart:coreimpl'); |
12 #import('dart:io'); | 12 #import('dart:io'); |
13 | 13 |
14 #import('../../pkg/dartdoc/dartdoc.dart'); | 14 #import('../../pkg/dartdoc/dartdoc.dart'); |
15 #import('../../pkg/dartdoc/mirrors/mirrors.dart'); | 15 #import('../../pkg/dartdoc/mirrors/mirrors.dart'); |
16 #import('../../pkg/dartdoc/mirrors/mirrors_util.dart'); | 16 #import('../../pkg/dartdoc/mirrors/mirrors_util.dart'); |
17 | 17 |
18 final HTML_LIBRARY_NAME = 'dart:html'; | 18 final HTML_LIBRARY_NAME = 'dart:html'; |
19 final DOM_LIBRARY_NAME = 'dart:dom_deprecated'; | |
20 | 19 |
21 /** | 20 /** |
22 * A class for computing a many-to-many mapping between the types and | 21 * A class for computing a many-to-many mapping between the types and |
23 * members in `dart:dom_deprecated` and `dart:html`. This mapping is | 22 * members in `dart:html` and the MDN DOM types. This mapping is |
24 * based on two indicators: | 23 * based on two indicators: |
25 * | 24 * |
26 * 1. Auto-detected wrappers. Most `dart:html` types correspond | 25 * 1. Auto-detected wrappers. Most `dart:html` types correspond |
27 * straightforwardly to a single `dart:dom_deprecated` type, and | 26 * straightforwardly to a single `@domName` type, and |
28 * have the same name. In addition, most `dart:html` methods | 27 * have the same name. In addition, most `dart:html` methods |
29 * just call a single `dart:dom_deprecated` method. This class | 28 * just call a single `@domName` method. This class |
30 * detects these simple correspondences automatically. | 29 * detects these simple correspondences automatically. |
31 * | 30 * |
32 * 2. Manual annotations. When it's not clear which | 31 * 2. Manual annotations. When it's not clear which |
33 * `dart:dom_deprecated` items a given `dart:html` item | 32 * `@domName` items a given `dart:html` item |
34 * corresponds to, the `dart:html` item can be annotated in the | 33 * corresponds to, the `dart:html` item can be annotated in the |
35 * documentation comments using the `@domName` annotation. | 34 * documentation comments using the `@domName` annotation. |
36 * | 35 * |
37 * The `@domName` annotations for types and members are of the form | 36 * The `@domName` annotations for types and members are of the form |
38 * `@domName NAME(, NAME)*`, where the `NAME`s refer to the | 37 * `@domName NAME(, NAME)*`, where the `NAME`s refer to the |
39 * `dart:dom_deprecated` types/members that correspond to the | 38 * `@domName` types/members that correspond to the |
40 * annotated `dart:html` type/member. `NAME`s on member annotations | 39 * annotated `dart:html` type/member. `NAME`s on member annotations |
41 * can refer to either fully-qualified member names (e.g. | 40 * can refer to either fully-qualified member names (e.g. |
42 * `Document.createElement`) or unqualified member names | 41 * `Document.createElement`) or unqualified member names |
43 * (e.g. `createElement`). Unqualified member names are assumed to | 42 * (e.g. `createElement`). Unqualified member names are assumed to |
44 * refer to members of one of the corresponding `dart:dom_deprecated` | 43 * refer to members of one of the corresponding `@domName` |
45 * types. | 44 * types. |
46 */ | 45 */ |
47 class HtmlDiff { | 46 class HtmlDiff { |
48 /** A map from `dart:dom_deprecated` members to corresponding | 47 /** |
49 * `dart:html` members. */ | 48 * A map from `dart:html` members to the corresponding fully qualified |
50 final Map<MemberMirror, Set<MemberMirror>> domToHtml; | 49 * `@domName` member(s). |
| 50 */ |
| 51 final Map<String, Set<String>> htmlToDom; |
51 | 52 |
52 /** A map from `dart:html` members to corresponding | 53 /** A map from `dart:html` types to corresponding `@domName` types. */ |
53 * `dart:dom_deprecated` members. | 54 final Map<String, Set<String>> htmlTypesToDom; |
54 * TODO(johnniwinther): We use qualified names as keys, since mirrors | |
55 * (currently) are not equal between different mirror systems. | |
56 */ | |
57 final Map<String, Set<MemberMirror>> htmlToDom; | |
58 | |
59 /** A map from `dart:dom_deprecated` types to corresponding | |
60 * `dart:html` types. | |
61 * TODO(johnniwinther): We use qualified names as keys, since mirrors | |
62 * (currently) are not equal between different mirror systems. | |
63 */ | |
64 final Map<String, Set<InterfaceMirror>> domTypesToHtml; | |
65 | |
66 /** A map from `dart:html` types to corresponding | |
67 * `dart:dom_deprecated` types. | |
68 * TODO(johnniwinther): We use qualified names as keys, since mirrors | |
69 * (currently) are not equal between different mirror systems. | |
70 */ | |
71 final Map<String, Set<InterfaceMirror>> htmlTypesToDom; | |
72 | 55 |
73 final CommentMap comments; | 56 final CommentMap comments; |
74 | 57 |
75 /** If true, then print warning messages. */ | 58 /** If true, then print warning messages. */ |
76 final bool _printWarnings; | 59 final bool _printWarnings; |
77 | 60 |
78 static Compilation _compilation; | 61 static Compilation _compilation; |
79 static MirrorSystem _mirrors; | 62 static MirrorSystem _mirrors; |
80 static LibraryMirror dom; | 63 static LibraryMirror dom; |
81 | 64 |
82 /** | 65 /** |
83 * Perform static initialization of [world]. This should be run before | 66 * Perform static initialization of [world]. This should be run before |
84 * calling [HtmlDiff.run]. | 67 * calling [HtmlDiff.run]. |
85 */ | 68 */ |
86 static void initialize(Path libDir) { | 69 static void initialize(Path libDir) { |
87 _compilation = new Compilation.library( | 70 _compilation = new Compilation.library( |
88 const <Path>[ | 71 const <Path>[const Path(HTML_LIBRARY_NAME)], libDir); |
89 const Path(DOM_LIBRARY_NAME), | |
90 const Path(HTML_LIBRARY_NAME) | |
91 ], libDir); | |
92 _mirrors = _compilation.mirrors; | 72 _mirrors = _compilation.mirrors; |
93 | |
94 // Find 'dart:dom_deprecated' by its library tag 'dom'. | |
95 dom = findMirror(_mirrors.libraries, DOM_LIBRARY_NAME); | |
96 } | 73 } |
97 | 74 |
98 HtmlDiff([bool printWarnings = false]) : | 75 HtmlDiff([bool printWarnings = false]) : |
99 _printWarnings = printWarnings, | 76 _printWarnings = printWarnings, |
100 domToHtml = new Map<MemberMirror, Set<MemberMirror>>(), | 77 htmlToDom = new Map<String, Set<String>>(), |
101 htmlToDom = new Map<String, Set<MemberMirror>>(), | 78 htmlTypesToDom = new Map<String, Set<String>>(), |
102 domTypesToHtml = new Map<String, Set<InterfaceMirror>>(), | |
103 htmlTypesToDom = new Map<String, Set<InterfaceMirror>>(), | |
104 comments = new CommentMap(); | 79 comments = new CommentMap(); |
105 | 80 |
106 void warn(String s) { | 81 void warn(String s) { |
107 if (_printWarnings) { | 82 if (_printWarnings) { |
108 print('Warning: $s'); | 83 print('Warning: $s'); |
109 } | 84 } |
110 } | 85 } |
111 | 86 |
112 /** | 87 /** |
113 * Computes the `dart:dom_deprecated` to `dart:html` mapping, and | 88 * Computes the `@domName` to `dart:html` mapping, and |
114 * places it in [domToHtml], [htmlToDom], [domTypesToHtml], and | 89 * places it in [htmlToDom] and [htmlTypesToDom]. Before this is run, dart2js |
115 * [htmlTypesToDom]. Before this is run, Frog should be initialized | 90 * should be initialized (via [parseOptions] and [initializeWorld]) and |
116 * (via [parseOptions] and [initializeWorld]) and | |
117 * [HtmlDiff.initialize] should be called. | 91 * [HtmlDiff.initialize] should be called. |
118 */ | 92 */ |
119 void run() { | 93 void run() { |
120 LibraryMirror htmlLib = findMirror(_mirrors.libraries, HTML_LIBRARY_NAME); | 94 LibraryMirror htmlLib = findMirror(_mirrors.libraries, HTML_LIBRARY_NAME); |
121 if (htmlLib === null) { | 95 if (htmlLib === null) { |
122 warn('Could not find $HTML_LIBRARY_NAME'); | 96 warn('Could not find $HTML_LIBRARY_NAME'); |
123 return; | 97 return; |
124 } | 98 } |
125 for (InterfaceMirror htmlType in htmlLib.types.getValues()) { | 99 for (InterfaceMirror htmlType in htmlLib.types.getValues()) { |
126 final domTypes = htmlToDomTypes(htmlType); | 100 final domTypes = htmlToDomTypes(htmlType); |
127 if (domTypes.isEmpty()) continue; | 101 if (domTypes.isEmpty()) continue; |
128 | 102 |
129 htmlTypesToDom.putIfAbsent(htmlType.qualifiedName, | 103 htmlTypesToDom.putIfAbsent(htmlType.qualifiedName, |
130 () => new Set()).addAll(domTypes); | 104 () => new Set()).addAll(domTypes); |
131 domTypes.forEach((t) => | |
132 domTypesToHtml.putIfAbsent(t.qualifiedName, | |
133 () => new Set()).add(htmlType)); | |
134 | 105 |
135 htmlType.declaredMembers.forEach( | 106 htmlType.declaredMembers.forEach( |
136 (_, m) => _addMemberDiff(m, domTypes)); | 107 (_, m) => _addMemberDiff(m, domTypes)); |
137 } | 108 } |
138 } | 109 } |
139 | 110 |
140 /** | 111 /** |
141 * Records the `dart:dom_deprecated` to `dart:html` mapping for | 112 * Records the `@domName` to `dart:html` mapping for |
142 * [implMember] (from `dart:html`). [domTypes] are the | 113 * [htmlMember] (from `dart:html`). [domTypes] are the |
143 * `dart:dom_deprecated` [Type]s that correspond to [implMember]'s | 114 * `@domName` type values that correspond to [htmlMember]'s |
144 * defining [Type]. | 115 * defining type. |
145 */ | 116 */ |
146 void _addMemberDiff(MemberMirror htmlMember, List<TypeMirror> domTypes) { | 117 void _addMemberDiff(MemberMirror htmlMember, List<String> domTypes) { |
147 var domMembers = htmlToDomMembers(htmlMember, domTypes); | 118 var domMembers = htmlToDomMembers(htmlMember, domTypes); |
148 if (htmlMember == null && !domMembers.isEmpty()) { | 119 if (htmlMember == null && !domMembers.isEmpty()) { |
149 warn('$HTML_LIBRARY_NAME member ' | 120 warn('$HTML_LIBRARY_NAME member ' |
150 '${htmlMember.surroundingDeclaration.simpleName}.' | 121 '${htmlMember.surroundingDeclaration.simpleName}.' |
151 '${htmlMember.simpleName} has no corresponding ' | 122 '${htmlMember.simpleName} has no corresponding ' |
152 '$HTML_LIBRARY_NAME member.'); | 123 '$HTML_LIBRARY_NAME member.'); |
153 } | 124 } |
154 | 125 |
155 if (htmlMember == null) return; | 126 if (htmlMember == null) return; |
156 if (!domMembers.isEmpty()) { | 127 if (!domMembers.isEmpty()) { |
157 htmlToDom[htmlMember.qualifiedName] = domMembers; | 128 htmlToDom[htmlMember.qualifiedName] = domMembers; |
158 } | 129 } |
159 domMembers.forEach((m) => | |
160 domToHtml.putIfAbsent(m, () => new Set()).add(htmlMember)); | |
161 } | 130 } |
162 | 131 |
163 /** | 132 /** |
164 * Returns the `dart:dom_deprecated` [Type]s that correspond to | 133 * Returns the `@domName` type values that correspond to |
165 * [htmlType] from `dart:html`. This can be the empty list if no | 134 * [htmlType] from `dart:html`. This can be the empty list if no |
166 * correspondence is found. | 135 * correspondence is found. |
167 */ | 136 */ |
168 List<InterfaceMirror> htmlToDomTypes(InterfaceMirror htmlType) { | 137 List<String> htmlToDomTypes(InterfaceMirror htmlType) { |
169 if (htmlType.simpleName == null) return []; | 138 if (htmlType.simpleName == null) return []; |
170 final tags = _getTags(comments.find(htmlType.location)); | 139 final tags = _getTags(comments.find(htmlType.location)); |
171 if (tags.containsKey('domName')) { | 140 if (tags.containsKey('domName')) { |
172 var domNames = <String>[]; | 141 var domNames = <String>[]; |
173 for (var s in tags['domName'].split(',')) { | 142 for (var s in tags['domName'].split(',')) { |
174 domNames.add(s.trim()); | 143 domNames.add(s.trim()); |
175 } | 144 } |
176 if (domNames.length == 1 && domNames[0] == 'none') return []; | 145 if (domNames.length == 1 && domNames[0] == 'none') return <String>[]; |
177 var domTypes = <InterfaceMirror>[]; | 146 return domNames; |
178 for (var domName in domNames) { | |
179 final domType = findMirror(dom.types, domName); | |
180 if (domType == null) { | |
181 warn('no $DOM_LIBRARY_NAME type named $domName'); | |
182 } else { | |
183 domTypes.add(domType); | |
184 } | |
185 } | |
186 return domTypes; | |
187 } | 147 } |
188 return <InterfaceMirror>[]; | 148 return <String>[]; |
189 } | 149 } |
190 | 150 |
191 /** | 151 /** |
192 * Returns the `dart:dom_deprecated` [Member]s that correspond to | 152 * Returns the `@domName` member values that correspond to |
193 * [htmlMember] from `dart:html`. This can be the empty set if no | 153 * [htmlMember] from `dart:html`. This can be the empty set if no |
194 * correspondence is found. [domTypes] are the | 154 * correspondence is found. [domTypes] are the |
195 * `dart:dom_deprecated` [Type]s that correspond to [implMember]'s | 155 * `@domName` type values that correspond to [htmlMember]'s |
196 * defining [Type]. | 156 * defining type. |
197 */ | 157 */ |
198 Set<MemberMirror> htmlToDomMembers(MemberMirror htmlMember, | 158 Set<String> htmlToDomMembers(MemberMirror htmlMember, List<String> domTypes) { |
199 List<InterfaceMirror> domTypes) { | |
200 if (htmlMember.isPrivate) return new Set(); | 159 if (htmlMember.isPrivate) return new Set(); |
201 final tags = _getTags(comments.find(htmlMember.location)); | 160 final tags = _getTags(comments.find(htmlMember.location)); |
202 if (tags.containsKey('domName')) { | 161 if (tags.containsKey('domName')) { |
203 var domNames = <String>[]; | 162 var domNames = <String>[]; |
204 for (var s in tags['domName'].split(',')) { | 163 for (var s in tags['domName'].split(',')) { |
205 domNames.add(s.trim()); | 164 domNames.add(s.trim()); |
206 } | 165 } |
207 if (domNames.length == 1 && domNames[0] == 'none') return new Set(); | 166 if (domNames.length == 1 && domNames[0] == 'none') return new Set(); |
208 final members = new Set(); | 167 final members = new Set(); |
209 domNames.forEach((name) { | 168 domNames.forEach((name) { |
210 var nameMembers = _membersFromName(name, domTypes); | 169 var nameMembers = _membersFromName(name, domTypes); |
211 if (nameMembers.isEmpty()) { | 170 if (nameMembers.isEmpty()) { |
212 if (name.contains('.')) { | 171 if (name.contains('.')) { |
213 warn('no member $name'); | 172 warn('no member $name'); |
214 } else { | 173 } else { |
215 final options = <String>[]; | 174 final options = <String>[]; |
216 for (var t in domTypes) { | 175 for (var t in domTypes) { |
217 options.add('${t.simpleName}.${name}'); | 176 options.add('$t.$name'); |
218 } | 177 } |
219 Strings.join(options, ' or '); | 178 Strings.join(options, ' or '); |
220 warn('no member $options'); | 179 warn('no member $options'); |
221 } | 180 } |
222 } | 181 } |
223 members.addAll(nameMembers); | 182 members.addAll(nameMembers); |
224 }); | 183 }); |
225 return members; | 184 return members; |
226 } | 185 } |
227 | 186 |
228 return new Set(); | 187 return new Set(); |
229 } | 188 } |
230 | 189 |
231 /** | 190 /** |
232 * Returns the `dart:dom_deprecated` [Member]s that are indicated by | 191 * Returns the `@domName` strings that are indicated by |
233 * [name]. [name] can be either an unqualified member name | 192 * [name]. [name] can be either an unqualified member name |
234 * (e.g. `createElement`), in which case it's treated as the name of | 193 * (e.g. `createElement`), in which case it's treated as the name of |
235 * a member of one of [defaultTypes], or a fully-qualified member | 194 * a member of one of [defaultTypes], or a fully-qualified member |
236 * name (e.g. `Document.createElement`), in which case it's looked | 195 * name (e.g. `Document.createElement`), in which case it's treated as a |
237 * up in `dart:dom_deprecated` and [defaultTypes] is ignored. | 196 * member of the @domName element (`Document` in this case). |
238 */ | 197 */ |
239 Set<MemberMirror> _membersFromName(String name, | 198 Set<String> _membersFromName(String name, List<String> defaultTypes) { |
240 List<InterfaceMirror> defaultTypes) { | |
241 if (!name.contains('.', 0)) { | 199 if (!name.contains('.', 0)) { |
242 if (defaultTypes.isEmpty()) { | 200 if (defaultTypes.isEmpty()) { |
243 warn('no default type for ${name}'); | 201 warn('no default type for $name'); |
244 return new Set(); | 202 return new Set(); |
245 } | 203 } |
246 final members = new Set<MemberMirror>(); | 204 final members = new Set<String>(); |
247 defaultTypes.forEach((t) { | 205 defaultTypes.forEach((t) { members.add('$t.$name'); }); |
248 MemberMirror member = findMirror(t.declaredMembers, name); | |
249 if (member !== null) { | |
250 members.add(member); | |
251 } | |
252 }); | |
253 return members; | 206 return members; |
254 } | 207 } |
255 | 208 |
256 final splitName = name.split('.'); | 209 if (name.split('.').length != 2) { |
257 if (splitName.length != 2) { | |
258 warn('invalid member name ${name}'); | 210 warn('invalid member name ${name}'); |
259 return new Set(); | 211 return new Set(); |
260 } | 212 } |
261 | 213 return new Set.from([name]); |
262 var typeName = splitName[0]; | |
263 | |
264 InterfaceMirror type = findMirror(dom.types, typeName); | |
265 if (type == null) return new Set(); | |
266 | |
267 MemberMirror member = findMirror(type.declaredMembers, splitName[1]); | |
268 if (member == null) return new Set(); | |
269 | |
270 return new Set.from([member]); | |
271 } | 214 } |
272 | 215 |
273 /** | 216 /** |
274 * Extracts a [Map] from tag names to values from [comment], which is parsed | 217 * Extracts a [Map] from tag names to values from [comment], which is parsed |
275 * from a Dart source file via dartdoc. Tags are of the form `@NAME VALUE`, | 218 * from a Dart source file via dartdoc. Tags are of the form `@NAME VALUE`, |
276 * where `NAME` is alphabetic and `VALUE` can contain any character other than | 219 * where `NAME` is alphabetic and `VALUE` can contain any character other than |
277 * `;`. Multiple tags can be separated by semicolons. | 220 * `;`. Multiple tags can be separated by semicolons. |
278 * | 221 * |
279 * At time of writing, the only tag that's used is `@domName`. | 222 * At time of writing, the only tag that's used is `@domName`. |
280 */ | 223 */ |
281 Map<String, String> _getTags(String comment) { | 224 Map<String, String> _getTags(String comment) { |
282 if (comment == null) return const <String, String>{}; | 225 if (comment == null) return const <String, String>{}; |
283 final re = const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)"); | 226 final re = const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)"); |
284 final tags = <String, String>{}; | 227 final tags = <String, String>{}; |
285 for (var m in re.allMatches(comment.trim())) { | 228 for (var m in re.allMatches(comment.trim())) { |
286 tags[m[1]] = m[2]; | 229 tags[m[1]] = m[2]; |
287 } | 230 } |
288 return tags; | 231 return tags; |
289 } | 232 } |
290 } | 233 } |
OLD | NEW |