Revert "remove serialization. it's moved to github"

pkg/serialization/lib/src/serialization_rule.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;
+
+// TODO(alanknight): We should have an example and tests for subclassing
+// serialization rule rather than using the hard-coded ClosureToMap rule. And
+// possibly an abstract superclass that's designed to be subclassed that way.
+/**
+ * The abstract superclass for serialization rules.
+ */
+abstract class SerializationRule {
+  /**
+   * Rules belong uniquely to a particular Serialization instance, and can
+   * be identified within it by number.
+   */
+  int _number;
+
+  /**
+   * Rules belong uniquely to a particular Serialization instance, and can
+   * be identified within it by number.
+   */
+  int get number => _number;
+
+  /**
+   * Rules belong uniquely to a particular Serialization instance, and can
+   * be identified within it by number.
+   */
+  void set number(int value) {
+    if (_number != null && _number != value) throw
+        new SerializationException("Rule numbers cannot be changed, once set");
+    _number = value;
+  }
+
+  /**
+   * Return true if this rule applies to this object, in the context
+   * where we're writing it, false otherwise.
+   */
+  bool appliesTo(object, Writer writer);
+
+  /**
+   * This extracts the state from the object, calling [f] for each value
+   * as it is extracted, and returning an object representing the whole
+   * state at the end. The state that results will still have direct
+   * pointers to objects, rather than references.
+   */
+  extractState(object, void f(value), Writer w);
+
+  /**
+   * Allows rules to tell us how they expect to store their state. If this
+   * isn't specified we can also just look at the data to tell.
+   */
+  bool get storesStateAsLists => false;
+  bool get storesStateAsMaps => false;
+  bool get storesStateAsPrimitives => false;
+
+  /**
+   * Given the variables representing the state of an object, flatten it
+   * by turning object pointers into Reference objects where needed. This
+   * destructively modifies the state object.
+   *
+   * This has a default implementation which assumes that object is indexable,
+   * so either conforms to Map or List. Subclasses may override to do something
+   * different, including returning a new state object to be used in place
+   * of the original.
+   */
+  // This has to be a separate operation from extracting, because we extract
+  // as we are traversing the objects, so we don't yet have the objects to
+  // generate references for them. It might be possible to avoid that by
+  // doing a depth-first rather than breadth-first traversal, but I'm not
+  // sure it's worth it.
+  flatten(state, Writer writer) {
+    keysAndValues(state).forEach((key, value) {
+      var reference = writer._referenceFor(value);
+      state[key] = reference;
+    });
+  }
+
+  /** Return true if this rule should only be applied when we are the first
+   * rule found that applies to this object. This may or may not be a hack
+   * that will disappear once we have better support for multiple rules.
+   * We want to have multiple different rules that apply to the same object. We
+   * also want to have multiple different rules that might exclusively apply
+   * to the same object. So, we want either ListRule or ListRuleEssential, and
+   * only one of them can be there. But on the other hand, we may want both
+   * ListRule and BasicRule. So we identify the kinds of rules that can share.
+   * If mustBePrimary returns true, then this rule will only be chosen if no
+   * other rule has been found yet. This means that the ordering of rules in
+   * the serialization is significant, which is unpleasant, but we'll have
+   * to see how bad it is.
+   */
+  // TODO(alanknight): Reconsider whether this should be handled differently.
+  bool get mustBePrimary => false;
+
+  /**
+   * Create the new object corresponding to [state] using the rules
+   * from [reader]. This may involve recursively inflating "essential"
+   * references in the state, which are those that are required for the
+   * object's constructor. It is up to the rule what state is considered
+   * essential.
+   */
+  inflateEssential(state, Reader reader);
+
+  /**
+   * The [object] has already been created. Set any of its non-essential
+   * variables from the representation in [state]. Where there are references
+   * to other objects they are resolved in the context of [reader].
+   */
+  void inflateNonEssential(state, object, Reader reader);
+
+  /**
+   * If we have [object] as part of our state, should we represent that
+   * directly, or should we make a reference for it. By default, true.
+   * This may also delegate to [writer].
+   */
+  bool shouldUseReferenceFor(object, Writer writer) => true;
+
+  /**
+   * Return true if the data this rule returns is variable length, so a
+   * length needs to be written for it if the format requires that. Return
+   * false if the results are always the same length.
+   */
+  bool get hasVariableLengthEntries => true;
+
+  /**
+   * If the data is fixed length, return it here. The format may or may not
+   * make use of this, depending on whether it already has enough information
+   * to determine the length on its own. If [hasVariableLengthEntries] is true
+   * this is ignored.
+   */
+  int get dataLength => 0;
+}
+
+/**
+ * This rule handles things that implement List. It will recreate them as
+ * whatever the default implemenation of List is on the target platform.
+ */
+class ListRule extends SerializationRule {
+
+  bool appliesTo(object, Writer w) => object is List;
+
+  bool get storesStateAsLists => true;
+
+  List extractState(List list, f, Writer w) {
+    var result = new List();
+    for (var each in list) {
+      result.add(each);
+      f(each);
+    }
+    return result;
+  }
+
+  inflateEssential(List state, Reader r) => new List();
+
+  // For a list, we consider all of its state non-essential and add it
+  // after creation.
+  void inflateNonEssential(List state, List newList, Reader r) {
+    populateContents(state, newList, r);
+  }
+
+  void populateContents(List state, List newList, Reader r) {
+    for(var each in state) {
+      newList.add(r.inflateReference(each));
+    }
+  }
+
+  bool get hasVariableLengthEntries => true;
+}
+
+/**
+ * This is a subclass of ListRule where all of the list's contents are
+ * considered essential state. This is needed if an object X contains a List L,
+ * but it expects L's contents to be fixed when X's constructor is called.
+ */
+class ListRuleEssential extends ListRule {
+
+  /** Create the new List and also inflate all of its contents. */
+  inflateEssential(List state, Reader r) {
+    var object = super.inflateEssential(state, r);
+    populateContents(state, object, r);
+    return object;
+  }
+
+  /** Does nothing, because all the work has been done in inflateEssential. */
+  void inflateNonEssential(state, newList, reader) {}
+
+  bool get mustBePrimary => true;
+}
+
+/**
+ * This rule handles things that implement Map. It will recreate them as
+ * whatever the default implemenation of Map is on the target platform. If a
+ * map has string keys it will attempt to retain it as a map for JSON formats,
+ * otherwise it will store it as a list of references to keys and values.
+ */
+class MapRule extends SerializationRule {
+
+  bool appliesTo(object, Writer w) => object is Map;
+
+  bool get storesStateAsMaps => true;
+
+  extractState(Map map, f, Writer w) {
+    // Note that we make a copy here because flattening may be destructive.
+    var newMap = new Map.from(map);
+    newMap.forEach((key, value) {
+      f(key);
+      f(value);
+    });
+    return newMap;
+  }
+
+  /**
+   * Change the keys and values of [state] into references in [writer].
+   * If [state] is a map whose keys are all strings then we leave the keys
+   * as is so that JSON formats will be more readable. If the keys are
+   * arbitrary then we need to turn them into references and replace the
+   * state with a new Map whose keys are the references.
+   */
+  flatten(Map state, Writer writer) {
+    bool keysAreAllStrings = state.keys.every((x) => x is String);
+    if (keysAreAllStrings && !writer.shouldUseReferencesForPrimitives) {
+      keysAndValues(state).forEach(
+          (key, value) => state[key] = writer._referenceFor(value));
+      return state;
+    } else {
+      var newState = [];
+      keysAndValues(state).forEach((key, value) {
+        newState.add(writer._referenceFor(key));
+        newState.add(writer._referenceFor(value));
+      });
+      return newState;
+    }
+  }
+
+  inflateEssential(state, Reader r) => new Map();
+
+  // For a map, we consider all of its state non-essential and add it
+  // after creation.
+  void inflateNonEssential(state, Map newMap, Reader r) {
+    if (state is List) {
+      inflateNonEssentialFromList(state, newMap, r);
+    } else {
+      inflateNonEssentialFromMap(state, newMap, r);
+    }
+  }
+
+  void inflateNonEssentialFromList(List state, Map newMap, Reader r) {
+    var key;
+    for (var each in state) {
+      if (key == null) {
+        key = each;
+      } else {
+        newMap[r.inflateReference(key)] = r.inflateReference(each);
+        key = null;
+      }
+    }
+  }
+
+  void inflateNonEssentialFromMap(Map state, Map newMap, Reader r) {
+    state.forEach((key, value) {
+      newMap[r.inflateReference(key)] = r.inflateReference(value);
+    });
+  }
+
+  bool get hasVariableLengthEntries => true;
+}
+
+/**
+ * This rule handles primitive types, defined as those that we can normally
+ * represent directly in the output format. We hard-code that to mean
+ * num, String, and bool.
+ */
+class PrimitiveRule extends SerializationRule {
+  bool appliesTo(object, Writer w) => isPrimitive(object);
+  extractState(object, Function f, Writer w) => object;
+  flatten(object, Writer writer) {}
+  inflateEssential(state, Reader r) => state;
+  void inflateNonEssential(object, _, Reader r) {}
+
+  bool get storesStateAsPrimitives => true;
+
+  /**
+   * Indicate whether we should save pointers to this object as references
+   * or store the object directly. For primitives this depends on the format,
+   * so we delegate to the writer.
+   */
+  bool shouldUseReferenceFor(object, Writer w) =>
+      w.shouldUseReferencesForPrimitives;
+
+  bool get hasVariableLengthEntries => false;
+}
+
+/** Typedef for the object construction closure used in ClosureRule. */
+typedef ConstructType(Map m);
+
+/** Typedef for the state-getting closure used in ClosureToMapRule. */
+typedef Map<String, dynamic> GetStateType(object);
+
+/** Typedef for the state-setting closure used in ClosureToMapRule. */
+typedef void NonEssentialStateType(object, Map m);
+
+/**
+ * This is a rule where the extraction and creation are hard-coded as
+ * closures. The result is expected to be a map indexed by field name.
+ */
+class ClosureRule extends CustomRule {
+
+  /** The runtimeType of objects that this rule applies to. Used in appliesTo.*/
+  final Type type;
+
+  /** The function for constructing new objects when reading. */
+  final ConstructType construct;
+
+  /** The function for returning an object's state as a Map. */
+  final GetStateType getStateFunction;
+
+  /** The function for setting an object's state from a Map. */
+  final NonEssentialStateType setNonEssentialState;
+
+  /**
+   * Create a ClosureToMapRule for the given [type] which gets an object's
+   * state by calling [getState], creates a new object by calling [construct]
+   * and sets the new object's state by calling [setNonEssentialState].
+   */
+  ClosureRule(this.type, this.getStateFunction, this.construct,
+      this.setNonEssentialState);
+
+  bool appliesTo(object, Writer w) => object.runtimeType == type;
+
+  getState(object) => getStateFunction(object);
+
+  create(state) => construct(state);
+
+  void setState(object, state) {
+    if (setNonEssentialState == null) return;
+    setNonEssentialState(object, state);
+  }
+}
+
+/**
+ * This rule handles things we can't pass directly, but only by reference.
+ * If objects are listed in the namedObjects in the writer or serialization,
+ * it will save the name rather than saving the state.
+ */
+class NamedObjectRule extends SerializationRule {
+  /**
+   * Return true if this rule applies to the object. Checked by looking up
+   * in the namedObjects collection.
+   */
+  bool appliesTo(object, Writer writer) {
+    return writer.hasNameFor(object);
+  }
+
+  /** Extract the state of the named objects as just the object itself. */
+  extractState(object, Function f, Writer writer) {
+    var result = [nameFor(object, writer)];
+    f(result.first);
+    return result;
+  }
+
+  /** When we flatten the state we save it as the name. */
+  // TODO(alanknight): This seems questionable. In a truly flat format we may
+  // want to have extracted the name as a string first and flatten it into a
+  // reference to that. But that requires adding the Writer as a parameter to
+  // extractState, and I'm reluctant to add yet another parameter until
+  // proven necessary.
+  flatten(state, Writer writer) {
+    state[0] = writer._referenceFor(state[0]);
+  }
+
+  /** Look up the named object and return it. */
+  inflateEssential(state, Reader r) =>
+      r.objectNamed(r.resolveReference(state.first));
+
+  /** Set any non-essential state on the object. For this rule, a no-op. */
+  void inflateNonEssential(state, object, Reader r) {}
+
+  /** Return the name for this object in the Writer. */
+  String nameFor(object, Writer writer) => writer.nameFor(object);
+}
+
+/**
+ * This rule handles the special case of Mirrors. It stores the mirror by its
+ * qualifiedName and attempts to look it up in both the namedObjects
+ * collection, or if it's not found there, by looking it up in the mirror
+ * system. When reading, the user is responsible for supplying the appropriate
+ * values in [Serialization.namedObjects] or in the [externals] paramter to
+ * [Serialization.read].
+ */
+class MirrorRule extends NamedObjectRule {
+  bool appliesTo(object, Writer writer) => object is DeclarationMirror;
+
+  String nameFor(DeclarationMirror object, Writer writer) =>
+      MirrorSystem.getName(object.qualifiedName);
+
+  inflateEssential(state, Reader r) {
+    var qualifiedName = r.resolveReference(state.first);
+    var lookupFull = r.objectNamed(qualifiedName, (x) => null);
+    if (lookupFull != null) return lookupFull;
+    var separatorIndex = qualifiedName.lastIndexOf(".");
+    var type = qualifiedName.substring(separatorIndex + 1);
+    var lookup = r.objectNamed(type, (x) => null);
+    if (lookup != null) return lookup;
+    var name = qualifiedName.substring(0, separatorIndex);
+    // This is very ugly. The library name for an unnamed library is its URI.
+    // That can't be constructed as a Symbol, so we can't use findLibrary.
+    // So follow one or the other path depending if it has a colon, which we
+    // assume is in any URI and can't be in a Symbol.
+    if (name.contains(":")) {
+      var uri = Uri.parse(name);
+      var libMirror = currentMirrorSystem().libraries[uri];
+      var candidate = libMirror.declarations[new Symbol(type)];
+      return candidate is ClassMirror ? candidate : null;
+    } else {
+      var symbol = new Symbol(name);
+      var typeSymbol = new Symbol(type);
+      for (var libMirror in currentMirrorSystem().libraries.values) {
+        if (libMirror.simpleName != symbol) continue;
+        var candidate = libMirror.declarations[typeSymbol];
+        if (candidate != null && candidate is ClassMirror) return candidate;
+      }
+      return null;
+    }
+  }
+}
+
+/**
+ * This provides an abstract superclass for writing your own rules specific to
+ * a class. It makes some assumptions about behaviour, and so can have a
+ * simpler set of methods that need to be implemented in order to subclass it.
+ *
+ */
+abstract class CustomRule extends SerializationRule {
+  // TODO(alanknight): It would be nice if we could provide an implementation
+  // of appliesTo() here. If we add a type parameter to these classes
+  // we can "is" test against it, but we need to be able to rule out subclasses.
+  // => instance.runtimeType == T
+  // should work.
+  /**
+   * Return true if this rule applies to this object, in the context
+   * where we're writing it, false otherwise.
+   */
+  bool appliesTo(instance, Writer w);
+
+  /**
+   * Subclasses should implement this to return a list of the important fields
+   * in the object. The order of the fields doesn't matter, except that the
+   * create and setState methods need to know how to use it.
+   */
+  List getState(instance);
+
+  /**
+   * Given a [List] of the object's [state], re-create the object. This should
+   * do the minimum needed to create the object, just calling the constructor.
+   * Setting the remaining state of the object should be done in the [setState]
+   * method, which will be called only once all the objects are created, so
+   * it won't cause problems with cycles.
+   */
+  create(List state);
+
+  /**
+   * Set any state in [object] which wasn't set in the constructor. Between
+   * this method and [create] all of the information in [state] should be set
+   * in the new object.
+   */
+  void setState(object, List state);
+
+  extractState(instance, Function f, Writer w) {
+    var state = getState(instance);
+    for (var each in values(state)) {
+      f(each);
+    }
+    return state;
+  }
+
+  inflateEssential(state, Reader r) => create(_lazy(state, r));
+
+  void inflateNonEssential(state, object, Reader r) {
+    setState(object, _lazy(state, r));
+  }
+
+  // We don't want to have to make the end user tell us how long the list is
+  // separately, so write it out for each object, even though they're all
+  // expected to be the same length.
+  bool get hasVariableLengthEntries => true;
+}
+
+/** A hard-coded rule for serializing Symbols. */
+class SymbolRule extends CustomRule {
+  bool appliesTo(instance, _) => instance is Symbol;
+  getState(instance) => [MirrorSystem.getName(instance)];
+  create(state) => new Symbol(state[0]);
+  void setState(symbol, state) {}
+  int get dataLength => 1;
+  bool get hasVariableLengthEntries => false;
+}
+
+/** A hard-coded rule for DateTime. */
+class DateTimeRule extends CustomRule {
+  bool appliesTo(instance, _) => instance is DateTime;
+  List getState(DateTime date) => [date.millisecondsSinceEpoch, date.isUtc];
+  DateTime create(List state) =>
+      new DateTime.fromMillisecondsSinceEpoch(state[0], isUtc: state[1]);
+  void setState(date, state) {}
+  // Let the system know we don't have to store a length for these.
+  int get dataLength => 2;
+  bool get hasVariableLengthEntries => false;
+}
+
+/** Create a lazy list/map that will inflate its items on demand in [r]. */
+_lazy(l, Reader r) {
+  if (l is List) return new _LazyList(l, r);
+  if (l is Map) return new _LazyMap(l, r);
+  throw new SerializationException("Invalid type: must be Map or List - $l");
+}
+
+/**
+ * This provides an implementation of Map that wraps a list which may
+ * contain references to (potentially) non-inflated objects. If these
+ * are accessed it will inflate them. This allows us to pass something that
+ * looks like it's just a list of objects to a [CustomRule] without needing
+ * to inflate all the references in advance.
+ */
+class _LazyMap implements Map {
+  _LazyMap(this._raw, this._reader);
+
+  final Map _raw;
+  final Reader _reader;
+
+  // This is the only operation that really matters.
+  operator [](x) => _reader.inflateReference(_raw[x]);
+
+  int get length => _raw.length;
+  bool get isEmpty => _raw.isEmpty;
+  bool get isNotEmpty => _raw.isNotEmpty;
+  Iterable get keys => _raw.keys;
+  bool containsKey(x) => _raw.containsKey(x);
+
+  // These operations will work, but may be expensive, and are probably
+  // best avoided.
+  get _inflated => mapValues(_raw, _reader.inflateReference);
+  bool containsValue(x) => _inflated.containsValue(x);
+  Iterable get values => _inflated.values;
+  void forEach(f) => _inflated.forEach(f);
+
+  // These operations are all invalid
+  _throw() {
+    throw new UnsupportedError("Not modifiable");
+  }
+  operator []=(x, y) => _throw();
+  putIfAbsent(x, y) => _throw();
+  bool remove(x) => _throw();
+  void clear() => _throw();
+  void addAll(Map other) => _throw();
+}
+
+/**
+ * This provides an implementation of List that wraps a list which may
+ * contain references to (potentially) non-inflated objects. If these
+ * are accessed it will inflate them. This allows us to pass something that
+ * looks like it's just a list of objects to a [CustomRule] without needing
+ * to inflate all the references in advance.
+ */
+class _LazyList extends ListBase {
+  _LazyList(this._raw, this._reader);
+
+  final List _raw;
+  final Reader _reader;
+
+  operator [](int x) => _reader.inflateReference(_raw[x]);
+  int get length => _raw.length;
+
+  void set length(int value) => _throw();
+
+  void operator []=(int index, value) => _throw();
+
+  void _throw() {
+    throw new UnsupportedError("Not modifiable");
+  }
+}