Add access to the isolate package-root/package-map in Platform.

sdk/lib/io/platform.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * Information about the environment in which the current program is running.
  *
  * Platform provides information such as the operating system,
@@ skipping 162 matching lines @@
    * and the script name. Each fetch of executableArguments returns a new
    * List, containing the flags passed to the executable.
    */
   static List<String> get executableArguments => _Platform.executableArguments;
 
   /**
    * Returns the value of the --package-root flag passed to the executable
    * used to run the script in this isolate.  This is the directory in which
    * Dart packages are looked up.
    *
    * If there is no --package-root flag, then the empty string is returned.

[floitsch, 2015/08/24 15:09:45]

should that one also return null in case of a package-map?

[Lasse Reichstein Nielsen, 2015/08/25 06:23:00]

Not touching existing functionality. That could be a breaking change.

[Ivan Posva, 2015/08/26 04:29:36]

To be honest we should consider making this breaking change and even consider
completely removing this value as it is mostly useless, and we know that
currently it can also be entirely wrong in the current implementation. This last
fact hints to me that we have very few, if any uses of this accessor.

[Lasse Reichstein Nielsen, 2015/08/26 06:26:06]

I'm all for breaking, in which case packageRoot should be the name for the URI,
not packageRootUri.

    */
   static String get packageRoot => _Platform.packageRoot;
 
   /**
+   * Returns the package root of the current isolate, if any.
+   *
+   * If the isolate is using a [packageMap], this getter returns `null`,

[Ivan Posva, 2015/08/26 04:29:36]

This is not entirely correct: An isolate might not be using a packageMap and not
be using a packageRoot at the same time. For example when loaded from a
snapshot.

[Lasse Reichstein Nielsen, 2015/08/26 06:26:06]

Again, I'm trying to keep things simpler by saying that an isolate always use
one of the two options (with "nothing" being equivalent to an empty map).

+   * otherwise it returns the package root - a directory that package
+   * URIs are resolved against.

[nweiz, 2015/08/25 01:17:05]

It would be good to explicitly mention how this differs from [packageRoot].

[Lasse Reichstein Nielsen, 2015/08/25 06:23:00]

Acknowledged.

[Ivan Posva, 2015/08/26 04:29:36]

If we decide to remove packageRoot, then we do not need to document its
difference to the non-existing accessor.

[Lasse Reichstein Nielsen, 2015/08/26 06:26:06]

Acknowledged.

+   */
+  static Uri get packageRootUri => _Platform.packageRootUri;

[Ivan Posva, 2015/08/26 04:29:35]

All the new getters here need to return Futures. The package file resolution is
asynchronous and is only triggered on first access. In the case of launching
from a snapshot or when no packages are being loaded for the main entry point
(e.g. deferred loading) we will reach user code which can call these accessors
before their data has been resolved.
The lazy resolution of the packages location is mandatory to not negatively
impact launches which do not rely on packages to be loaded, which includes all
deployment scenarios from snapshots.

[Lasse Reichstein Nielsen, 2015/08/26 06:26:06]

Would it be possible to be blocking instead of async?

I wouldn't mind if he first access here blocked until the value was available.
The fact that the VM handles things lazily is an implementation detail that we
don't need to expose to users.

(I did notice some bug reports that looked like a lazy initialization being done
a little too late).

+
+  /**
+   * Returns the package mapping of the current isolate, if any.

[floitsch, 2015/08/24 15:09:45]

Should we mention that the package-mapping (as well as root) is the one that is
currently active. For compiled code it might differ from where the sources came
from?

(We need an "advanced" section in dartdocs).

[Lasse Reichstein Nielsen, 2015/08/25 06:23:00]

Acknowledged.

+   *
+   * If the current isolate is using [packageRoot], this getter returns `null`.

[nweiz, 2015/08/25 01:17:05]

Shouldn't this be [packageRootUri]? Presumably this will also be `null` if the
main isolate uses a package root because the implicit detection of .packages
failed, even if --package-root hasn't been passed.

[Lasse Reichstein Nielsen, 2015/08/25 06:23:00]

Good catch.
I'm not sure if a default package root for an HTTP base would not show up here.
I'll test that.

+   *
+   * The package map maps package names to a directory that package URIs for
+   * that package are resolved against, or to `null`, if the package name is

[floitsch, 2015/08/24 15:09:45]

no need to specify the `null` case. That's the normal behavior of maps.

[Lasse Reichstein Nielsen, 2015/08/25 06:23:00]

True. Should just say that it only has keys for a finite set of recognized
package names.

+   * not recognized.
+   *
+   * Returns an empty map if the isolate does not have a way to resolve package
+   * URIs.

[Ivan Posva, 2015/08/25 04:50:39]

Should return null if the isolate is not using a package map. Otherwise you
cannot distinguish between: Found a .packages file (or was passed an empty map
through the API) from package map not found/passed/

[Lasse Reichstein Nielsen, 2015/08/25 06:23:00]

I chose to do this instead because it's more useful.
This is not intended as a way to debug your package resolution detection, just 
to provide what is currently being used. 
I assumed that not having any resolution is indistinguishable from have an empty
map (no package name recognized), and it gives the user one less case to worry
about - one of the two getters always returns non-null.

[Ivan Posva, 2015/08/26 04:29:35]

Isn't that exactly what the null-aware operators would be for? If you don't care
about the fact that a neither a packageRoot or a packageMap are in use just do

var mapping = packageMap?[package_name];

[Lasse Reichstein Nielsen, 2015/08/26 06:26:06]

That would be an argument if ?[] was actually in the language. We only have a
half-baked null-aware specification where ?.foo works, but neither ?<operator>
nor ?(). I know it's harder to parse, but it's still feels like half a solution.

It's not just to make it easier to write - it's to make it easier to understand 
for the user (and therefore use correctly). If there are only two cases: use
package-root/use package-map, then it's impossible to forget he null case.

+   */
+  static Map<String, Uri> get packageMap => _Platform.packageMap;
+
+  /**
    * Returns the version of the current Dart runtime.
    *
    * The returned `String` is formatted as the
    * [semver](http://semver.org) version string of the current dart
    * runtime, possibly followed by whitespace and other version and
    * build details.
    */
   static String get version => _version;
 }