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 148 matching lines @@
  * This class defines a particular serialization scheme, in terms of
  * [SerializationRule] instances, and supports reading and writing them.
  * See library comment for examples of usage.
  */
 class Serialization {
 
   /**
    * The serialization is controlled by the list of Serialization rules. These
    * are most commonly added via [addRuleFor].
    */
-  List rules = [];
+  List _rules = [];
+
+  /**
+   * The serialization is controlled by the list of Serialization rules. These
+   * are most commonly added via [addRuleFor].
+   */
+  List get rules => _rules;
 
   /**
    * 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;
+    return !_rules.some((x) => x is CustomRule);
+  }
+
+  /**
+   * 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 52 matching lines @@
     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) {
-    rule.number = rules.length;
-    rules.add(rule);
+    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.
    */
   String write(Object object) {
     return newWriter().write(object);
   }
 
   /**
    * Return a new [Writer] object for this serialization. This is useful if you
    * want to do something more complex with the writer than just returning
    * the final result.
    */
   Writer newWriter() => new Writer(this);
 
   /**
    * 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);
+      candidateRules = object.possibleRules(_rules);
     } else {
       target = object;
-      candidateRules = rules;
+      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]);
 }