OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file |
| 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. |
| 4 |
| 5 import 'dart:async'; |
| 6 |
| 7 import 'package:http/http.dart' as http; |
| 8 |
| 9 import 'current_isolate_resolver.dart'; |
| 10 import 'package_config_resolver.dart'; |
| 11 import 'package_root_resolver.dart'; |
| 12 import 'sync_package_resolver.dart'; |
| 13 |
| 14 /// A class that defines how to resolve `package:` URIs. |
| 15 /// |
| 16 /// This includes the information necessary to resolve `package:` URIs using |
| 17 /// either a package config or a package root. It can be used both as a standard |
| 18 /// cross-package representation of the user's configuration, and as a means of |
| 19 /// concretely locating packages and the assets they contain. |
| 20 /// |
| 21 /// Unlike [SyncPackageResolver], this does not provide synchronous APIs. This |
| 22 /// is necessary when dealing with the current Isolate's package resolution |
| 23 /// strategy. |
| 24 /// |
| 25 /// This class should not be implemented by user code. |
| 26 abstract class PackageResolver { |
| 27 /// The map contained in the parsed package config. |
| 28 /// |
| 29 /// This maps package names to the base URIs for those packages. These are |
| 30 /// already resolved relative to [packageConfigUri], so if they're relative |
| 31 /// they should be considered relative to [Uri.base]. |
| 32 /// |
| 33 /// [urlFor] should generally be used rather than looking up package URLs in |
| 34 /// this map, to ensure that code works with a package root as well as a |
| 35 /// package config. |
| 36 /// |
| 37 /// Note that for some implementations, loading the map may require IO |
| 38 /// operations that could fail. |
| 39 /// |
| 40 /// Completes to `null` when using a [packageRoot] for resolution, or when no |
| 41 /// package resolution is being used. |
| 42 Future<Map<String, Uri>> get packageConfigMap; |
| 43 |
| 44 /// The URI for the package config. |
| 45 /// |
| 46 /// This is the URI from which [packageConfigMap] was parsed, if that's |
| 47 /// available. Otherwise, it's a `data:` URI containing a serialized |
| 48 /// representation of [packageConfigMap]. This `data:` URI should be accepted |
| 49 /// by all Dart tools. |
| 50 /// |
| 51 /// Note that if this is a `data:` URI, it may not be safe to pass as a |
| 52 /// parameter to a Dart process due to length limits. |
| 53 /// |
| 54 /// Completes to `null` when using a [packageRoot] for resolution, or when no |
| 55 /// package resolution is being used. |
| 56 Future<Uri> get packageConfigUri; |
| 57 |
| 58 /// The base URL for resolving `package:` URLs. |
| 59 /// |
| 60 /// Completes to `null` when using a [packageConfigMap] for resolution, or |
| 61 /// when no package resolution is being used. |
| 62 Future<Uri> get packageRoot; |
| 63 |
| 64 /// Fetches the package resolution for [this] and returns an object that |
| 65 /// provides synchronous access. |
| 66 /// |
| 67 /// This may throw exceptions if loading or parsing the package map fails. |
| 68 Future<SyncPackageResolver> get asSync; |
| 69 |
| 70 /// Returns the argument to pass to a subprocess to get it to use this package |
| 71 /// resolution strategy when resolving `package:` URIs. |
| 72 /// |
| 73 /// This uses the `--package-root` or `--package` flags, which are the |
| 74 /// conventions supported by the Dart VM and dart2js. |
| 75 /// |
| 76 /// Note that if [packageConfigUri] is a `data:` URI, it may be too large to |
| 77 /// pass on the command line. |
| 78 /// |
| 79 /// Returns `null` if no package resolution is in use. |
| 80 Future<String> get processArgument; |
| 81 |
| 82 /// Returns package resolution strategy describing how the current isolate |
| 83 /// resolves `package:` URIs. |
| 84 static final PackageResolver current = new CurrentIsolateResolver(); |
| 85 |
| 86 /// Returns a package resolution strategy that is unable to resolve any |
| 87 /// `package:` URIs. |
| 88 static final PackageResolver none = SyncPackageResolver.none.asAsync; |
| 89 |
| 90 /// Loads a package config file from [uri] and returns its package resolution |
| 91 /// strategy. |
| 92 /// |
| 93 /// This supports `file:`, `http:`, `data:` and `package:` URIs. It throws an |
| 94 /// [UnsupportedError] for any other schemes. If [client] is passed and an |
| 95 /// HTTP request is needed, it's used to make that request; otherwise, a |
| 96 /// default client is used. |
| 97 /// |
| 98 /// [uri] may be a [String] or a [Uri]. |
| 99 static Future<PackageResolver> loadConfig(uri, {http.Client client}) async { |
| 100 var resolver = await SyncPackageResolver.loadConfig(uri, client: client); |
| 101 return resolver.asAsync; |
| 102 } |
| 103 |
| 104 /// Returns the package resolution strategy for the given [packageConfigMap]. |
| 105 /// |
| 106 /// If passed, [uri] specifies the URI from which [packageConfigMap] was |
| 107 /// loaded. It may be a [String] or a [Uri]. |
| 108 /// |
| 109 /// Whether or not [uri] is passed, [packageConfigMap] is expected to be |
| 110 /// fully-resolved. That is, any relative URIs in the original package config |
| 111 /// source should be resolved relative to its location. |
| 112 factory PackageResolver.config(Map<String, Uri> packageConfigMap, {uri}) => |
| 113 new PackageConfigResolver(packageConfigMap, uri: uri).asAsync; |
| 114 |
| 115 /// Returns the package resolution strategy for the given [packageRoot], which |
| 116 /// may be a [String] or a [Uri]. |
| 117 factory PackageResolver.root(packageRoot) => |
| 118 new PackageRootResolver(packageRoot).asAsync; |
| 119 |
| 120 /// Resolves [packageUri] according to this package resolution strategy. |
| 121 /// |
| 122 /// [packageUri] may be a [String] or a [Uri]. This throws a [FormatException] |
| 123 /// if [packageUri] isn't a `package:` URI or doesn't have at least one path |
| 124 /// segment. |
| 125 /// |
| 126 /// If [packageUri] refers to a package that's not in the package spec, this |
| 127 /// returns `null`. |
| 128 Future<Uri> resolveUri(packageUri); |
| 129 |
| 130 /// Returns the resolved URL for [package] and [path]. |
| 131 /// |
| 132 /// This is equivalent to `resolveUri("package:$package/")` or |
| 133 /// `resolveUri("package:$package/$path")`, depending on whether [path] was |
| 134 /// passed. |
| 135 /// |
| 136 /// If [package] refers to a package that's not in the package spec, this |
| 137 /// returns `null`. |
| 138 Future<Uri> urlFor(String package, [String path]); |
| 139 |
| 140 /// Returns the `package:` URI for [uri]. |
| 141 /// |
| 142 /// If [uri] can't be referred to using a `package:` URI, returns `null`. |
| 143 /// |
| 144 /// [uri] may be a [String] or a [Uri]. |
| 145 Future<Uri> packageUriFor(uri); |
| 146 |
| 147 /// Returns the path on the local filesystem to the root of [package], or |
| 148 /// `null` if the root cannot be found. |
| 149 /// |
| 150 /// **Note**: this assumes a pub-style package layout. In particular: |
| 151 /// |
| 152 /// * If a package root is being used, this assumes that it contains symlinks |
| 153 /// to packages' lib/ directories. |
| 154 /// |
| 155 /// * If a package config is being used, this assumes that each entry points |
| 156 /// to a package's lib/ directory. |
| 157 /// |
| 158 /// Returns `null` if the package root is not a `file:` URI, or if the package |
| 159 /// config entry for [package] is not a `file:` URI. |
| 160 Future<String> packagePath(String package); |
| 161 } |
OLD | NEW |