Index: sdk/lib/codec/codec.dart |
diff --git a/sdk/lib/codec/codec.dart b/sdk/lib/codec/codec.dart |
new file mode 100644 |
index 0000000000000000000000000000000000000000..faf736141d04a9da028c93a633548f20f405623f |
--- /dev/null |
+++ b/sdk/lib/codec/codec.dart |
@@ -0,0 +1,107 @@ |
+// Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
+// for details. All rights reserved. Use of this source code is governed by a |
+// BSD-style license that can be found in the LICENSE file. |
+ |
+library dart.codec; |
+ |
+import 'dart:convert'; |
+ |
+part 'encoding.dart'; |
+part 'json.dart'; |
+ |
+/** |
+ * A [Codec] encodes and (if supported) decodes data. |
+ * |
+ * Codecs can be fused. For example fusing [JSON] and [UTF8] produces |
+ * an encoder that can convert Json objects directly to bytes, or can decode |
+ * bytes directly to json objects. |
+ * |
+ * Fused codecs generally attempt to optimize the operations and can be faster |
+ * than executing each step of an encoding separately. |
+ * |
+ * *Codecs are still experimental and are subject to change without notice.* |
+ */ |
+abstract class Codec<S, T> { |
+ const Codec(); |
+ |
+ T encode(S input) => encoder.convert(input); |
+ S decode(T encoded) => decoder.convert(encoded); |
+ |
+ /** |
+ * Returns the encoder from [S] to [T]. |
+ * |
+ * It may be stateful and should not be reused. |
+ */ |
+ Converter<S, T> get encoder; |
+ /** |
+ * Returns the decoder of `this`, converting from [T] to [S]. |
+ * |
+ * It may be stateful an should not be reused. |
+ */ |
+ Converter<T, S> get decoder; |
+ |
+ /** |
+ * Fuses `this` with `other`. |
+ * |
+ * When encoding, the resulting codec encodes with `this` before |
+ * encoding with [other]. |
+ * |
+ * When decoding, the resulting codec decodes with [other] before decoding |
+ * with `this`. |
+ * |
+ * In some cases one needs to use the [inverted] codecs to be able to fuse |
+ * them correctly. That is, the output type of `this` ([T]) must match the |
+ * input type of the second codec [other]. |
+ * |
+ * Examples: |
+ * |
+ * final JSON_TO_BYTES = JSON.fuse(UTF8); |
+ * List<int> bytes = JSON_TO_BYTES.encode(["json-object"]); |
+ * var decoded = JSON_TO_BYTES.decode(bytes); |
+ * assert(decoded is List && decoded[0] == "json-object"); |
+ * |
+ * var inverted = JSON.inverted; |
+ * var jsonIdentity = JSON.fuse(inverted); |
+ * var jsonObject = jsonIdentity.encode(["1", 2]); |
+ * assert(jsonObject is List && jsonObject[0] == "1" && jsonObject[1] == 2); |
+ */ |
+ // TODO(floitsch): use better example with line-splitter once that one is |
+ // in this library. |
+ Codec<S, dynamic> fuse(Codec<T, dynamic> other) { |
+ return new _FusedCodec<S, T, dynamic>(this, other); |
+ } |
+ |
+ /** |
+ * Inverts `this`. |
+ * |
+ * The [encoder] and [decoder] of the resulting codec are swapped. |
+ */ |
+ Codec<T, S> get inverted => new _InvertedCodec<T, S>(this); |
+} |
+ |
+/** |
+ * Fuses the given codecs. |
+ * |
+ * In the non-chunked conversion simply invokes the non-chunked conversions in |
+ * sequence. |
+ */ |
+class _FusedCodec<S, M, T> extends Codec<S, T> { |
+ final Codec<S, M> _first; |
+ final Codec<M, T> _second; |
+ |
+ Converter<S, T> get encoder => _first.encoder.fuse(_second.encoder); |
+ Converter<T, S> get decoder => _second.decoder.fuse(_first.decoder); |
+ |
+ _FusedCodec(this._first, this._second); |
+} |
+ |
+class _InvertedCodec<T, S> extends Codec<T, S> { |
+ final Codec<S, T> _codec; |
+ |
+ _InvertedCodec(Codec<S, T> codec) : _codec = codec; |
+ |
+ Converter<T, S> get encoder => _codec.decoder; |
+ Converter<S, T> get decoder => _codec.encoder; |
+ |
+ Codec<S, T> get inverted => _codec; |
+} |