Add a MapRule

pkg/serialization/lib/src/serialization_rule.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.
 
 part of serialization;
 
 // TODO(alanknight): We should have an example and tests for subclassing
 // serialization rule rather than using the hard-coded ClosureToMap rule. And
 // possibly an abstract superclass that's designed to be subclassed that way.
 /**
@@ skipping 10 matching lines @@
    * Rules belong uniquely to a particular Serialization instance, and can
    * be identified within it by number.
    */
   int get number => _number;
 
   /**
    * Rules belong uniquely to a particular Serialization instance, and can
    * be identified within it by number.
    */
   void set number(x) {
-    if (_number != null) throw
+    if (_number != null && _number != x) throw
         new SerializationException("Rule numbers cannot be changed, once set");
     _number = x;
   }
 
   /**
    * Return true if this rule applies to this object, in the context
    * where we're writing it, false otherwise.
    */
   bool appliesTo(object, Writer writer);
 
   /**
    * This extracts the state from the object, calling [f] for each value
    * as it is extracted, and returning an object representing the whole
    * state at the end. The state that results will still have direct
    * pointers to objects, rather than references.
    */
   extractState(object, void f(value));
 
   /**
+   * Allows rules to tell us how they expect to store their state. If this
+   * isn't specified we can also just look at the data to tell.
+   */
+  bool get storesStateAsLists => false;
+  bool get storesStateAsMaps => false;
+  bool get storesStateAsPrimitives => false;
+
+  /**
    * Given the variables representing the state of an object, flatten it
    * by turning object pointers into Reference objects where needed. This
    * destructively modifies the state object.
    *
    * This has a default implementation which assumes that object is indexable,
    * so either conforms to Map or List. Subclasses may override to do something
-   * different.
+   * different, including returning a new state object to be used in place
+   * of the original.
    */
   // This has to be a separate operation from extracting, because we extract
   // as we are traversing the objects, so we don't yet have the objects to
   // generate references for them. It might be possible to avoid that by
   // doing a depth-first rather than breadth-first traversal, but I'm not
   // sure it's worth it.
