OLD | NEW |
---|---|
1 // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 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. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /// A [Resource] is data that can be read into a Dart program. | |
6 /// | |
7 /// A resource is identified by a URI. It can be loaded as bytes or data. | |
8 /// The resource URI may be a `package:` URI. | |
9 /// | |
10 /// Example: | |
11 /// | |
12 /// var resource = new Resource("package:foo/foo_data.txt"); | |
13 /// var string = await resource.readAsString(UTF8); | |
14 /// print(string); | |
15 /// | |
16 /// Example: | |
17 /// | |
18 /// var resource = new Resource("http://example.com/data.json"); | |
19 /// var obj = await resource.openRead() // Reads as stream of bytes. | |
20 /// .transform(UTF8.fuse(JSON).decoder) | |
21 /// .first; | |
22 /// | |
23 /// | |
24 /// Notice: Currently this package requires `dart:io` to do the reading, | |
25 /// so it doesn't work in the browser. | |
floitsch
2016/01/21 12:53:57
Mention the browser version.
Lasse Reichstein Nielsen
2016/01/25 10:48:37
Done.
| |
26 library resource; | |
27 | |
5 import "dart:async" show Future, Stream; | 28 import "dart:async" show Future, Stream; |
6 import "dart:convert" show Encoding; | 29 |
7 import "dart:isolate" show Isolate; | 30 import "loader.dart" show ResourceLoader; |
8 import "loader.dart"; | 31 // TODO(lrn): Merge with implementation when configured imports removes |
32 // the need to share code. | |
33 import "resource_impl.dart" as impl show Resource; | |
9 | 34 |
10 /// A resource that can be read into the program. | 35 /// A resource that can be read into the program. |
11 /// | 36 /// |
12 /// A resource is data that can be located using a URI and read into | 37 /// A resource is data that can be located using a URI and read into |
13 /// the program at runtime. | 38 /// the program at runtime. |
14 /// The URI may use the `package` scheme to read resources provided | 39 /// The URI may use the `package` scheme to read resources provided |
15 /// along with package sources. | 40 /// along with package sources. |
16 abstract class Resource { | 41 class Resource extends impl.Resource { |
17 /// Creates a resource object with the given [uri] as location. | 42 /// Creates a resource object with the given [uri] as location. |
18 /// | 43 /// |
19 /// The [uri] must be either a [Uri] or a string containing a valid URI. | 44 /// The [uri] must be either a [Uri] or a string containing a valid URI. |
20 /// If the string is not a valid URI, using any of the functions on | 45 /// If the string is not a valid URI, using any of the functions on |
21 /// the resource object will fail. | 46 /// the resource object will fail. |
22 /// | 47 /// |
23 /// The URI may be relative, in which case it will be resolved | 48 /// The URI may be relative, in which case it will be resolved |
24 /// against [Uri.base] before being used. | 49 /// against [Uri.base] before being used. |
25 /// | 50 /// |
26 /// The URI may use the `package` scheme, which is always supported. | 51 /// The URI may use the `package` scheme, which is always supported. |
27 /// Other schemes may also be supported where possible. | 52 /// Other schemes may also be supported where possible. |
28 /// | 53 /// |
29 /// If [loader] is provided, it is used to load absolute non-package URIs. | 54 /// If [loader] is provided, it is used to load absolute non-package URIs. |
30 /// Package: URIs are resolved to a non-package URI before being loaded, so | 55 /// Package: URIs are resolved to a non-package URI before being loaded, so |
31 /// the loader doesn't have to support package: URIs, nor does it need to | 56 /// the loader doesn't have to support package: URIs, nor does it need to |
32 /// support relative URI references. | 57 /// support relative URI references. |
33 /// If [loader] is omitted, a default implementation is used which supports | 58 /// If [loader] is omitted, a default implementation is used which supports |
34 /// as many of `http`, `https`, `file` and `data` as are available on the | 59 /// as many of `http`, `https`, `file` and `data` as are available on the |
35 /// current platform. | 60 /// current platform. |
36 const factory Resource(uri, {ResourceLoader loader}) = _Resource; | 61 const Resource(uri, {ResourceLoader loader}) |
62 : super(uri, (loader != null) ? loader : const DefaultLoader()); | |
37 | 63 |
38 /// The location URI of this resource. | 64 /// The location URI of this resource. |
39 /// | 65 /// |
40 /// This is a [Uri] of the `uri` parameter given to the constructor. | 66 /// This is a [Uri] of the `uri` parameter given to the constructor. |
41 /// If the parameter was a string that did not contain a valid URI, | 67 /// If the parameter was a string that did not contain a valid URI, |
42 /// reading `uri` will fail. | 68 /// reading `uri` will fail. |
43 Uri get uri; | 69 Uri get uri; |
44 | 70 |
45 /// Reads the resource content as a stream of bytes. | 71 /// Reads the resource content as a stream of bytes. |
46 Stream<List<int>> openRead(); | 72 Stream<List<int>> openRead(); |
47 | 73 |
48 /// Reads the resource content as a single list of bytes. | 74 /// Reads the resource content as a single list of bytes. |
49 Future<List<int>> readAsBytes(); | 75 Future<List<int>> readAsBytes(); |
50 | 76 |
51 /// Reads the resource content as a string. | 77 /// Reads the resource content as a string. |
52 /// | 78 /// |
53 /// The content is decoded into a string using an [Encoding]. | 79 /// The content is decoded into a string using an [Encoding]. |
54 /// If no other encoding is provided, it defaults to UTF-8. | 80 /// If no other encoding is provided, it defaults to UTF-8. |
55 Future<String> readAsString({Encoding encoding}); | 81 Future<String> readAsString({Encoding encoding}); |
56 } | 82 } |
57 | |
58 class _Resource implements Resource { | |
59 /// Loading strategy for the resource. | |
60 final ResourceLoader _loader; | |
61 | |
62 /// The URI of the resource. | |
63 final _uri; | |
64 | |
65 const _Resource(uri, {ResourceLoader loader}) | |
66 : _uri = uri, _loader = (loader != null) ? loader : const DefaultLoader(); | |
67 // TODO: Make this `loader ?? const DefaultLoader()` when ?? is const. | |
68 | |
69 Uri get uri => (_uri is String) ? Uri.parse(_uri) : (_uri as Uri); | |
70 | |
71 Stream<List<int>> openRead() async* { | |
72 Uri uri = await _resolvedUri; | |
73 yield* _loader.openRead(uri); | |
74 } | |
75 | |
76 Future<List<int>> readAsBytes() async { | |
77 Uri uri = await _resolvedUri; | |
78 return _loader.readAsBytes(uri); | |
79 } | |
80 | |
81 Future<String> readAsString({Encoding encoding}) async { | |
82 Uri uri = await _resolvedUri; | |
83 return _loader.readAsString(uri, encoding: encoding); | |
84 } | |
85 | |
86 Future<Uri> get _resolvedUri => resolveUri(uri); | |
87 } | |
OLD | NEW |