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

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.
  *
  * ## Installing ##
@@ skipping 16 matching lines @@
  *      var address = new Address();
  *      address.street = 'N 34th';
  *      address.city = 'Seattle';
  *      var serialization = new Serialization()
  *          ..addRuleFor(address);
  *      Map output = serialization.write(address);
  *
  * 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.
  *
  * The version above used reflection to automatically identify the public
  * fields of the address object. We can also specify those fields explicitly.
  *
  *      var serialization = new Serialization()
  *        ..addRuleFor(address,
  *            constructor: "create",
@@ skipping 89 matching lines @@
  *
  * Writing
  * =======
  * To write objects, we use the write() method.
  *
  *       var output = serialization.write(someObject);
  *
  * 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
  * the [Serialization.write] method or by getting a [Writer] object.
  * The available formats
  * include the default, a simple "flat" format that doesn't include field names,
  * and a simple JSON format that produces output more suitable for talking to
  * services that expect JSON in a predefined format. Examples of these are
  *
  *      Map output = serialization.write(address, new SimpleMapFormat());
@@ skipping 194 matching lines @@
    * method.
    */
   void addRule(SerializationRule rule) {
     rule.number = rules.length;
     rules.add(rule);
   }
 
   /**
    * 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);
   }
 
   /**
    * 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([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
    * 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 [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);
   }
 
   /**
    * 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([Format format]) => new Reader(this, format);
 
   /**
@@ skipping 24 matching lines @@
       target = object;
       candidateRules = rules;
     }
     Iterable applicable = candidateRules.where(
         (each) => each.appliesTo(target, w));
 
     if (applicable.isEmpty) {
       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;
   }
 
   /**
    * Create a Serialization for serializing SerializationRules. This is used
    * to save the rules in a self-describing format along with the data.
    * If there are new rule classes created, they will need to be described
    * here.
    */
   Serialization ruleSerialization() {
@@ skipping 43 matching lines @@
     }
     return ifAbsent == null ? null : ifAbsent();
   }
 }
 
 /**
  * An exception class for errors during serialization.
  */
 class SerializationException implements Exception {
   final String message;
-  const SerializationException([this.message]);
-  toString() => "SerializationException($message)";
+  const SerializationException(this.message);
+  String toString() => "SerializationException($message)";
 }