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 reslusion for [this] and returns an object that | |
Bob Nystrom
2016/07/21 18:00:31
"resolution".
nweiz
2016/07/21 19:42:43
Done.
| |
65 /// provides synchronuos access. | |
Bob Nystrom
2016/07/21 18:00:32
"synchronous".
nweiz
2016/07/21 19:42:43
Done.
| |
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 /// convention supported by the Dart VM and dart2js. | |
Bob Nystrom
2016/07/21 18:00:31
"conventions".
nweiz
2016/07/21 19:42:43
Done.
| |
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 it's passed and an HTTP | |
95 /// request is needed, [client] is used to make that request. | |
Bob Nystrom
2016/07/21 18:00:31
It might be good to clarify that you don't need to
nweiz
2016/07/21 19:42:43
Done.
| |
96 /// | |
97 /// [uri] may be a [String] or a [Uri]. | |
98 static Future<PackageResolver> loadConfig(uri, {http.Client client}) async { | |
99 var resolver = await SyncPackageResolver.loadConfig(uri, client: client); | |
100 return resolver.asAsync; | |
101 } | |
102 | |
103 /// Returns the package resolution strategy for the given [packageConfigMap]. | |
104 /// | |
105 /// If passed, [uri] specifies the URI from which [packageConfigMap] was | |
106 /// loaded. It may be a [String] or a [Uri]. | |
107 /// | |
108 /// Whether or not [uri] is passed, [packageConfigMap] is expected to be | |
109 /// fully-resolved. That is, any relative URIs in the original package config | |
110 /// source should be resolved relative to its location. | |
111 factory PackageResolver.config(Map<String, Uri> packageConfigMap, {uri}) => | |
112 new PackageConfigResolver(packageConfigMap, uri: uri).asAsync; | |
113 | |
114 /// Returns the package resolution strategy for the given [packageRoot], which | |
115 /// may be a [String] or a [Uri]. | |
116 factory PackageResolver.root(packageRoot) => | |
117 new PackageRootResolver(packageRoot).asAsync; | |
118 | |
119 /// Resolves [packageUri] according to this package resolution strategy. | |
120 /// | |
121 /// [packageUri] may be a [String] or a [Uri]. This throws a [FormatException] | |
122 /// if [packageUri] isn't a `package:` URI or doesn't have at least one path | |
123 /// segment. | |
124 /// | |
125 /// If [packageUri] refers to a package that's not in the package spec, this | |
126 /// returns `null`. | |
127 Future<Uri> resolveUri(packageUri); | |
128 | |
129 /// Returns the resolved URL for [package] and [path]. | |
130 /// | |
131 /// This is equivalent to `resolveUri("package:$package/")` or | |
132 /// `resolveUri("package:$package/$path")`, depending on whether [path] was | |
133 /// passed. | |
134 /// | |
135 /// If [package] refers to a package that's not in the package spec, this | |
136 /// returns `null`. | |
137 Future<Uri> urlFor(String package, [String path]); | |
138 | |
139 /// Returns the `package:` URI for [uri]. | |
140 /// | |
141 /// If [uri] can't be referred to using a `package:` URI, returns `null`. | |
142 /// | |
143 /// [uri] may be a [String] or a [Uri]. | |
144 Future<Uri> packageUriFor(uri); | |
145 | |
146 /// Returns the path on the local filesystem to the root of [package], or | |
147 /// `null` if the root cannot be found. | |
148 /// | |
149 /// **Note**: this assumes a pub-style package layout. In particular: | |
150 /// | |
151 /// * If a package root is being used, this assumes that it contains symlinks | |
152 /// to packages' lib/ directories. | |
153 /// | |
154 /// * If a package config is being used, this assumes that each entry points | |
155 /// to a package's lib/ directory. | |
156 /// | |
157 /// Returns `null` if the package root is not a `file:` URI, or if the package | |
158 /// config entry for [package] is not a `file:` URI. | |
159 Future<String> packagePath(String package); | |
160 } | |
OLD | NEW |