Better ability to have hand-written custom rules and various cleanups.

pkg/serialization/lib/serialization.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 provides a general-purpose serialization facility for Dart objects. A
  * [Serialization] is defined in terms of [SerializationRule]s and supports
  * reading and writing to different formats.
  *
  * Setup
@@ skipping 159 matching lines @@
 
   /**
    * When reading, we may need to resolve references to existing objects in
    * the system. The right action may not be to create a new instance of
    * something, but rather to find an existing instance and connect to it.
    * For example, if we have are serializing an Email message and it has a
    * link to the owning account, it may not be appropriate to try and serialize
    * the account. Instead we should just connect the de-serialized message
    * object to the account object that already exists there.
    */
-  Map<String, dynamic> externalObjects = {};
+  Map<String, dynamic> namedObjects = {};
 
   /**
    * When we write out data using this serialization, should we also write
-   * out a description of the rules.
+   * out a description of the rules. This is on by default unless using
+   * CustomRule subclasses, in which case it requires additional setup and
+   * is off by default.
    */
-  bool selfDescribing = true;
+  bool _selfDescribing;
+
+  /**
+   * When we write out data using this serialization, should we also write
+   * out a description of the rules. This is on by default unless using
+   * CustomRule subclasses, in which case it requires additional setup and
+   * is off by default.
+   */
+  bool get selfDescribing {
+    if (_selfDescribing != null) return _selfDescribing;
+    _selfDescribing = !rules.some((x) => x is CustomRule);

[Jennifer Messerly, 2012/12/12 20:38:28]

Do we know that the set of "rules" is fixed at this point? In other words, could
add a CustomRule later but this property has cached a value of true?

Also, what happens if I set selfDescribing to true but I in fact do have a
CustomRule? Does it work?

It seems potentially fragile to compute a value once and cache it if the things
used by the computation could change later. It would be good to invalidate this
property in addRule, or just don't cache it.

[Alan Knight, 2012/12/12 21:19:33]

Yes, this was a cheesy attempt to make it default to the right thing, but allow
the user to override it. It _probably_ doesn't get called until all the rules
are added, but that's pretty fragile. I think not caching the value if we
compute it is the simplest thing. Then the user can still force it. In which
case the only way it's going to work right now is if the user adds named objects
for each such rule in the meta-serialization. Which they can't actually do right
now, but ought to be able to.

+    return _selfDescribing;
+  }
+
+  /**
+   * When we write out data using this serialization, should we also write
+   * out a description of the rules. This is on by default unless using
+   * CustomRule subclasses, in which case it requires additional setup and
+   * is off by default.
+   */
+  set selfDescribing(x) => _selfDescribing = x;
 
   /**
    * Creates a new serialization with a default set of rules for primitives
    * and lists.
    */
   Serialization() {
     addDefaultRules();
   }
 
   /**
@@ skipping 51 matching lines @@
     // it will always find the first one.
     addRule(new ListRuleEssential());
   }
 
   /**
    * Add a new SerializationRule [rule]. The addRuleFor method will probably
    * handle most simple cases, but for adding an arbitrary rule, including
    * a SerializationRule subclass which you have created, you can use this
    * method.
    */
   void addRule(SerializationRule rule) {

[Jennifer Messerly, 2012/12/12 20:38:28]

An issue I just noticed (maybe we already have a TODO) -- rules.add is different
from addRule. If someone added a rule with "rules.add" it wouldn't have the
correct invariants (number property not set). This could be fixed in a few ways:
* not expose the raw list to the user
* expose a smart list that knows how to maintain the invariants (we do something
similar for DOM node lists -- adding to them sets their parent property -- but
it's more work)
* don't set "rule.number" or check for CustomRules up front. Instead wait until
we start serialization, and then update the properties:

[Alan Knight, 2012/12/12 21:19:33]

Made rules private. If it starts seem like people really need access will look
further at one of the other approaches.

     rule.number = rules.length;
     rules.add(rule);
   }
 
   /**
    * This is the basic method to write out an object graph rooted at
    * [object] and return the result. Right now this is hard-coded to return
    * a String from a custom [JSON] format, but that is likely to change to be
    * more pluggable in the near future.
    */
@@ skipping 10 matching lines @@
 
   /**
    * Write out the tree in a custom flat format, returning a list containing
    * only "simple" types: num, String, and bool.
    */
   List writeFlat(Object object) {
     return newWriter().writeFlat(object);
   }
 
   /**
-   * Read the serialized data from [input] and return a List of the root
-   * objects from the result. If there are objects that need to be resolved
+   * Read the serialized data from [input] and return the root object
+   * from the result. If there are objects that need to be resolved
    * in the current context, they should be provided in [externals] as a
    * Map from names to values. In particular, in the current implementation
    * any class mirrors needed should be provided in [externals] using the
    * class name as a key. In addition to the [externals] map provided here,
    * values will be looked up in the [externalObjects] map.
    */
-  List read(String input, [Map externals = const {}]) {
+  read(String input, [Map externals = const {}]) {
     return newReader().read(input, externals);
   }
 
   /**
-   * In the most common case there is only a single root object to be read,
-   * and this method can be used to return just one object rather than
-   * a List. The [input] and [externals] parameters are the same as for the
-   * general [read] method.
-   */
-  Object readOne(String input, [Map externals = const {}]) {
-    return newReader().readOne(input, externals);
-  }
-
-  /**
    * Return a new [Reader] object for this serialization. This is useful if
    * you want to do something more complex with the reader than just returning
    * the final result.
    */
   Reader newReader() => new Reader(this);
 
   /**
    * Return the list of SerializationRule that apply to [object]. For
    * internal use, but public because it's used in testing.
    */
-  List<SerializationRule> rulesFor(object) {
+  List<SerializationRule> rulesFor(object, Writer w) {
     // This has a couple of edge cases.
     // 1) The owning object may have indicated we should use a different
     // rule than the default.
     // 2) We may not have a rule, in which case we lazily create a BasicRule.
     // 3) Rules are allowed to say mustBePrimary, meaning that they can be used
     // iff no other rule was chosen first.
     // TODO(alanknight): Can the mustBePrimary mechanism be removed or changed.
     // It adds an order dependency to the rules, and is messy. Reconsider in the
     // light of a more general mechanism for multiple rules per object.
     // TODO(alanknight): Finding which rules apply seems likely to be a
     // bottleneck, particularly with the current reflective implementation.
     // Consider how to improve it. e.g. cache the list of rules by class. But
     // be careful of issues like rules which have arbitrary predicates. Or
     // consider having the arbitrary predicates be secondary to an initial
     // class-based lookup mechanism.
     var target, candidateRules;
     if (object is DesignatedRuleForObject) {
       target = object.target;
       candidateRules = object.possibleRules(rules);
     } else {
       target = object;
       candidateRules = rules;
     }
-    List applicable = candidateRules.filter((each) => each.appliesTo(target));
+    List applicable = candidateRules.filter(
+        (each) => each.appliesTo(target, w));
 
     if (applicable.isEmpty) {
       return [addRuleFor(target)];
     }
 
     if (applicable.length == 1) return applicable;
     var first = applicable[0];
     var finalRules = applicable.filter(
         (x) => !x.mustBePrimary || (x == first));
 
@@ skipping 10 matching lines @@
    */
   Serialization _ruleSerialization() {
     // TODO(alanknight): There's an extensibility issue here with new rules.
     // TODO(alanknight): How to handle rules with closures? They have to
     // exist on the other side, but we might be able to hook them up by name,
     // or we might just be able to validate that they're correctly set up
     // on the other side.
 
     // Make some bogus rule instances so we have something to feed rule creation
     // and get their types. If only we had class literals implemented...
-    var closureRule = new ClosureToMapRule.stub([].runtimeType);
-    var basicRule = new BasicRule(reflect(null).type, '', [], [], []);
+   var basicRule = new BasicRule(reflect(null).type, '', [], [], []);
 
     var meta = new Serialization()
       ..selfDescribing = false
       ..addRuleFor(new ListRule())
       ..addRuleFor(new PrimitiveRule())
       ..addRuleFor(new ListRuleEssential())
       ..addRuleFor(basicRule,
           constructorFields: ['typeWrapped',
             'constructorName',
             'constructorFields', 'regularFields', []],
           fields: [])
-      ..addRule(new ClassMirrorRule());
-    meta.externalObjects = externalObjects;
+      ..addRule(new NamedObjectRule())
+      ..addRule(new MirrorRule());
+    meta.namedObjects = namedObjects;
     return meta;
   }
+
+  /** Return true if our [namedObjects] collection has an entry for [object].*/
+  bool _hasNameFor(object) {
+    var sentinel = const _Sentinel();
+    return _nameFor(object, () => sentinel) != sentinel;
+  }
+
+  /**
+   * Return the name we have for [object] in our [namedObjects] collection or
+   * the result of evaluating [ifAbsent] if there is no entry.
+   */
+  _nameFor(object, [ifAbsent]) {
+    for (var key in namedObjects.keys) {
+      if (identical(namedObjects[key], object)) return key;
+    }
+    return ifAbsent == null ? null : ifAbsent();
+  }
 }
 
 /**
  * An exception class for errors during serialization.
  */
 class SerializationException implements Exception {
   final String message;
   const SerializationException([this.message]);
 }