Make input/output formats pluggable, adapt to new libraries

pkg/serialization/lib/src/reader_writer.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;
 
 /**
  * This writes out the state of the objects to an external format. It holds
  * all of the intermediate state needed. The primary API for it is the
  * [write] method.
@@ skipping 13 matching lines @@
    * the full set of objects to be written.*/
   Trace trace;
 
   /**
    * When we write out objects, should we also write out a description
    * of the rules for the serialization. This defaults to the corresponding
    * value on the Serialization.
    */
   bool selfDescribing;
 
+  Format format = new SimpleMapFormat();
+
   /**
    * Objects that cannot be represented in-place in the serialized form need
    * to have references to them stored. The [Reference] objects are computed
    * once and stored here for each object. This provides some space-saving,
    * but also serves to record which objects we have already seen.
    */
   final Map<dynamic, Reference> references =
       new IdentityMap<Object, Reference>();
 
   /**
    * The state of objects that need to be serialized is stored here.
    * Each rule has a number, and rules keep track of the objects that they
    * serialize, in order. So the state of any object can be found by indexing
    * from the rule number and the object number within the rule.
    * The actual representation of the state is determined by the rule. Lists
    * and Maps are common, but it is arbitrary.
    */
   final List<List> states = new List<List>();
 
   /** Return the list of rules we use. */
   List<SerializationRule> get rules => serialization._rules;
 
   /**
    * Creates a new [Writer] that uses the rules from its parent
    * [Serialization]. Serializations do not keep any state
    * related to a particular read/write, so the same one can be used
    * for multiple different Readers/Writers.
    */
