remove serialization. it's moved to github

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.
-
-/**
- * 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.
- *
- * For information on installing and importing this library, see the
- * [serialization package on pub.dartlang.org]
- * (http://pub.dartlang.org/packages/serialization).
- *
- * ## Setup
- *
- * A simple example of usage is
- *
- *      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.
- * 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
- * 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",
- *            constructorFields: ["number", "street"],
- *            fields: ["city"]);
- *
- * This rule still uses reflection to access the fields, but does not try to
- * identify which fields to use, but instead uses only the "number" and "street"
- * fields that we specified. We may also want to tell it to identify the
- * fields, but to specifically omit certain fields that we don't want
- * serialized.
- *
- *      var serialization = new Serialization()
- *        ..addRuleFor(Address,
- *            constructor: "",
- *            excludeFields: ["other", "stuff"]);
- *
- * ## Writing rules
- *
- * We can also use a completely non-reflective rule to serialize and
- * de-serialize objects. This can be more work, but it does work in
- * dart2js, where mirrors are not yet implemented. We can specify this in two
- * ways. First, we can write our own SerializationRule class that has methods
- * for our Address class.
- *
- *      class AddressRule extends CustomRule {
- *        bool appliesTo(instance, Writer w) => instance.runtimeType == Address;
- *        getState(instance) => [instance.street, instance.city];
- *        create(state) => new Address();
- *        setState(Address a, List state) {
- *          a.street = state[0];
- *          a.city = state[1];
- *        }
- *      }
- *
- * The class needs four different methods. The [CustomRule.appliesTo]
- * method tells us if
- * the rule should be used to write an object. In this example we use a test
- * based on runtimeType. We could also use an "is Address" test, but if Address
- * has subclasses that would find those as well, and we want a separate rule
- * for each. The [CustomRule.getState] method should
- * return all the state of the object that we want to recreate,
- * and should be either a Map or a List. If you want to write to human-readable
- * formats where it's useful to be able to look at the data as a map from
- * field names to values, then it's better to return it as a map. Otherwise it's
- * more efficient to return it as a list. You just need to be sure that the
- * [CustomRule.create] and [CustomRule.setState] methods interpret the data the
- * same way as [CustomRule.getState] does.
- *
- * The [CustomRule.create] method will create the new object and return it. While it's
- * possible to create the object and set all its state in this one method, that
- * increases the likelihood of problems with cycles. So it's better to use the
- * minimum necessary information in [CustomRule.create] and do more of the work
- * in [CustomRule.setState].
- *
- * The other way to do this is not creating a subclass, but by using a
- * [ClosureRule] and giving it functions for how to create
- * the address.
- *
- *      addressToMap(a) => {"number" : a.number, "street" : a.street,
- *          "city" : a.city};
- *      createAddress(Map m) => new Address.create(m["number"], m["street"]);
- *      fillInAddress(Address a, Map m) => a.city = m["city"];
- *      var serialization = new Serialization()
- *        ..addRule(
- *            new ClosureRule(anAddress.runtimeType,
- *                addressToMap, createAddress, fillInAddress);
- *
- * In this case we have created standalone functions rather than
- * methods in a subclass and we pass them to the constructor of
- * [ClosureRule]. In this case we've also had them use maps rather than
- * lists for the state, but either would work as long as the rule is
- * consistent with the representation it uses. We pass it the runtimeType
- * of the object, and functions equivalent to the methods on [CustomRule]
- *
- * ## Constant values
- *
- * There are cases where the constructor needs values that we can't easily get
- * from the serialized object. For example, we may just want to pass null, or a
- * constant value. To support this, we can specify as constructor fields
- * values that aren't field names. If any value isn't a String, or is a string
- * that doesn't correspond to a field name, it will be
- * treated as a constant and passed unaltered to the constructor.
- *
- * In some cases a non-constructor field should not be set using field
- * access or a setter, but should be done by calling a method. For example, it
- * may not be possible to set a List field "foo", and you need to call an
- * addFoo() method for each entry in the list. In these cases, if you are using
- * a BasicRule for the object you can call the setFieldWith() method.
- *
- *       s..addRuleFor(FooHolder).setFieldWith("foo",
- *           (parent, value) => for (var each in value) parent.addFoo(value));
- *
- * ## 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
- * 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());
- *      List output = serialization.write(address, new SimpleFlatFormat());
- *      var output = serialization.write(address, new SimpleJsonFormat());
- * Or, using a [Writer] explicitly
- *      var writer = serialization.newWriter(new SimpleFlatFormat());
- *      List output = writer.write(address);
- *
- * These representations are not yet considered stable.
- *
- * ## Reading
- *
- * To read objects, the corresponding [Serialization.read] method can be used.
- *
- *       Address input = serialization.read(input);
- *
- * When reading, the serialization instance doing the reading must be configured
- * with compatible rules to the one doing the writing. It's possible for the
- * rules to be different, but they need to be able to read the same
- * representation. For most practical purposes right now they should be the
- * same. The simplest way to achieve this is by having the serialization
- * variable [Serialization.selfDescribing] be true. In that case the rules
- * themselves are also
- * stored along with the serialized data, and can be read back on the receiving
- * end. Note that this may not work for all rules or all formats. The
- * [Serialization.selfDescribing] variable is true by default, but the
- * [SimpleJsonFormat] does not support it, since the point is to provide a
- * representation in a form
- * other services might expect. Using CustomRule or ClosureRule also does not
- * yet work with the [Serialization.selfDescribing] variable.
- *
- * ## Named objects
- *
- * When reading, some object references should not be serialized, but should be
- * connected up to other instances on the receiving side. A notable example of
- * this is when serialization rules have been stored. Instances of BasicRule
- * take a [ClassMirror] in their constructor, and we cannot serialize those. So
- * when we read the rules, we must provide a Map<String, Object> which maps from
- * the simple name of classes we are interested in to a [ClassMirror]. This can
- * be provided either in the [Serialization.namedObjects],
- * or as an additional parameter to the reading and writing methods on the
- * [Reader] or [Writer] respectively.
- *
- *     new Serialization()
- *       ..addRuleFor(Person, constructorFields: ["name"])
- *       ..namedObjects['Person'] = reflect(new Person()).type;
- */
-library serialization;
-
-import 'src/mirrors_helpers.dart';
-import 'src/serialization_helpers.dart';
-import 'dart:collection';
-
-part 'src/reader_writer.dart';
-part 'src/serialization_rule.dart';
-part 'src/basic_rule.dart';
-part 'src/format.dart';
-
-/**
- * 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 {
-  final List<SerializationRule> _rules;
-
-  /**
-   * The serialization is controlled by the list of Serialization rules. These
-   * are most commonly added via [addRuleFor].
-   */
-  final UnmodifiableListView<SerializationRule> 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> namedObjects = {};
-
-  /**
-   * 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 _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 {
-    // TODO(alanknight): Should this be moved to the format?
-    // TODO(alanknight): Allow self-describing in the presence of CustomRule.
-    // TODO(alanknight): Don't do duplicate work creating a writer and
-    // serialization here and then re-creating when we actually serialize.
-    if (_selfDescribing != null) return _selfDescribing;
-    var meta = ruleSerialization();
-    var w = meta.newWriter();
-    _selfDescribing = !rules.any((rule) =>
-        meta.rulesFor(rule, w, create: false).isEmpty);
-    return _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.
-   */
-  void set selfDescribing(bool value) {
-    _selfDescribing = value;
-  }
-
-  /**
-   * Creates a new serialization with a default set of rules for primitives
-   * and lists.
-   */
-  factory Serialization() =>
-    new Serialization.blank()
-      ..addDefaultRules();
-
-  /**
-   * Creates a new serialization with no default rules at all. The most common
-   * use for this is if we are reading self-describing serialized data and
-   * will populate the rules from that data.
-   */
-  factory Serialization.blank()
-    => new Serialization._(new List<SerializationRule>());
-
-  Serialization._(List<SerializationRule> rules) :
-    this._rules = rules,
-    this.rules = new UnmodifiableListView(rules);
-
-  /**
-   * Create a [BasicRule] rule for [instanceOrType]. Normally this will be
-   * a type, but for backward compatibilty we also allow you to pass an
-   * instance (except an instance of Type), and the rule will be created
-   * for its runtimeType. Optionally
-   * allows specifying a [constructor] name, the list of [constructorFields],
-   * and the list of [fields] not used in the constructor. Returns the new
-   * rule. Note that [BasicRule] uses reflection, and so will not work with the
-   * current state of dartj2s. If you need to run there, consider using
-   * [CustomRule] instead.
-   *
-   * If the optional parameters aren't specified, the default constructor will
-   * be used, and the list of fields will be computed. Alternatively, you can
-   * omit [fields] and provide [excludeFields], which will then compute the
-   * list of fields specifically excluding those listed.
-   *
-   * The fields can be actual public fields, but can also be getter/setter
-   * pairs or getters whose value is provided in the constructor. For the
-   * [constructorFields] they can also be arbitrary objects. Anything that is
-   * not a String will be treated as a constant value to be used in any
-   * construction of these objects.
-   *
-   * If the list of fields is computed, fields from the superclass will be
-   * included. However, each subclass needs its own rule, since the constructors
-   * are not inherited, and so may need to be specified separately for each
-   * subclass.
-   */
-  BasicRule addRuleFor(
-      instanceOrType,
-      {String constructor,
-        List constructorFields,
-        List<String> fields,
-        List<String> excludeFields}) {
-
-    var rule = new BasicRule(
-        turnInstanceIntoSomethingWeCanUse(
-            instanceOrType),
-        constructor, constructorFields, fields, excludeFields);
-    addRule(rule);
-    return rule;
-  }
-
-  /** Set up the default rules, for lists and primitives. */
-  void addDefaultRules() {
-    addRule(new PrimitiveRule());
-    addRule(new ListRule());
-    // Both these rules apply to lists, so unless otherwise indicated,
-    // it will always find the first one.
-    addRule(new ListRuleEssential());
-    addRule(new MapRule());
-    addRule(new SymbolRule());
-    addRule(new DateTimeRule());
-  }
-
-  /**
-   * 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);
-  }
-
-  /**
-   * 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 is [SimpleMapFormat] and returns a Map.
-   */
-  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);
-
-  /**
-   * 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 is [SimpleMapFormat] and expects a Map as input.
-   * 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, {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);
-
-  /**
-   * Return the list of SerializationRule that apply to [object]. For
-   * internal use, but public because it's used in testing.
-   */
-  Iterable<SerializationRule> rulesFor(object, Writer w, {create : true}) {
-    // 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);
-    } else {
-      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;
-    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');
-    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() {
-    // 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.
-
-    var meta = new Serialization()
-      ..selfDescribing = false
-      ..addRuleFor(ListRule)
-      ..addRuleFor(MapRule)
-      ..addRuleFor(PrimitiveRule)
-      ..addRuleFor(ListRuleEssential)
-      ..addRuleFor(BasicRule,
-          constructorFields: ['type',
-            'constructorName',
-            'constructorFields', 'regularFields', []],
-          fields: [])
-      ..addRule(new NamedObjectRule())
-      ..addRule(new MirrorRule())
-      ..addRuleFor(MirrorRule)
-      ..addRuleFor(SymbolRule)
-      ..addRuleFor(DateTimeRule);
-    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);
-  String toString() => "SerializationException($message)";
-}