Add front end code for reading the SDK's "libraries.dart" file.

pkg/front_end/lib/src/base/library_info.dart

+/// A bit flag used by [LibraryInfo] indicating that a library is used by

[Siggi Cherem (dart-lang), 2016/12/14 20:48:43]

+dartdoc for the library.

I wonder if we can avoid duplicating this by importing libraries.dart in some
way.

I assume you are extracting the contents of libraries.dart so that the 
front_end package can work on multiple versions of the sdk, but maybe we can
split libraries.dart in two:

sdk_library_metadata/lib/library_info.dart # basically what we have here
sdk_library_metadata/lib/libraries.dart # the actual list of libraries exported
in libraries.dart today.

Then you can import package:sdk_library_metadata/library_info.dart in front_end,
but parse sdk/lib/_internal/sdk_library_metadata/libraries.dart ?

[Paul Berry, 2016/12/14 23:17:25]

Hmm, let me think about that.  Assuming we keep libraries.dart around in the
long term, I can definitely see the benefit of that.  Note that we would have to
start publishing sdk_library_metadata on pub, since front end is used by
analyzer, and analyzer gets published on pub.  Alternatively, we could move
library_info to a public part of the SDK so that front_end could just import
"dart:library_info".

But I actually would like to challenge the idea that we want to keep
libraries.dart around at all.  The same information could just as easily be
stored in some other format (perhaps a JSON file).  Then it would be trivial to
parse--we wouldn't have to have all this weird hacky logic that tries to build
the values of the constants from an unresolved AST.  We could still expose the
LibraryInfo interface to people (assuming it's useful) but instead of defining
it inside the SDK, we would just define it inside the front end, and provide a
convenience method in the front end that reads the JSON, translates it into
LibraryInfo.

+/// dart2js.
+///
+/// This declaration duplicates the declaration in the SDK's "libraries.dart".
+const int DART2JS_PLATFORM = 1;
+
+/// A bit flag used by [LibraryInfo] indicating that a library is used by the
+/// VM.
+///
+/// This declaration duplicates the declaration in the SDK's "libraries.dart".
+const int VM_PLATFORM = 2;
+
+/// Parse a category string in the SDK's "libraries.dart".
+///
+/// This declaration duplicates the declaration in the SDK's "libraries.dart".
+Category parseCategory(String name) {
+  switch (name) {
+    case 'Client':
+      return Category.client;
+    case 'Server':
+      return Category.server;
+    case 'Embedded':
+      return Category.embedded;
+  }
+  return null;
+}
+
+/// The contexts that a library can be used from.
+///
+/// This declaration duplicates the declaration in the SDK's "libraries.dart".
+enum Category {
+  /// Indicates that a library can be used in a browser context.
+  client,
+
+  /// Indicates that a lbirary can be used in a command line context.
+  server,
+
+  /// Indicates that a library can be used from embedded devices.
+  embedded
+}
+
+/// Information about a "dart:" library gleaned from the SDK's "libraries.dart"
+/// file.
+///
+/// This declaration duplicates the declaration in "libraries.dart".
+class LibraryInfo {
+  /// Path to the library's *.dart file relative to the SDK's "lib" directory.
+  final String path;
+
+  /// The categories in which the library can be used, encoded as a
+  /// comma-separated String.
+  final String _categories;
+
+  /// Path to the dart2js library's *.dart file relative to the SDK's "lib"
+  /// directory, or null if dart2js uses the common library path defined above.
+  final String dart2jsPath;
+
+  /// Path to the dart2js library's patch file relative to the SDK's "lib"
+  /// directory, or null if no dart2js patch file associated with this library.
+  final String dart2jsPatchPath;
+
+  /// True if this library is documented and should be shown to the user.
+  final bool documented;
+
+  /// Bit flags indicating which platforms consume this library.  See
+  /// [DART2JS_LIBRARY] and [VM_LIBRARY].
+  final int platforms;
+
+  /// True if the library contains implementation details for another library.
+  /// The implication is that these libraries are less commonly used and that
+  /// tools like the analysis server should not show these libraries in a list
+  /// of all libraries unless the user specifically asks the tool to do so.
+  final bool implementation;
+
+  /// States the current maturity of this library.
+  final Maturity maturity;
+
+  const LibraryInfo(this.path,
+      {String categories: "",
+      this.dart2jsPath,
+      this.dart2jsPatchPath,
+      this.implementation: false,
+      this.documented: true,
+      this.maturity: Maturity.UNSPECIFIED,
+      this.platforms: DART2JS_PLATFORM | VM_PLATFORM})
+      : _categories = categories;
+
+  /// The categories in which the library can be used.
+  ///
+  /// If no categories are specified, the library is internal and cannot be
+  /// loaded by user code.
+  List<Category> get categories {
+    // `''.split(',')` returns [''], not [], so we handle that case separately.
+    if (_categories.isEmpty) return const <Category>[];
+    return _categories.split(',').map(parseCategory).toList();
+  }
+
+  /// The original "categories" String that was passed to the constructor.
+  ///
+  /// Can be used to construct a slightly modified copy of this LibraryInfo.
+  String get categoriesString {
+    return _categories;
+  }
+
+  bool get isDart2jsLibrary => (platforms & DART2JS_PLATFORM) != 0;
+
+  bool get isInternal => categories.isEmpty;
+
+  bool get isVmLibrary => (platforms & VM_PLATFORM) != 0;
+}
+
+/// Abstraction to capture the maturity of a library.
+class Maturity {
+  static const Maturity DEPRECATED = const Maturity(0, "Deprecated",
+      "This library will be remove before next major release.");
+  static const Maturity EXPERIMENTAL = const Maturity(
+      1,
+      "Experimental",
+      "This library is experimental and will likely change or be removed\n"
+      "in future versions.");
+  static const Maturity UNSTABLE = const Maturity(
+      2,
+      "Unstable",
+      "This library is in still changing and have not yet endured\n"
+      "sufficient real-world testing.\n"
+      "Backwards-compatibility is NOT guaranteed.");
+
+  static const Maturity WEB_STABLE = const Maturity(
+      3,
+      "Web Stable",
+      "This library is tracking the DOM evolution as defined by WC3.\n"
+      "Backwards-compatibility is NOT guaranteed.");
+
+  static const Maturity STABLE = const Maturity(
+      4,
+      "Stable",
+      "The library is stable. API backwards-compatibility is guaranteed.\n"
+      "However implementation details might change.");
+
+  static const Maturity LOCKED = const Maturity(5, "Locked",
+      "This library will not change except when serious bugs are encountered.");
+
+  static const Maturity UNSPECIFIED = const Maturity(-1, "Unspecified",
+      "The maturity for this library has not been specified.");
+
+  final int level;
+
+  final String name;
+
+  final String description;
+
+  const Maturity(this.level, this.name, this.description);
+
+  String toString() => "$name: $level\n$description\n";
+}