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

pkg/serialization/lib/serialization.dart

Index: pkg/serialization/lib/serialization.dart
diff --git a/pkg/serialization/lib/serialization.dart b/pkg/serialization/lib/serialization.dart
index 522a7d10658792714a83c393036a88abdc39df52..0f4deff8cceb135df07b808fddd0376fae3808b0 100644
--- a/pkg/serialization/lib/serialization.dart
+++ b/pkg/serialization/lib/serialization.dart
@@ -34,7 +34,7 @@
  * This creates a new serialization and adds a rule for address objects. Right
  * now it has to be passed an address instance because of limitations using
  * Address as a literal. Then we ask the [Serialization] to write the address
- * and we get back a Map which is a [json]able representation of the state of
+ * and we get back a Map which is a JSONable representation of the state of

[Alan Knight, 2013/06/26 19:26:29]

The point of that syntax was to provide a link in the documentation that takes
you to the json package. Sadly that doesn't work, because DartDoc, but Andrei
tells me that it will work before all that long. So I'd rather leave the links
in place.

Reviews do tend to go faster when they're smaller/ more focused, so I don't have
to wait for e.g. the DartDoc guy to be in to check up on things that aren't
really part of main objective, or ponderthe merits of a final List that's
mutated versus replacing a List.

  * the address and related objects. Note that while the output in this case
  * is a [Map], the type will vary depending on which output format we've told
  * the [Serialization] to use.
@@ -144,7 +144,7 @@
  * By default this uses a representation in which objects are represented as
  * maps keyed by field name, but in which references between objects have been
  * converted into Reference objects. This is then typically encoded as
- * a [json] string, but can also be used in other ways, e.g. sent to another
+ * a JSON string, but can also be used in other ways, e.g. sent to another
  * isolate.
  *
  * We can write objects in different formats by passing a [Format] object to
@@ -359,9 +359,9 @@ class Serialization {
   /**
    * This writes out an object graph rooted at [object] and returns the result.
    * The [format] parameter determines the form of the result. The default
-   * format returns a String in [json] format.
+   * format returns a String in JSON format.
    */
-  write(Object object, [Format format]) {
+  write(Object object, {Format format}) {
     return newWriter(format).write(object);
   }
 
@@ -370,13 +370,14 @@ class Serialization {
    * want to do something more complex with the writer than just returning
    * the final result.
    */
-  Writer newWriter([Format format]) =>
-      new Writer(this, format);
+  Writer newWriter([Format format]) => new Writer(this, format);
 
   /**
    * Read the serialized data from [input] and return the root object
    * from the result. The [input] can be of any type that the [Format]
    * reads/writes, but normally will be a [List], [Map], or a simple type.
+   * The [format] parameter determines the form of the result. The default
+   * format returns a String in JSON format.
    * 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
@@ -384,8 +385,8 @@ class Serialization {
    * class name as a key. In addition to the [externals] map provided here,
    * values will be looked up in the [namedObjects] map.
    */
-  read(input, [Map externals = const {}]) {
-    return newReader().read(input, externals);
+  read(input, {Format format, Map externals: const {}}) {
+    return newReader(format).read(input, externals);
   }
 
   /**
@@ -430,13 +431,17 @@ class Serialization {
       return create ? [addRuleFor(target)] : applicable;
     }
 
-    if (applicable.length == 1) return applicable;
+    if (applicable.length == 1) {
+      return applicable;
+    }

[Alan Knight, 2013/06/26 19:26:29]

I can see the one directly below, but a guard clause that fits on one line I'd
rather have as a one-liner.

     var first = applicable.first;
     var finalRules = applicable.where(
         (x) => !x.mustBePrimary || (x == first));
 
-    if (finalRules.isEmpty) throw new SerializationException(
-        'No valid rule found for object $object');
+    if (finalRules.isEmpty) {
+      throw new SerializationException(
+          'No valid rule found for object $object');
+    }
     return finalRules;
   }
 
@@ -500,6 +505,6 @@ class Serialization {
  */
 class SerializationException implements Exception {
   final String message;
-  const SerializationException([this.message]);
-  toString() => "SerializationException($message)";
+  const SerializationException(this.message);
+  String toString() => "SerializationException($message)";
 }