OLD | NEW |
1 // Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2014, 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 * Data structures representing an API definition, and visitor base classes | 6 * Data structures representing an API definition, and visitor base classes |
7 * for visiting those data structures. | 7 * for visiting those data structures. |
8 */ | 8 */ |
9 library api; | 9 library api; |
10 | 10 |
11 import 'dart:collection'; | 11 import 'dart:collection'; |
12 | 12 |
13 import 'package:html/dom.dart' as dom; | 13 import 'package:html/dom.dart' as dom; |
14 | 14 |
15 /** | 15 /** |
16 * Toplevel container for the API. | 16 * Toplevel container for the API. |
17 */ | 17 */ |
18 class Api extends ApiNode { | 18 class Api extends ApiNode { |
19 final String version; | 19 final String version; |
20 final List<Domain> domains; | 20 final List<Domain> domains; |
21 final Types types; | 21 final Types types; |
22 final Refactorings refactorings; | 22 final Refactorings refactorings; |
23 | 23 |
24 Api(this.version, this.domains, this.types, this.refactorings, | 24 Api(this.version, this.domains, this.types, this.refactorings, |
25 dom.Element html, | 25 dom.Element html, |
26 {bool experimental}) | 26 {bool experimental}) |
27 : super(html, experimental); | 27 : super(html, experimental, false); |
28 } | 28 } |
29 | 29 |
30 /** | 30 /** |
31 * Base class for objects in the API model. | 31 * Base class for objects in the API model. |
32 */ | 32 */ |
33 class ApiNode { | 33 class ApiNode { |
34 /** | 34 /** |
35 * A flag to indicate if this API is experimental. | 35 * A flag to indicate if this API is experimental. |
36 */ | 36 */ |
37 final bool experimental; | 37 final bool experimental; |
38 | 38 |
39 /** | 39 /** |
| 40 * A flag to indicate if this API is deprecated. |
| 41 */ |
| 42 final bool deprecated; |
| 43 |
| 44 /** |
40 * Html element representing this part of the API. | 45 * Html element representing this part of the API. |
41 */ | 46 */ |
42 final dom.Element html; | 47 final dom.Element html; |
43 | 48 |
44 ApiNode(this.html, bool experimental) | 49 ApiNode(this.html, bool experimental, bool deprecated) |
45 : this.experimental = experimental ?? false; | 50 : this.experimental = experimental ?? false, |
| 51 this.deprecated = deprecated ?? false; |
46 } | 52 } |
47 | 53 |
48 /** | 54 /** |
49 * Base class for visiting the API definition. | 55 * Base class for visiting the API definition. |
50 */ | 56 */ |
51 abstract class ApiVisitor<T> { | 57 abstract class ApiVisitor<T> { |
52 /** | 58 /** |
53 * Dispatch the given [type] to the visitor. | 59 * Dispatch the given [type] to the visitor. |
54 */ | 60 */ |
55 T visitTypeDecl(TypeDecl type) => type.accept(this) as T; | 61 T visitTypeDecl(TypeDecl type) => type.accept(this) as T; |
56 T visitTypeEnum(TypeEnum typeEnum); | 62 T visitTypeEnum(TypeEnum typeEnum); |
57 T visitTypeList(TypeList typeList); | 63 T visitTypeList(TypeList typeList); |
58 T visitTypeMap(TypeMap typeMap); | 64 T visitTypeMap(TypeMap typeMap); |
59 T visitTypeObject(TypeObject typeObject); | 65 T visitTypeObject(TypeObject typeObject); |
60 T visitTypeReference(TypeReference typeReference); | 66 T visitTypeReference(TypeReference typeReference); |
61 | 67 |
62 T visitTypeUnion(TypeUnion typeUnion); | 68 T visitTypeUnion(TypeUnion typeUnion); |
63 } | 69 } |
64 | 70 |
65 /** | 71 /** |
66 * Definition of a single domain. | 72 * Definition of a single domain. |
67 */ | 73 */ |
68 class Domain extends ApiNode { | 74 class Domain extends ApiNode { |
69 final String name; | 75 final String name; |
70 final List<Request> requests; | 76 final List<Request> requests; |
71 final List<Notification> notifications; | 77 final List<Notification> notifications; |
72 | 78 |
73 Domain(this.name, this.requests, this.notifications, dom.Element html, | 79 Domain(this.name, this.requests, this.notifications, dom.Element html, |
74 {bool experimental}) | 80 {bool experimental, bool deprecated}) |
75 : super(html, experimental); | 81 : super(html, experimental, deprecated); |
76 } | 82 } |
77 | 83 |
78 /** | 84 /** |
79 * API visitor that visits the entire API hierarchically by default. | 85 * API visitor that visits the entire API hierarchically by default. |
80 */ | 86 */ |
81 class HierarchicalApiVisitor extends ApiVisitor { | 87 class HierarchicalApiVisitor extends ApiVisitor { |
82 /** | 88 /** |
83 * The API to visit. | 89 * The API to visit. |
84 */ | 90 */ |
85 final Api api; | 91 final Api api; |
(...skipping 112 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
198 final String event; | 204 final String event; |
199 | 205 |
200 /** | 206 /** |
201 * Type of the object associated with the "params" key in the notification | 207 * Type of the object associated with the "params" key in the notification |
202 * object, or null if the notification has no parameters. | 208 * object, or null if the notification has no parameters. |
203 */ | 209 */ |
204 final TypeObject params; | 210 final TypeObject params; |
205 | 211 |
206 Notification(this.domainName, this.event, this.params, dom.Element html, | 212 Notification(this.domainName, this.event, this.params, dom.Element html, |
207 {bool experimental}) | 213 {bool experimental}) |
208 : super(html, experimental); | 214 : super(html, experimental, false); |
209 | 215 |
210 /** | 216 /** |
211 * Get the name of the notification, including the domain prefix. | 217 * Get the name of the notification, including the domain prefix. |
212 */ | 218 */ |
213 String get longEvent => '$domainName.$event'; | 219 String get longEvent => '$domainName.$event'; |
214 | 220 |
215 /** | 221 /** |
216 * Get the full type of the notification object, including the common "id" | 222 * Get the full type of the notification object, including the common "id" |
217 * and "error" fields. | 223 * and "error" fields. |
218 */ | 224 */ |
(...skipping 25 matching lines...) Expand all Loading... |
244 */ | 250 */ |
245 final TypeObject feedback; | 251 final TypeObject feedback; |
246 | 252 |
247 /** | 253 /** |
248 * Type of the refactoring options, or null if the refactoring has no options. | 254 * Type of the refactoring options, or null if the refactoring has no options. |
249 */ | 255 */ |
250 final TypeObject options; | 256 final TypeObject options; |
251 | 257 |
252 Refactoring(this.kind, this.feedback, this.options, dom.Element html, | 258 Refactoring(this.kind, this.feedback, this.options, dom.Element html, |
253 {bool experimental}) | 259 {bool experimental}) |
254 : super(html, experimental); | 260 : super(html, experimental, false); |
255 } | 261 } |
256 | 262 |
257 /** | 263 /** |
258 * A collection of refactoring definitions. | 264 * A collection of refactoring definitions. |
259 */ | 265 */ |
260 class Refactorings extends ApiNode with IterableMixin<Refactoring> { | 266 class Refactorings extends ApiNode with IterableMixin<Refactoring> { |
261 final List<Refactoring> refactorings; | 267 final List<Refactoring> refactorings; |
262 | 268 |
263 Refactorings(this.refactorings, dom.Element html, {bool experimental}) | 269 Refactorings(this.refactorings, dom.Element html, {bool experimental}) |
264 : super(html, experimental); | 270 : super(html, experimental, false); |
265 | 271 |
266 @override | 272 @override |
267 Iterator<Refactoring> get iterator => refactorings.iterator; | 273 Iterator<Refactoring> get iterator => refactorings.iterator; |
268 } | 274 } |
269 | 275 |
270 /** | 276 /** |
271 * Description of a request method. | 277 * Description of a request method. |
272 */ | 278 */ |
273 class Request extends ApiNode { | 279 class Request extends ApiNode { |
274 /** | 280 /** |
(...skipping 13 matching lines...) Expand all Loading... |
288 final TypeObject params; | 294 final TypeObject params; |
289 | 295 |
290 /** | 296 /** |
291 * Type of the object associated with the "result" key in the response object, | 297 * Type of the object associated with the "result" key in the response object, |
292 * or null if the response has no results. | 298 * or null if the response has no results. |
293 */ | 299 */ |
294 final TypeObject result; | 300 final TypeObject result; |
295 | 301 |
296 Request( | 302 Request( |
297 this.domainName, this.method, this.params, this.result, dom.Element html, | 303 this.domainName, this.method, this.params, this.result, dom.Element html, |
298 {bool experimental}) | 304 {bool experimental, bool deprecated}) |
299 : super(html, experimental); | 305 : super(html, experimental, deprecated); |
300 | 306 |
301 /** | 307 /** |
302 * Get the name of the request, including the domain prefix. | 308 * Get the name of the request, including the domain prefix. |
303 */ | 309 */ |
304 String get longMethod => '$domainName.$method'; | 310 String get longMethod => '$domainName.$method'; |
305 | 311 |
306 /** | 312 /** |
307 * Get the full type of the request object, including the common "id" and | 313 * Get the full type of the request object, including the common "id" and |
308 * "method" fields. | 314 * "method" fields. |
309 */ | 315 */ |
(...skipping 24 matching lines...) Expand all Loading... |
334 fields.add(new TypeObjectField('result', result, null)); | 340 fields.add(new TypeObjectField('result', result, null)); |
335 } | 341 } |
336 return new TypeObject(fields, null); | 342 return new TypeObject(fields, null); |
337 } | 343 } |
338 } | 344 } |
339 | 345 |
340 /** | 346 /** |
341 * Base class for all possible types. | 347 * Base class for all possible types. |
342 */ | 348 */ |
343 abstract class TypeDecl extends ApiNode { | 349 abstract class TypeDecl extends ApiNode { |
344 TypeDecl(dom.Element html, bool experimental) : super(html, experimental); | 350 TypeDecl(dom.Element html, bool experimental) |
| 351 : super(html, experimental, false); |
345 | 352 |
346 accept(ApiVisitor visitor); | 353 accept(ApiVisitor visitor); |
347 } | 354 } |
348 | 355 |
349 /** | 356 /** |
350 * Description of a named type definition. | 357 * Description of a named type definition. |
351 */ | 358 */ |
352 class TypeDefinition extends ApiNode { | 359 class TypeDefinition extends ApiNode { |
353 final String name; | 360 final String name; |
354 final TypeDecl type; | 361 final TypeDecl type; |
355 | 362 |
356 TypeDefinition(this.name, this.type, dom.Element html, {bool experimental}) | 363 TypeDefinition(this.name, this.type, dom.Element html, |
357 : super(html, experimental); | 364 {bool experimental, bool deprecated}) |
| 365 : super(html, experimental, deprecated); |
358 } | 366 } |
359 | 367 |
360 /** | 368 /** |
361 * Type of an enum. We represent enums in JSON as strings, so this type | 369 * Type of an enum. We represent enums in JSON as strings, so this type |
362 * declaration simply lists the allowed values. | 370 * declaration simply lists the allowed values. |
363 */ | 371 */ |
364 class TypeEnum extends TypeDecl { | 372 class TypeEnum extends TypeDecl { |
365 final List<TypeEnumValue> values; | 373 final List<TypeEnumValue> values; |
366 | 374 |
367 TypeEnum(this.values, dom.Element html, {bool experimental}) | 375 TypeEnum(this.values, dom.Element html, {bool experimental}) |
368 : super(html, experimental); | 376 : super(html, experimental); |
369 | 377 |
370 accept(ApiVisitor visitor) => visitor.visitTypeEnum(this); | 378 accept(ApiVisitor visitor) => visitor.visitTypeEnum(this); |
371 } | 379 } |
372 | 380 |
373 /** | 381 /** |
374 * Description of a single allowed value for an enum. | 382 * Description of a single allowed value for an enum. |
375 */ | 383 */ |
376 class TypeEnumValue extends ApiNode { | 384 class TypeEnumValue extends ApiNode { |
377 final String value; | 385 final String value; |
378 | 386 |
379 TypeEnumValue(this.value, dom.Element html, {bool experimental}) | 387 TypeEnumValue(this.value, dom.Element html, |
380 : super(html, experimental); | 388 {bool experimental, bool deprecated}) |
| 389 : super(html, experimental, deprecated); |
381 } | 390 } |
382 | 391 |
383 /** | 392 /** |
384 * Type of a JSON list. | 393 * Type of a JSON list. |
385 */ | 394 */ |
386 class TypeList extends TypeDecl { | 395 class TypeList extends TypeDecl { |
387 final TypeDecl itemType; | 396 final TypeDecl itemType; |
388 | 397 |
389 TypeList(this.itemType, dom.Element html, {bool experimental}) | 398 TypeList(this.itemType, dom.Element html, {bool experimental}) |
390 : super(html, experimental); | 399 : super(html, experimental); |
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
445 final String name; | 454 final String name; |
446 final TypeDecl type; | 455 final TypeDecl type; |
447 final bool optional; | 456 final bool optional; |
448 | 457 |
449 /** | 458 /** |
450 * Value that the field is required to contain, or null if it may vary. | 459 * Value that the field is required to contain, or null if it may vary. |
451 */ | 460 */ |
452 final Object value; | 461 final Object value; |
453 | 462 |
454 TypeObjectField(this.name, this.type, dom.Element html, | 463 TypeObjectField(this.name, this.type, dom.Element html, |
455 {this.optional: false, this.value, bool experimental}) | 464 {this.optional: false, this.value, bool experimental, bool deprecated}) |
456 : super(html, experimental); | 465 : super(html, experimental, deprecated); |
457 } | 466 } |
458 | 467 |
459 /** | 468 /** |
460 * A reference to a type which is either defined elsewhere in the API or which | 469 * A reference to a type which is either defined elsewhere in the API or which |
461 * is built-in ([String], [bool], or [int]). | 470 * is built-in ([String], [bool], or [int]). |
462 */ | 471 */ |
463 class TypeReference extends TypeDecl { | 472 class TypeReference extends TypeDecl { |
464 final String typeName; | 473 final String typeName; |
465 | 474 |
466 TypeReference(this.typeName, dom.Element html, {bool experimental}) | 475 TypeReference(this.typeName, dom.Element html, {bool experimental}) |
467 : super(html, experimental) { | 476 : super(html, experimental) { |
468 if (typeName.isEmpty) { | 477 if (typeName.isEmpty) { |
469 throw new Exception('Empty type name'); | 478 throw new Exception('Empty type name'); |
470 } | 479 } |
471 } | 480 } |
472 | 481 |
473 accept(ApiVisitor visitor) => visitor.visitTypeReference(this); | 482 accept(ApiVisitor visitor) => visitor.visitTypeReference(this); |
474 } | 483 } |
475 | 484 |
476 /** | 485 /** |
477 * A collection of type definitions. | 486 * A collection of type definitions. |
478 */ | 487 */ |
479 class Types extends ApiNode with IterableMixin<TypeDefinition> { | 488 class Types extends ApiNode with IterableMixin<TypeDefinition> { |
480 final Map<String, TypeDefinition> types; | 489 final Map<String, TypeDefinition> types; |
481 | 490 |
482 Types(this.types, dom.Element html, {bool experimental}) | 491 Types(this.types, dom.Element html, {bool experimental}) |
483 : super(html, experimental); | 492 : super(html, experimental, false); |
484 | 493 |
485 @override | 494 @override |
486 Iterator<TypeDefinition> get iterator => types.values.iterator; | 495 Iterator<TypeDefinition> get iterator => types.values.iterator; |
487 | 496 |
488 Iterable<String> get keys => types.keys; | 497 Iterable<String> get keys => types.keys; |
489 | 498 |
490 TypeDefinition operator [](String typeName) => types[typeName]; | 499 TypeDefinition operator [](String typeName) => types[typeName]; |
491 | 500 |
492 bool containsKey(String typeName) => types.containsKey(typeName); | 501 bool containsKey(String typeName) => types.containsKey(typeName); |
493 } | 502 } |
494 | 503 |
495 /** | 504 /** |
496 * Type which represents a union among multiple choices. | 505 * Type which represents a union among multiple choices. |
497 */ | 506 */ |
498 class TypeUnion extends TypeDecl { | 507 class TypeUnion extends TypeDecl { |
499 final List<TypeDecl> choices; | 508 final List<TypeDecl> choices; |
500 | 509 |
501 /** | 510 /** |
502 * The field that is used to disambiguate this union | 511 * The field that is used to disambiguate this union |
503 */ | 512 */ |
504 final String field; | 513 final String field; |
505 | 514 |
506 TypeUnion(this.choices, this.field, dom.Element html, {bool experimental}) | 515 TypeUnion(this.choices, this.field, dom.Element html, {bool experimental}) |
507 : super(html, experimental); | 516 : super(html, experimental); |
508 | 517 |
509 accept(ApiVisitor visitor) => visitor.visitTypeUnion(this); | 518 accept(ApiVisitor visitor) => visitor.visitTypeUnion(this); |
510 } | 519 } |
OLD | NEW |