pkg/serialization: add format param to Serialization.read method

pkg/serialization/lib/src/format.dart

 part of serialization;
 
 /**
  * An abstract class for serialization formats. Subclasses define how data
  * is read or written to a particular output mechanism.
  */
 abstract class Format {
 
   const Format();
 
@@ skipping 62 matching lines @@
     reader._data = topLevel["data"];
     topLevel["roots"] = topLevel["roots"];
     return topLevel;
   }
 }
 
 /**
  * A format that stores the data in maps which can be converted into a JSON
  * string or passed through an isolate. Note that this consists of maps, but
  * that they don't follow the original object structure or look like the nested
- * maps of a [json] representation. They are flat, and [Reference] objects
+ * maps of a JSON representation. They are flat, and [Reference] objects
  * are converted into a map form that will not make sense to
  * anything but this format. For simple acyclic JSON that other programs
  * can read, use [SimpleJsonFormat]. This is the default format, and is
  * easier to read than the more efficient [SimpleFlatFormat].
  */
 class SimpleMapFormat extends InternalMapFormat {
 
   const SimpleMapFormat();
 
   /**
    * Generate output for this format from [w] and return it as a String which
-   * is the [json] representation of a nested Map structure. The top level has
+   * is the JSON representation of a nested Map structure. 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 not 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<String, dynamic> generateOutput(Writer w) {
     forAllStates(w, (x) => x is Reference, referenceToMap);
     var result = super.generateOutput(w);
     result["roots"] = result["roots"].map(
         (x) => x is Reference ? referenceToMap(x) : x).toList();
     return result;
   }
 
   /**
    * Convert the data generated by the rules to have maps with the fields
    * of [Reference] objects instead of the [Reference] so that the structure
    * can be serialized between isolates and json easily.
    */
-  forAllStates(ReaderOrWriter w, bool predicate(value),
+  void forAllStates(ReaderOrWriter w, bool predicate(value),
                void transform(value)) {
     for (var eachRule in w.rules) {
       var ruleData = w.states[eachRule.number];
       for (var data in ruleData) {
         keysAndValues(data).forEach((key, value) {
           if (predicate(value)) {
             data[key] = transform(value);
           }
         });
       }
     }
   }
 
-  /** Convert the reference to a [json] serializable form. */
+  /** Convert the reference to a JSON serializable form. */
   Map<String, int> referenceToMap(Reference ref) => ref == null ? null :
     {
       "__Ref" : 0,
       "rule" : ref.ruleNumber,
       "object" : ref.objectNumber
     };
 
   /**
    * Convert the [referenceToMap] form for a reference back to a [Reference]
    * object.
@@ skipping 13 matching lines @@
         (ref) => ref is Map && ref["__Ref"] != null,
         (ref) => mapToReference(reader, ref));
     topLevel["roots"] = topLevel["roots"]
         .map((x) => x is Map<String, int> ? mapToReference(reader, x) : x)
         .toList();
     return topLevel;
   }
 }
 
 /**
- * A format for "normal" [json] representation of objects. It stores
+ * A format for "normal" JSON representation of objects. It stores
  * the fields of the objects as nested maps, and doesn't allow cycles. This can
- * be useful in talking to existing APIs that expect [json] format data. The
+ * be useful in talking to existing APIs that expect JSON format data. The
  * output will be either a simple object (string, num, bool), a List, or a Map,
  * with nesting of those.
  * Note that since the classes of objects aren't normally stored, this isn't
  * enough information to read back the objects. However, if the
  * If the [storeRoundTripInfo] field of the format is set to true, then this
  * will store the rule number along with the data, allowing reconstruction.
  */
 class SimpleJsonFormat extends SimpleMapFormat {
 
   /**
    * Indicate if we should store rule numbers with map/list data so that we
    * will know how to reconstruct it with a read operation. If we don't, this
    * will be more compliant with things that expect known format JSON as input,
    * but we won't be able to read back the objects.
    */
   final bool storeRoundTripInfo;
 
   /**
    * If we store the rule numbers, what key should we use to store them.
    */
   static const String RULE = "_rule";
   static const String RULES = "_rules";
   static const String DATA = "_data";
   static const String ROOTS = "_root";
 
   const SimpleJsonFormat({this.storeRoundTripInfo : false});
 
   /**
    * Generate output for this format from [w] and return it as
-   * the [json] representation of a nested Map structure.
+   * the JSON representation of a nested Map structure.
    */
   generateOutput(Writer w) {
     jsonify(w);
     var root = w._rootReferences().first;
     if (root is Reference) root = w.stateForReference(root);
     if (w.selfDescribing && storeRoundTripInfo) {
       root = new Map()
           ..[RULES] = w.serializedRules()
           ..[DATA] = root;
     }
     return root;
   }
 
   /**
    * Convert the data generated by the rules to have nested maps instead
    * of Reference objects and to add rule numbers if [storeRoundTripInfo]
    * is true.
    */
-  jsonify(Writer w) {
+  void jsonify(Writer w) {
     for (var eachRule in w.rules) {
       var ruleData = w.states[eachRule.number];
       jsonifyForRule(ruleData, w, eachRule);
     }
   }
 
   /**
    * For a particular [rule] modify the [ruleData] to conform to this format.
    */
-  jsonifyForRule(List ruleData, Writer w, SerializationRule rule) {
+  void jsonifyForRule(List ruleData, Writer w, SerializationRule rule) {
     for (var i = 0; i < ruleData.length; i++) {
       var each = ruleData[i];
       if (each is List) {
         jsonifyEntry(each, w);
         if (storeRoundTripInfo) ruleData[i].add(rule.number);
       } else if (each is Map) {
         jsonifyEntry(each, w);
         if (storeRoundTripInfo) each[RULE] = rule.number;
       }
     }
   }
 
   /**
    * For one particular entry, which is either a Map or a List, update it
    * to turn References into a nested List/Map.
    */
-  jsonifyEntry(map, Writer w) {
+  void jsonifyEntry(map, Writer w) {
     // Note, if this is a Map, and the key might be a reference, we need to
     // bend over backwards to avoid concurrent modifications. Non-string keys
     // won't actually work if we try to write this to json, but might happen
     // if e.g. sending between isolates.
     var updates = new Map();
     keysAndValues(map).forEach((key, value) {
       if (value is Reference) updates[key] = w.stateForReference(value);
     });
     updates.forEach((k, v) => map[k] = v);
   }
@@ skipping 234 matching lines @@
       return [];
     } else {
       throw new SerializationException("Invalid data in serialization");
     }
   }
 
   /**
    * Read data for [rule] from [input] with [length] number of entries,
    * creating lists from the results.
    */
-  readLists(Iterator input, SerializationRule rule, int length, Reader r) {
+  List readLists(Iterator input, SerializationRule rule, int length, Reader r) {
     var ruleData = [];
     for (var i = 0; i < length; i++) {
       var subLength =
           rule.hasVariableLengthEntries ? _next(input) : rule.dataLength;
       var subList = [];
       ruleData.add(subList);
       for (var j = 0; j < subLength; j++) {
         subList.add(nextReferenceFrom(input, r));
       }
     }
     return ruleData;
   }
 
   /**
    * Read data for [rule] from [input] with [length] number of entries,
    * creating maps from the results.
    */
-  readMaps(Iterator input, SerializationRule rule, int length, Reader r) {
+  List readMaps(Iterator input, SerializationRule rule, int length, Reader r) {
     var ruleData = [];
     for (var i = 0; i < length; i++) {
       var subLength =
           rule.hasVariableLengthEntries ? _next(input) : rule.dataLength;
       var map = new Map();
       ruleData.add(map);
       for (var j = 0; j < subLength; j++) {
         var key = nextReferenceFrom(input, r);
         var value = nextReferenceFrom(input, r);
         map[key] = value;
       }
     }
     return ruleData;
   }
 
   /**
    * Read data for [rule] from [input] with [length] number of entries,
    * treating the data as primitives that can be returned directly.
    */
-  readPrimitives(Iterator input, SerializationRule rule, int length) {
+  List readPrimitives(Iterator input, SerializationRule rule, int length) {
     var ruleData = [];
     for (var i = 0; i < length; i++) {
       ruleData.add(_next(input));
     }
     return ruleData;
   }
 
   /** Read the next Reference from the input. */
   Reference nextReferenceFrom(Iterator input, Reader r) {
     var a = _next(input);
     var b = _next(input);
     if (a == null) {
       return null;
     } else {
       return new Reference(r, a, b);
     }
   }
 
   /** Return the next element from the input. */
   _next(Iterator input) {
     input.moveNext();
     return input.current;
   }
 }