First version of Codecs and Converters.

sdk/lib/codec/codec.dart

+// 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 [Encoding.UTF8] produces
+ * an encoder that can convert Json objects directly to bytes, or can decode
+ * bytes directly to json objects.
+ *
+ * Fused codecs generally work in an optimized way and can be faster than

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

generally work in an optimized way ->
generally attempt to optimize the operations

[floitsch, 2013/07/12 16:09:15]

Done.

+ * 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);
+
+  Converter<S, T> get encoder;

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

Documentation!
E.g.:
This encoder converts from S to T. It may be statefull(?), so you should get a
new decoder for each [S] you want to convert.

[floitsch, 2013/07/12 16:09:15]

Done.

+  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.

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

Elaborate. Is this just a case of "output of this codec's encoder must match
input of other codec's decoder and vice versa"?

[floitsch, 2013/07/12 16:09:15]

Done.

+   *
+   * Examples:
+   *
+   *     final JSON_TO_BYTES = JSON.fuse(Encoding.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");

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

Example using [inverted]?

[floitsch, 2013/07/12 16:09:15]

Added one, but the best example would be with the line-splitter which is not yet
in the library. Added TODO.

+   */
+  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 inversed.

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

inversed -> swapped.

[floitsch, 2013/07/12 16:09:15]

Done.

+   */
+  Codec<T, S> get inverted => new _InvertedCodec<T, S>(this);
+}
+
+class _FusedCodec<S, M, T> extends Codec<S, T> {

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

Documentation for class, please.
This seems to be a general class used by all codecs, because the real fusing
happens at the Converter level.

Will there be fused codecs that know that their parts' encoder/decoder are
stateless, so it can create the fused Converter only once?

[floitsch, 2013/07/12 16:09:15]

correct.
wasn't planned, but individual classes will implement their own Fused converters
(for example to chunk the non-chunked input).

+  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(Codec<S, M> first, Codec<M, T> second)

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

_FusedCodec(this._first, this._second);

I don't usually bother with prettier names for private classes. If I can read
"_FusedCodec" without problems, I can read "_first" too.
For public classes, the names are important to the API.

[floitsch, 2013/07/12 16:09:15]

Done.

+      : this._first = first,
+        this._second = second;
+}
+
+class _InvertedCodec<S, T> extends Codec<S, T> {

[Lasse Reichstein Nielsen, 2013/07/12 11:50:47]

Consider swapping S and T here, so it reads better when compared to Codec
itself.

[floitsch, 2013/07/12 16:09:15]

Done.

+  final Codec<T, S> _codec;
+
+  _InvertedCodec(Codec<T, S> codec) : _codec = codec;
+
+  Converter<S, T> get encoder => _codec.decoder;
+  Converter<T, S> get decoder => _codec.encoder;
+
+  Codec<T, S> get inverted => _codec;
+}