-  Writer(this.serialization) {
+  Writer(this.serialization, [Format newFormat]) {
     trace = new Trace(this);
     selfDescribing = serialization.selfDescribing;
+    if (newFormat != null) format = newFormat;
   }
 
   /**
    * This is the main API for a [Writer]. It writes the objects and returns
-   * the serialized representation, currently a JSON format of a map
-   * whose data is either lists indexed by field position or maps indexed
-   * by field name, and holding either primitives or references. See [toMaps]
+   * the serialized representation, as determined by [format].
    */
-  // TODO(alanknight): Generalize the output representation. Probably requires
-  // introducing some sort of OutputFormat object.
-  String write(anObject) {
+  write(anObject) {
     trace.addRoot(anObject);
     trace.traceAll();
     _flatten();
-    return toStringFormat();
+    return format.generateOutput(this);
   }
 
   /**
-   * This is an alternate writing API that writes the objects and returns
-   * the serialized representation as a List of simple objects.
-   * See [toFlatFormat].
-   */
-  List writeFlat(anObject) {
-    shouldUseReferencesForPrimitives = true;
-    trace.addRoot(anObject);
-    trace.traceAll();
-    _flatten();
-    return toFlatFormat();
-  }
-
-  /**
-   * Write to a simple flat format. This format is at the proof of concept
-   * stage, so details are not finalized and are likely to change in the future.
-   * Right now this produces a List containing null, int, and String. This is
-   * more space-efficient than the map format created by [toStringFormat] or
-   * [toMaps], but is much less human-readable.
-   */
-  List toFlatFormat() {
-    var result = new List(3);
-    // TODO(alanknight): Don't make it call toMaps in order to make non-maps.
-    // As part of that, if writing flat, the rule serialization should be flat.
-    var stuff = toMaps();
-    result[0] = stuff["rules"];
-    var roots = new List();
-    stuff["roots"].forEach((x) => x.writeToList(roots));
-    result[2] = roots;
-
-    // TODO(alanknight): This needs serious generalization. Do we introduce
-    // an output format object that the rules talk to? Do we make use of the
-    // fact that rules talk to something that looks to them like a List. Do
-    // we then mandate that instead of saying they have complete charge of
-    // their own storage?
-    var flatData = [];
-    for (var eachRule in rules) {
-      var ruleData = stuff["data"][eachRule.number];
-      flatData.add(ruleData.length);
-      eachRule.dumpStateInto(ruleData, flatData);
-    }
-    result[1] = flatData;
-    return result;
-  }
-
-  /**
    * Given that we have fully populated the list of [states], and more
    * importantly, the list of [references], go through each state and turn
    * anything that requires a [Reference] into one. Since only the rules
    * know the representation they use for state, delegate to them.
    */
   void _flatten() {
     for (var eachRule in rules) {
       _growStates(eachRule);
       var index = eachRule.number;
       for (var eachState in states[index]) {
@@ skipping 29 matching lines @@
       var state = rule.extractState(object, trace.note);
       _addStateForRule(rule, state);
     }
   }
 
   /**
    * Should we store primitive objects directly or create references for them.
    * That depends on which format we're using, so a flat format will want
    * references, but the Map format can store them directly.
    */
-  bool shouldUseReferencesForPrimitives = false;
+  bool get shouldUseReferencesForPrimitives
+      => format.shouldUseReferencesForPrimitives;
+
+  /**
+   * Returns a serialized version of the [SerializationRule]s used to write
+   * the data, if [selfDescribing] is true, otherwise returns null.
+   */
+  serializedRules() {
+    if (!selfDescribing) return null;
+    var meta = serialization.ruleSerialization();
+    var writer = new Writer(meta);
+    writer.selfDescribing = false;
+    return writer.write(serialization._rules);
+  }
 
   /** Record a [state] entry for a particular rule. */
   void _addStateForRule(eachRule, state) {
     _growStates(eachRule);
     states[eachRule.number].add(state);
   }
 
   /** Find what the object number for the thing we're about to add will be.*/
   int _nextObjectNumberFor(SerializationRule rule) {
     _growStates(rule);
@@ skipping 27 matching lines @@
    * the context of a particular rule, and if the rule has more than one,
    * this will return the one for the primary rule, defined as the one that
    * is listed in its canonical reference.
    */
   int _objectNumberFor(object) {
     var reference = references[object];
     return (reference == null) ? -1 : reference.objectNumber;
   }
 
   /**
-   * Return the serialized data in string format. Currently hard-coded to
-   * our custom JSON format.
-   */
-  String toStringFormat() {
-    return json.stringify(toMaps());
-  }
-
-  /**
-   * Returns the full serialized structure as nested maps. The top-level
-   * has 3 fields, "rules" which may hold a definition of the rules used,
-   * "data" which holds the serialized data, and "roots", which holds
-   * [Reference] objects indicating the root objects. Note that roots are
-   * necessary because the data is organized in the same way as the object
-   * structure, it's a list of lists holding self-contained maps which only
-   * refer to other parts via [Reference] objects.
-   * This effectively defines a custom JSON serialization format, although
-   * the details of the format vary depending which rules were used.
-   */
-  Map toMaps() {
-    var result = new Map();
-    var savedRules;
-    if (selfDescribing) {
-      var meta = serialization._ruleSerialization();
-      var writer = new Writer(meta);
-      writer.selfDescribing = false;
-      savedRules = writer.write(serialization._rules);
-    }
-    result["rules"] = savedRules;
-    result["data"] = states;
-    result["roots"] = _rootReferences(trace.roots);
-    return result;
-  }
-
-  /**
    * Return a list of [Reference] objects pointing to our roots. This will be
    * stored in the output under "roots" in the default format.
    */
-  _rootReferences(roots) =>
-    roots.mappedBy(_referenceFor).toList();
+  _rootReferences() => trace.roots.mappedBy(_referenceFor).toList();
 
   /**
    * Given an object, return a reference for it if one exists. If there's
    * no reference, return null. Once we have finished the tracing step, all
    * objects that should have a reference (roughly speaking, non-primitives)
    * can be relied on to have a reference.
    */
   _referenceFor(object) => references[object];
 
   /**
@@ skipping 43 matching lines @@
    */
   List<List> _data;
 
   /**
    * The resulting objects, indexed according to the same scheme as
    * [data], where each rule has a number, and rules keep track of the objects
    * that they serialize, in order.
    */
   List<List> objects;
 
+  Format format = new SimpleMapFormat();
+
   /**
    * Creates a new [Reader] that uses the rules from its parent
    * [Serialization]. Serializations do not keep any state related to
    * a particular read or write operation, so the same one can be used
    * for multiple different Writers/Readers.
    */
-  Reader(this.serialization) {
+  Reader(this.serialization, [Format newFormat]) {
     selfDescribing = serialization.selfDescribing;
+    if (newFormat != null) format = newFormat;
   }
 
   /**
    * When we read, we may need to look up objects by name in order to link to
    * them. This is particularly true if we have references to classes,
    * functions, mirrors, or other non-portable entities. The map in which we
    * look things up can be provided as an argument to read, but we can also
    * provide a map here, and objects will be looked up in both places.
    */
   Map namedObjects;
@@ skipping 22 matching lines @@
    * to a List of Lists whose size must match the number of rules.
    */
   // When we set the data, initialize the object storage to a matching size.
   void set data(List<List> newData) {
     _data = newData;
     objects = _data.mappedBy((x) => new List(x.length)).toList();
   }
 
   /**
    * This is the primary method for a [Reader]. It takes the input data,
-   * currently hard-coded to expect our custom JSON format, and returns
-   * the root object.
+   * decodes it according to [format] and returns the root object.
    */
-  read(String input, [Map externals = const {}]) {
+  read(rawInput, [Map externals = const {}]) {
     namedObjects = externals;
-    var topLevel = json.parse(input);
-    var ruleString = topLevel["rules"];
-    readRules(ruleString, externals);
-    data = topLevel["data"];
+    var input = format.read(rawInput, this);
+    data = input["data"];
     rules.forEach(inflateForRule);
-    var roots = topLevel["roots"];
-    return inflateReference(roots.first);
+    return inflateReference(input["roots"].first);
   }
 
   /**
    * If the data we are reading from has rules written to it, read them back
    * and set them as the rules we will use.
    */
-  void readRules(String newRules, Map externals) {
+  void readRules(String newRules) {
     // TODO(alanknight): Replacing the serialization is kind of confusing.
     List rulesWeRead = (newRules == null) ?
-        null : serialization._ruleSerialization().read(newRules, externals);
+        null : serialization.ruleSerialization().read(newRules, namedObjects);
     if (rulesWeRead != null && !rulesWeRead.isEmpty) {
       serialization = new Serialization.blank();
       rulesWeRead.forEach(serialization.addRule);
     }
   }
 
   /**
-   * This is a hard-coded read method for a vaguely flat format. It's just a
-   * proof of concept of handling more flat formats right now, and needs a lot
-   * of fixing and generalization.
-   */
-  readFlat(List input, [Map externals = const {}]) {
-    // TODO(alanknight): Way too much code duplication with read. Numerous
-    // code smells.
-    namedObjects = externals;
-    var topLevel = input;
-    var ruleString = topLevel[0];
-    readRules(ruleString, externals);
-    var flatData = topLevel[1];
-    var stream = flatData.iterator;
-    var tempData = new List(rules.length);
-     for (var eachRule in rules) {
-       tempData[eachRule.number] = eachRule.pullStateFrom(stream);
-    }
-    data = tempData;
-    for (var eachRule in rules) {
-      inflateForRule(eachRule);
-    }
-    var rootsAsInts = topLevel[2];
-    var rootStream = rootsAsInts.iterator;
-    var roots = new List();
-    while (rootStream.moveNext()) {
-      var first = rootStream.current;
-      rootStream.moveNext();
-      var second = rootStream.current;
-      roots.add(new Reference(this, first, second));
-    }
-    var x = inflateReference(roots[0]);
-    return inflateReference(roots.first);
-  }
-
-  /**
    * Inflate all of the objects for [rule]. Does the essential state for all
    * objects first, then the non-essential state. This avoids cycles in
    * non-essential state, because all the objects will have already been
    * created.
    */
   inflateForRule(rule) {
     var dataForThisRule = _data[rule.number];
     keysAndValues(dataForThisRule).forEach((position, state) {
       inflateOne(rule, position, state);
     });
@@ skipping 53 matching lines @@
 
   /** Given [reference], return the the state we have stored for it. */
   _stateFor(Reference reference) =>
       _data[reference.ruleNumber][reference.objectNumber];
 
   /** Given a reference, return the rule it references. */
   SerializationRule ruleFor(Reference reference) =>
       serialization._rules[reference.ruleNumber];
 
   /**
+   * Return the primitive rule we are using. This is an ugly mechanism to
+   * support the extra information to reconstruct objects in the
+   * [SimpleJsonFormat].
+   */
+  SerializationRule _primitiveRule() {
+    for (var each in rules) {
+      if (each.runtimeType == PrimitiveRule) {
+        return each;
+      }
+    }
+    throw new SerializationException("No PrimitiveRule found");
+  }
+
+  /**
    * Given a possible reference [anObject], call either [ifReference] or
    * [ifNotReference], depending if it's a reference or not. This is the
    * primary place that knows about the serialized representation of a
    * reference.
    */
   asReference(anObject, {Function ifReference: doNothing,
       Function ifNotReference : doNothing}) {
     if (anObject is Reference) return ifReference(anObject);
     if (anObject is Map && anObject["__Ref"] == true) {
       var ref =
@@ skipping 103 matching lines @@
     "__Ref" : true,
     "rule" : ruleNumber,
     "object" : objectNumber
   };
 
   /** Write our information to [list]. Useful in writing to flat formats.*/
   writeToList(List list) {
     list.add(ruleNumber);
     list.add(objectNumber);
   }
+
+  toString() => "Reference $ruleNumber, $objectNumber";
 }
 
 /**
  * This is used during tracing to indicate that an object should be processed
  * using a particular rule, rather than the one that might ordinarily be
  * found for it. This normally only makes sense if the object is uniquely
  * referenced, and is a more or less internal collection. See ListRuleEssential
  * for an example. It knows how to return its object and how to filter.
  */
 class DesignatedRuleForObject {
   Function rulePredicate;
   final target;
 
   DesignatedRuleForObject(this.target, this.rulePredicate);
 
   possibleRules(List rules) => rules.where(rulePredicate).toList();
 }