OLD | NEW |
1 // Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2014, 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 library barback.transformer.transform; | 5 library barback.transform; |
6 | 6 |
7 import 'dart:async'; | 7 import 'dart:async'; |
8 import 'dart:convert'; | 8 import 'dart:convert'; |
9 | 9 |
10 import '../asset/asset.dart'; | 10 import 'asset.dart'; |
11 import '../asset/asset_id.dart'; | 11 import 'asset_id.dart'; |
12 import '../errors.dart'; | 12 import 'asset_set.dart'; |
13 import 'aggregate_transform.dart'; | 13 import 'base_transform.dart'; |
14 import 'transform_logger.dart'; | 14 import 'errors.dart'; |
15 | 15 import 'transform_node.dart'; |
16 /// Creates a new [Transform] wrapping an [AggregateTransform]. | 16 import 'utils.dart'; |
17 /// | |
18 /// Although barback internally works in terms of [AggregateTransformer]s, most | |
19 /// transformers only work on individual primary inputs in isolation. We want to | |
20 /// allow those transformers to implement the more user-friendly [Transformer] | |
21 /// interface which takes the more user-friendly [Transform] object. This method | |
22 /// wraps the more general [AggregateTransform] to return a [Transform] instead. | |
23 Future<Transform> newTransform(AggregateTransform aggregate) { | |
24 // A wrapped [Transformer] will assign each primary input a unique transform | |
25 // key, so we can safely get the first asset emitted. We don't want to wait | |
26 // for the stream to close, since that requires barback to prove that no more | |
27 // new assets will be generated. | |
28 return aggregate.primaryInputs.first.then((primaryInput) => | |
29 new Transform._(aggregate, primaryInput)); | |
30 } | |
31 | 17 |
32 /// While a [Transformer] represents a *kind* of transformation, this defines | 18 /// While a [Transformer] represents a *kind* of transformation, this defines |
33 /// one specific usage of it on a set of files. | 19 /// one specific usage of it on a set of files. |
34 /// | 20 /// |
35 /// This ephemeral object exists only during an actual transform application to | 21 /// This ephemeral object exists only during an actual transform application to |
36 /// facilitate communication between the [Transformer] and the code hosting | 22 /// facilitate communication between the [Transformer] and the code hosting |
37 /// the transformation. It lets the [Transformer] access inputs and generate | 23 /// the transformation. It lets the [Transformer] access inputs and generate |
38 /// outputs. | 24 /// outputs. |
39 class Transform { | 25 class Transform extends BaseTransform { |
40 /// The underlying aggregate transform. | 26 final TransformNode _node; |
41 final AggregateTransform _aggregate; | 27 |
| 28 final _outputs = new AssetSet(); |
42 | 29 |
43 /// Gets the primary input asset. | 30 /// Gets the primary input asset. |
44 /// | 31 /// |
45 /// While a transformation can use multiple input assets, one must be a | 32 /// While a transformation can use multiple input assets, one must be a |
46 /// special "primary" asset. This will be the "entrypoint" or "main" input | 33 /// special "primary" asset. This will be the "entrypoint" or "main" input |
47 /// file for a transformation. | 34 /// file for a transformation. |
48 /// | 35 /// |
49 /// For example, with a dart2js transform, the primary input would be the | 36 /// For example, with a dart2js transform, the primary input would be the |
50 /// entrypoint Dart file. All of the other Dart files that that imports | 37 /// entrypoint Dart file. All of the other Dart files that that imports |
51 /// would be secondary inputs. | 38 /// would be secondary inputs. |
52 final Asset primaryInput; | 39 /// |
| 40 /// This method may fail at runtime with an [AssetNotFoundException] if called |
| 41 /// asynchronously after the transform begins running. The primary input may |
| 42 /// become unavailable while this transformer is running due to asset changes |
| 43 /// earlier in the graph. You can ignore the error if this happens: the |
| 44 /// transformer will be re-run automatically for you. |
| 45 Asset get primaryInput { |
| 46 if (!_node.primary.state.isAvailable) { |
| 47 throw new AssetNotFoundException(_node.primary.id); |
| 48 } |
53 | 49 |
54 /// A logger so that the [Transformer] can report build details. | 50 return _node.primary.asset; |
55 TransformLogger get logger => _aggregate.logger; | 51 } |
56 | 52 |
57 Transform._(this._aggregate, this.primaryInput); | 53 Transform._(TransformNode node) |
| 54 : _node = node, |
| 55 super(node); |
58 | 56 |
59 /// Gets the asset for an input [id]. | 57 /// Gets the asset for an input [id]. |
60 /// | 58 /// |
61 /// If an input with [id] cannot be found, throws an [AssetNotFoundException]. | 59 /// If an input with [id] cannot be found, throws an [AssetNotFoundException]. |
62 Future<Asset> getInput(AssetId id) => _aggregate.getInput(id); | 60 Future<Asset> getInput(AssetId id) => _node.getInput(id); |
63 | 61 |
64 /// A convenience method to the contents of the input with [id] as a string. | 62 /// A convenience method to the contents of the input with [id] as a string. |
65 /// | 63 /// |
66 /// This is equivalent to calling [getInput] followed by [Asset.readAsString]. | 64 /// This is equivalent to calling [getInput] followed by [Asset.readAsString]. |
67 /// | 65 /// |
68 /// If the asset was created from a [String] the original string is always | 66 /// If the asset was created from a [String] the original string is always |
69 /// returned and [encoding] is ignored. Otherwise, the binary data of the | 67 /// returned and [encoding] is ignored. Otherwise, the binary data of the |
70 /// asset is decoded using [encoding], which defaults to [UTF8]. | 68 /// asset is decoded using [encoding], which defaults to [UTF8]. |
71 /// | 69 /// |
72 /// If an input with [id] cannot be found, throws an [AssetNotFoundException]. | 70 /// If an input with [id] cannot be found, throws an [AssetNotFoundException]. |
73 Future<String> readInputAsString(AssetId id, {Encoding encoding}) => | 71 Future<String> readInputAsString(AssetId id, {Encoding encoding}) { |
74 _aggregate.readInputAsString(id, encoding: encoding); | 72 if (encoding == null) encoding = UTF8; |
| 73 return getInput(id).then((input) => input.readAsString(encoding: encoding)); |
| 74 } |
75 | 75 |
76 /// A convenience method to the contents of the input with [id]. | 76 /// A convenience method to the contents of the input with [id]. |
77 /// | 77 /// |
78 /// This is equivalent to calling [getInput] followed by [Asset.read]. | 78 /// This is equivalent to calling [getInput] followed by [Asset.read]. |
79 /// | 79 /// |
80 /// If the asset was created from a [String], this returns its UTF-8 encoding. | 80 /// If the asset was created from a [String], this returns its UTF-8 encoding. |
81 /// | 81 /// |
82 /// If an input with [id] cannot be found, throws an [AssetNotFoundException]. | 82 /// If an input with [id] cannot be found, throws an [AssetNotFoundException]. |
83 Stream<List<int>> readInput(AssetId id) => _aggregate.readInput(id); | 83 Stream<List<int>> readInput(AssetId id) => |
| 84 futureStream(getInput(id).then((input) => input.read())); |
84 | 85 |
85 /// A convenience method to return whether or not an asset exists. | 86 /// A convenience method to return whether or not an asset exists. |
86 /// | 87 /// |
87 /// This is equivalent to calling [getInput] and catching an | 88 /// This is equivalent to calling [getInput] and catching an |
88 /// [AssetNotFoundException]. | 89 /// [AssetNotFoundException]. |
89 Future<bool> hasInput(AssetId id) => _aggregate.hasInput(id); | 90 Future<bool> hasInput(AssetId id) { |
| 91 return getInput(id).then((_) => true).catchError((error) { |
| 92 if (error is AssetNotFoundException && error.id == id) return false; |
| 93 throw error; |
| 94 }); |
| 95 } |
90 | 96 |
91 /// Stores [output] as the output created by this transformation. | 97 /// Stores [output] as the output created by this transformation. |
92 /// | 98 /// |
93 /// A transformation can output as many assets as it wants. | 99 /// A transformation can output as many assets as it wants. |
94 void addOutput(Asset output) => _aggregate.addOutput(output); | 100 void addOutput(Asset output) { |
| 101 // TODO(rnystrom): This should immediately throw if an output with that ID |
| 102 // has already been created by this transformer. |
| 103 _outputs.add(output); |
| 104 } |
| 105 } |
95 | 106 |
96 /// Consume the primary input so that it doesn't get processed by future | 107 /// The controller for [Transform]. |
97 /// phases or emitted once processing has finished. | 108 class TransformController extends BaseTransformController { |
98 /// | 109 Transform get transform => super.transform; |
99 /// Normally the primary input will automatically be forwarded unless the | 110 |
100 /// transformer overwrites it by emitting an input with the same id. This | 111 /// The set of assets that the transformer has emitted. |
101 /// allows the transformer to tell barback not to forward the primary input | 112 AssetSet get outputs => transform._outputs; |
102 /// even if it's not overwritten. | 113 |
103 void consumePrimary() => _aggregate.consumePrimary(primaryInput.id); | 114 TransformController(TransformNode node) |
| 115 : super(new Transform._(node)); |
104 } | 116 } |
OLD | NEW |