Initial version of a serialization framework

pkg/serialization/lib/src/serialization_helpers.dart

+// Copyright (c) 2012, 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.
+
+/**
+ * This contains extra functions and classes useful for implementing
+ * serialiation. Some or all of them might be removable with changes to the

[Jennifer Messerly, 2012/11/20 01:20:47]

perhaps reword second sentence?

Some or all of these will be removed once the functionality is available in the
core library.

[Alan Knight, 2012/11/20 12:17:54]

Done.

+ * core library.
+ */
+library serialization_helpers;
+
+/**
+ * A named function of one argument that just returns it. Useful for using
+ * as a default value for a function parameter or other places where you want
+ * to concisely provide a function that just returns its argument.
+ */
+doNothing(x) => x;
+
+/** Concatenate two lists. Handle the case where one or both might be null. */

[Jennifer Messerly, 2012/11/20 01:20:47]

this seems to me like it should exist in core libraries somewhere? if so, do you
mind filing a bug? with a bug+TODO it will be easier to track if we can remove
it later.

[Alan Knight, 2012/11/20 12:17:54]

Done. Bug existed already, but added the TODO referencing it.

+append(List a, List b) {

[Jennifer Messerly, 2012/11/20 01:20:47]

return type List

+  if (a == null) {
+    if (b == null) return []; else return new List.from(b);

[Jennifer Messerly, 2012/11/20 01:20:47]

should use curlies here:
http://www.dartlang.org/articles/style-guide/#do-use-curly-braces-for-all-flo...

[Alan Knight, 2012/11/20 12:17:54]

Rewrote it using ? :

+  }
+  if (b == null) return new List.from(a);
+  var result = new List.from(a);
+  result.addAll(b);
+  return result;
+}
+
+/**
+ * Return a sorted version of [aCollection], using the default sort criterion.
+ * Always returns a List, regardless of the type of [aCollection].
+ */
+List sorted(aCollection) {
+  var result = new List.from(aCollection);
+  result.sort();
+  return result;
+}
+
+/**
+ * Be able to iterate polymorphically between List-like and Map-like things.
+ * For example, keysAndValues(["a", "b", "c"]).forEach((key, value) => ...);
+ * will loop over the key/value pairs 1/"a", 2/"b", 3/"c", as if the argument
+ * was a Map from integer keys to string values.
+ * Only supports forEach() and map() operations because that was all the code
+ * needed for the moment.
+ */
+MapLikeIterable keysAndValues(x) => new MapLikeIterable(x);
+
+/**
+ * A class for iterating over things as if they were Maps, which primarily
+ * means that forEach() and map() pass two arguments, and map() returns a new
+ * Map with the same keys as [collection] and values which have been transformed
+ * by the argument to map().
+ */
+class MapLikeIterable {

[Jennifer Messerly, 2012/11/20 01:20:47]

should this iterate a key-value pairs? then it could implement Collection for
real.

in C#, Dictionary implements Enumerable<KeyValuePair<K,V>>, so all of the
list-related functionality "just works" on pairs.

[Alan Knight, 2012/11/20 12:17:54]

It's possible, but then the iteration would be different from Map. I also
worried a bit about it being a performance impact, and also less convenient,
because the user has to extract out the key and value themselves.

I'm hopeful that some sort of mechanism for this will be in the forthcoming
collections library revisions, and am bugging Florian about it this week.

+  MapLikeIterable(this.collection);
+  final collection;
+
+  /** Iterate over the collection, passing both key and value parameters. */
+  void forEach(Function f) {
+    if (collection is Map) {

[Jennifer Messerly, 2012/11/20 01:20:47]

this seems to me like there should be two subtypes, one for when Collection is a
Map, and another if it is a generic iterable. Generally lots of type tests imply
polymorphism would be a cleaner solution.

[Alan Knight, 2012/11/20 12:17:54]

Yes, these are definitely a short-term hack to do the basic things I needed.
Re-organizing to have separate subclasses is definitely nicer, though, and did
that.

+       collection.forEach(f);

[Jennifer Messerly, 2012/11/20 01:20:47]

not sure how I feel about forEach and iterator behaving differently. iterator is
iterating over values but forEach is iterating over pairs...

[Alan Knight, 2012/11/20 12:17:54]

Yes, that's unpleasant. The iterator method wasn't actually used, so deleted it.

+    } else {
+      Iterator iterator = collection.iterator();
+      for (var i = 0; i < collection.length; i++) {
+        f(i, iterator.next());
+      }
+    }
+  }
+
+  /**
+   * Return a new collection whose keys are the same as [collection], but whose
+   * values are the result of applying [f] to the key/value pairs. So, if
+   * [collection] is a List, it will be the same as the map() method if the
+   * [key] parameter wasn't passed.
+   */
+  map(Function f) {
+    var result = copyEmpty();
+    forEach((key, value) {
+       result[key] = f(key, value);
+    });
+    return result;
+  }
+
+  /**
+   * Return an empty copy of our collection. Very limited, only knows enough
+   * to return a Map or List as appropriate.
+   */
+  copyEmpty() {
+    if (collection is Map) return new Map();
+    return new List(collection.length);
+  }
+
+  /**
+   * Return an iterator for [collection]. If it's a Map, then return an iterator
+   * on its values. Otherwise just return the collection's normal iterator.
+   */
+  Iterator iterator() {
+    if (collection is Map) {
+      return collection.values.iterator();
+    } else {
+      return collection.iterator();
+    }
+  }
+}
+
+/**
+ * An inverse of MapLikeIterable. Lets you iterate polymorphically between
+ * List-like and Map-like things, but making them behave like Lists, instead
+ * of behaving like Maps.
+ * So values(["a", "b", "c"]).forEach((value) => ...);
+ * will loop over the values "a", "b", "c", as if it were a List of values.
+ * Only supports forEach() and map() operations because that was all I needed
+ * for the moment.
+ */
+ListLikeIterable values(x) => new ListLikeIterable(x);
+
+/**
+ * A class for iterating over things as if they were Lists, which primarily
+ * means that forEach passes one argument, and map() returns a new Map
+ * with the same keys as [collection] and values which haev been transformed
+ * by the argument to map().
+ */
+class ListLikeIterable {

[Jennifer Messerly, 2012/11/20 01:20:47]

I'm not seeing the point of this class. If collection is! Map, then all the
methods simply forward. If the collection is a Map, then it behaves like
MapLikeIterable, except for forEach...

Personally, I would try to redesign these two types (ListLike and MapLike) and
see if:
* they can both be defined as "implements Collection<T>" (or List<T>) and use
generics
* they can avoid wrapping normal lists

[Alan Knight, 2012/11/20 12:17:54]

Split this out so that if you call values() on an Iterable you just get the same
thing back, and simplified this code so that it's just for Maps. The things it
provides are a forEach() that takes one parameter, and a map() operation.

On redesigning the two, implementing either Collection or List would drag along
a lot more methods that aren't used right now, which I'm reluctant to do for
code that I'm hoping I'll be able to just delete soon and use library facilities
that are more general-purpose.  It doesn't seem like it would be easy to
implement either, because the point of MapLikeIterable is to behave like a Map.
Map doesn't implement Collection, and can't, because its definitions conflict,
notably forEach. It might be possible for MapLikeIterable to implement Map and
ListLikeIterable to implement List, although there are some questionable
operations there, e.g. I don't really want to provide []=(int x) on a Map with
semantics of picking an arbitrary ordering and replacing the element with that
index. And if its semantics were instead to just delegate to the map's []=
operation then the type signature isn't right.

For the purposes of this code, a generic parameter wouldn't be much use because
most of the uses would be <dynamic>.

+  ListLikeIterable(this.collection);
+  final collection;
+
+  /** Iterate over the collection, passing just the value parameters. */
+  forEach(f) {
+    if (collection is Map) {
+      collection.forEach((key, value) => f(value));

[Jennifer Messerly, 2012/11/20 01:20:47]

is this just collection.values.forEach(f)?

[Alan Knight, 2012/11/20 12:17:54]

Yes, but avoids asking for values, which can be an expensive operation (i.e.
copying). It's starting to sound like the intention is that keys/values can be
relied on to be fast, although looking at the actual implementation some have it
directly available as a field and some (e.g. _LinkedHashMapImpl) are copying.

I think this is definitely something that the new libraries will fix by having
lazy iterables.

+    } else {
+      collection.forEach(f);
+    }
+  }
+
+  /**
+   * Return a new collection whose keys are the same as [collection], but whose
+   * values are the result of applying [f] to the key/value pairs. So, if
+   * [collection] is a List, it will be the same as if map() had been called
+   * directly on [collection].
+   */
+  map(Function f) {
+    if (collection is Map) {
+      var result = copyEmpty();
+      collection.forEach((key, value) {
+        result[key] = f(value);
+      });
+      return result;
+    } else {
+      return collection.map(f);
+    }
+  }
+
+  /**
+   * Return an empty copy of our collection. Very limited, only knows enough
+   * to return a Map or List as appropriate.
+   */
+  copyEmpty() {
+    if (collection is Map) return new Map();
+    return new List(collection.length);
+  }
+
+  /**
+   * Return an iterator that behaves like a List iterator, taking one parameter.
+   */
+  Iterator iterator() {
+    if (collection is Map) {
+      return collection.values.iterator();
+    } else {
+      return collection.iterator();
+    }
+  }
+}