Line data Source code
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 0 : var resolver = await SyncPackageResolver.loadConfig(uri, client: client);
101 0 : return resolver.asAsync;
102 0 : }
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 0 : 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 0 : 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 : }
|