-  void flatten(state, Writer writer) {
+  flatten(state, Writer writer) {
     keysAndValues(state).forEach((key, value) {
       var reference = writer._referenceFor(value);
-      state[key] = (reference == null) ? value : reference;
+      state[key] = reference;
     });
   }
 
   /** Return true if this rule should only be applied when we are the first
    * rule found that applies to this object. This may or may not be a hack
    * that will disappear once we have better support for multiple rules.
    * We want to have multiple different rules that apply to the same object. We
    * also want to have multiple different rules that might exclusively apply
    * to the same object. So, we want either ListRule or ListRuleEssential, and
    * only one of them can be there. But on the other hand, we may want both
@@ skipping 46 matching lines @@
 }
 
 /**
  * This rule handles things that implement List. It will recreate them as
  * whatever the default implemenation of List is on the target platform.
  */
 class ListRule extends SerializationRule {
 
   appliesTo(object, Writer w) => object is List;
 
-  state(List list) => new List.from(list);
+  bool get storesStateAsLists => true;
 
   List extractState(List list, f) {
     var result = new List();
     for (var each in list) {
       result.add(each);
       f(each);
     }
     return result;
   }
 
@@ skipping 28 matching lines @@
     return object;
   }
 
   /** Does nothing, because all the work has been done in inflateEssential. */
   inflateNonEssential(state, newList, reader) {}
 
   bool get mustBePrimary => true;
 }
 
 /**
+ * This rule handles things that implement Map. It will recreate them as
+ * whatever the default implemenation of Map is on the target platform. If a
+ * map has string keys it will attempt to retain it as a map for JSON formats,
+ * otherwise it will store it as a list of references to keys and values.
+ */
+class MapRule extends SerializationRule {
+
+  appliesTo(object, Writer w) => object is Map;
+
+  bool get storesStateAsMaps => true;
+
+  extractState(Map map, f) {
+    // Note that we make a copy here because flattening may be destructive.
+    var newMap = new Map.from(map);
+    newMap.forEach((key, value) {
+      f(key);
+      f(value);
+    });
+    return newMap;
+  }
+
+  /**
+   * Change the keys and values of [state] into references in [writer].
+   * If [state] is a map whose keys are all strings then we leave the keys
+   * as is so that JSON formats will be more readable. If the keys are
+   * arbitrary then we need to turn them into references.
+   */
+  flatten(Map state, Writer writer) {
+    bool keysAreAllStrings = state.keys.every((x) => x is String);

[Jennifer Messerly, 2013/01/25 01:19:59]

out of curiousity, why do we check all keys? Could we check each key individual
and preserve strings when possible?

[Alan Knight, 2013/01/26 01:33:38]

I don't think that would work, at least not with the current state of the JSON
support. A lot of the point of retaining things in Map form is to make readable
JSON. But the JSON support requires any Maps in its arguments to have string
keys, and will fail otherwise. So if we see any non-string keys we need to turn
the whole thing into a List instead.

+    if (keysAreAllStrings) {
+      keysAndValues(state).forEach(

[Jennifer Messerly, 2013/01/25 01:19:59]

I would have expected a return in both branches. Could we "return state;" here?

[Alan Knight, 2013/01/26 01:33:38]

Sure. The normal case for flatten() is that it destructively modifies the
existing state, and returning null is interpreted as just meaning to use the old
one. But consistently returning it in both cases probably makes the intention
clearer, so doing that.

+          (key, value) => state[key] = writer._referenceFor(value));
+    } else {
+      var newState = [];
+      keysAndValues(state).forEach((key, value) {
+        newState.add(writer._referenceFor(key));
+        newState.add(writer._referenceFor(value));
+      });
+      return newState;
+    }
+  }
+
+  inflateEssential(state, Reader r) => new Map();
+
+  // For a map, we consider all of its state non-essential and add it
+  // after creation.
+  inflateNonEssential(state, Map newMap, Reader r) {
+    if (state is List) {
+      inflateNonEssentialFromList(state, newMap, r);
+    } else {
+      inflateNonEssentialFromMap(state, newMap, r);
+    }
+  }
+
+  void inflateNonEssentialFromList(List state, Map newMap, Reader r) {
+    var key;
+    for (var each in state) {
+      if (key == null) {
+        key = each;
+      } else {
+        newMap[r.inflateReference(key)] = r.inflateReference(each);
+        key = null;
+      }
+    }
+  }
+
+  void inflateNonEssentialFromMap(Map state, Map newMap, Reader r) {
+    state.forEach((key, value) {
+      newMap[r.inflateReference(key)] = r.inflateReference(value);
+    });
+  }
+
+  bool get hasVariableLengthEntries => true;
+}
+
+/**
  * This rule handles primitive types, defined as those that we can normally
  * represent directly in the output format. We hard-code that to mean
  * num, String, and bool.
  */
 class PrimitiveRule extends SerializationRule {
   appliesTo(object, Writer w) {
     return isPrimitive(object);
   }
   extractState(object, Function f) => object;
-  void flatten(object, Writer writer) {}
+  flatten(object, Writer writer) {}
   inflateEssential(state, Reader r) => state;
   inflateNonEssential(object, _, Reader r) {}
 
+  bool get storesStateAsPrimitives => true;
+
   /**
    * Indicate whether we should save pointers to this object as references
    * or store the object directly. For primitives this depends on the format,
    * so we delegate to the writer.
    */
   bool shouldUseReferenceFor(object, Writer w) =>
       w.shouldUseReferencesForPrimitives;
 
   bool get hasVariableLengthEntries => false;
 }
@@ skipping 61 matching lines @@
 
   /** Extract the state of the named objects as just the object itself. */
   extractState(object, Function f) => [object];
 
   /** When we flatten the state we save it as the name. */
   // TODO(alanknight): This seems questionable. In a truly flat format we may
   // want to have extracted the name as a string first and flatten it into a
   // reference to that. But that requires adding the Writer as a parameter to
   // extractState, and I'm reluctant to add yet another parameter until
   // proven necessary.
-  void flatten(state, Writer writer) {
+  flatten(state, Writer writer) {
     state[0] = nameFor(state.first, writer);
   }
 
   /** Look up the named object and return it. */
   inflateEssential(state, Reader r) => r.objectNamed(state.first);
 
   /** Set any non-essential state on the object. For this rule, a no-op. */
   inflateNonEssential(state, object, Reader r) {}
 
   /** Return the name for this object in the Writer. */
@@ skipping 150 matching lines @@
   _throw() {
     throw new UnsupportedError("Not modifiable");
   }
   operator []=(x, y) => _throw();
   add(x) => _throw();
   addLast(x) => _throw();
   addAll(x) => _throw();
   sort([f]) => _throw();
   clear() => _throw();
   removeAt(x) => _throw();
+  remove(x) => _throw();
   removeLast() => _throw();
-  remove(x) => _throw();
   removeAll(x) => _throw();
   retainAll(x) => _throw();
   removeMatching(x) => _throw();
   retainMatching(x) => _throw();
   getRange(x, y) => _throw();
   setRange(x, y, z, [a]) => _throw();
   removeRange(x, y) => _throw();
   insertRange(x, y, [z]) => _throw();
+  get reversed => _throw();
   void set length(x) => _throw();
-  List get reversed => _throw();
 }