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

pkg/serialization/lib/src/basic_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): Figure out how to reasonably separate out the things
+// that require reflection without making the API more awkward. Or if that is
+// in fact necessary. Maybe the tree-shaking will just remove it if unused.
+
+/**
+ * This is the basic rule for handling "normal" objects, which have a list of
+ * fields and a constructor, as opposed to simple types or collections. It uses
+ * mirrors to access the state, and can also use them to figure out the list
+ * of fields and the constructor if it's not provided.
+ *
+ * If you call [Serialization.addRule], this is what you get.
+ *
+ */
+class BasicRule extends SerializationRule {
+  /**
+   * The [type] is used both to find fields and to verify if the object is one
+   * that we handle.
+   */
+  final ClassMirror type;
+
+  /** Used to create new objects when reading. */
+  final Constructor constructor;
+
+  /** This holds onto our list of fields, and can also calculate them. */
+  final _FieldList _fields;
+
+  /**
+   * Instances can either use maps or lists to hold the object's state. The list
+   * representation is much more compact and used by default. The map
+   * representation is more human-readable. The default is to use lists.
+   */
+  bool useMaps = false;
+
+  // TODO(alanknight) Change the type parameter once we have class literals.
+  // Issue 6282.
+  // TODO(alanknight) Does the comment for this format properly?
+  /**
+   * Create this rule. Right now the user is obliged to pass a ClassMirror,
+   * but once we allow class literals (Issue 6282) it will support that. The
+   * other parameters can all be left as null, and are optional on the
+   * [Serialization.addRule] method which is the normal caller for this.
+   * [constructorName] is the constructor, if not the default.
+   * [constructorFields] are the fields required to call the constructor, which
+   *   is the essential state. They don't have to be actual fields,
+   *   getter/setter pairs or getter/constructor pairs are fine. Note that
+   *   the constructorFields do not need to be strings, they can be arbitrary
+   *   values. For non-strings, these will be treated as constant values to be
+   *   used instead of data read from the objects.
+   * [regularFields] are the non-essential fields. They don't have to be actual
+   *   fields, getter/setter pairs are fine. If this is null, it's assumed
+   *   that we should figure them out.
+   * [excludeFields] lets you tell it to find the fields automatically, but
+   *   omit some that would otherwise be included.
+   */
+  factory BasicRule(ClassMirror type, String constructorName,
+      List constructorFields, List regularFields, List excludeFields) {
+
+    var fields = new _FieldList(type);
+    fields.constructorFields = constructorFields;
+    fields.regular = regularFields;
+    // TODO(alanknight): The order of this matters. It shouldn't.
+    fields.exclude = excludeFields;
+    fields.figureOutFields();
+
+    var constructor = new Constructor(type, constructorName,
+        fields.constructorFieldIndices());
+
+    return new BasicRule._(type, constructor, fields);
+  }
+
+  BasicRule._(this.type, this.constructor, this._fields) {
+    configureForLists();
+  }
+
+  /**
+   * Sometimes it's necessary to treat fields of an object differently, based
+   * on the containing object. For example, by default a list treats its
+   * contents as non-essential state, so it will be populated only after all
+   * objects have been created. An object may have a list which is used in its
+   * constructor and must be fully created before the owning object can be
+   * created. Alternatively, it may not be possible to set a field directly,
+   * and some other method must be called to set it, perhaps calling a method
+   * on the owning object to add each individual element.
+   *
+   * This method lets you designate a function to use to set the value of a
+   * field. It also makes the contents of that field be treated as essential,
+   * which currently only has meaning if the field is a list. This is done
+   * because you might set a list field's special treatment function to add
+   * each item individually and that will only work if those objects already
+   * exist.
+   *
+   * For example, to serialize a Serialization, we need its rules to be
+   * individually added rather than just setting the rules field.
+   *      ..addRuleFor(Serialization).setFieldWith('rules',
+   *          (InstanceMirror s, List rules) {
+   *            rules.forEach((x) => s.reflectee.addRule(x));
+   * Note that the function is passed the owning object as well as the field
+   * value, but that it is passed as a mirror.
+   */
+  void setFieldWith(String fieldName, SetWithFunction setWith) {
+    _fields.addAllByName([fieldName]);
+    _NamedField field = _fields.named(_asSymbol(fieldName));
+    Function setter = (setWith == null) ? field.defaultSetter : setWith;
+    field.customSetter = setter;
+  }
+
+  /** Return the name of the constructor used to create new instances on read.*/
+  String get constructorName => constructor.name;
+
+  /** Return the list of field names to be passed to the constructor.*/
+  List<String> get constructorFields => _fields.constructorFieldNames();
+
+  /** Return the list of field names not used in the constructor. */
+  List<String> get regularFields => _fields.regularFieldNames();
+
+  String toString() => "Basic Rule for ${type.simpleName}";
+
+  /**
+   * Configure this instance to use maps by field name as its output.
+   * Instances can either produce maps or lists. The list representation
+   * is much more compact and used by default. The map representation is
+   * much easier to debug. The default is to use lists.
+   */
+  void configureForMaps() {
+    useMaps = true;
+  }
+
+  /**
+   * Configure this instance to use lists accessing fields by index as its
+   * output. Instances can either produce maps or lists. The list representation
+   * is much more compact and used by default. The map representation is
+   * much easier to debug. The default is to use lists.
+   */
+  void configureForLists() {
+    useMaps = false;
+  }
+
+  /**
+   * Create either a list or a map to hold the object's state, depending
+   * on the [useMaps] variable. If using a Map, we wrap it in order to keep
+   * the protocol compatible. See [configureForLists]/[configureForMaps].
+   *
+   * If a list is returned, it is growable.
+   */
+   createStateHolder() {
+     if (useMaps) return new _MapWrapper(_fields.contents);
+     List list = [];
+     list.length = _fields.length;
+     return list;
+   }
+
+  /**
+   * Wrap the state if it's passed in as a map, and if the keys are references,
+   * resolve them to the strings we expect. We leave the previous keys in there
+   * as well, as they shouldn't be harmful, and it costs more to remove them.
+   */
+   makeIndexableByNumber(state) {
+     if (!(state is Map)) return state;
+     // TODO(alanknight): This is quite inefficient, and we do it twice per
+     // instance. If the keys are references, we need to turn them into strings
+     // before we can look at indexing them by field position. It's also eager,
+     // but we know our keys are always primitives, so we don't have to worry
+     // about their instances not having been created yet.
+     var newState = new Map();
+     for (var each in state.keys) {
+       var newKey = (each is Reference) ? each.inflated() : each;
+       newState[newKey] = state[each];
+     }
+     return new _MapWrapper.fromMap(newState, _fields.contents);
+   }
+
+  /**
+   * Extract the state from [object] using an instanceMirror and the field
+   * names in [_fields]. Call the function [callback] on each value.
+   */
+  extractState(object, Function callback, Writer w) {
+    var result = createStateHolder();
+    var mirror = reflect(object);
+
+    keysAndValues(_fields).forEach(
+        (index, field) {
+          var value = _value(mirror, field);
+          callback(field.name);
+          callback(checkForEssentialLists(index, value));
+          result[index] = value;
+        });
+    return _unwrap(result);
+  }
+
+  flatten(state, Writer writer) {
+    if (state is List) {
+      keysAndValues(state).forEach((index, value) {
+        state[index] = writer._referenceFor(value);
+      });
+    } else {
+      var newState = new Map();
+      keysAndValues(state).forEach((key, value) {
+        newState[writer._referenceFor(key)] = writer._referenceFor(value);
+      });
+      return newState;
+    }
+  }
+
+  /**
+   * If the value is a List, and the field is a constructor field or
+   * otherwise specially designated, we wrap it in something that indicates
+   * a restriction on the rules that can be used. Which in this case amounts
+   * to designating the rule, since we so far only have one rule per object.
+   */
+  checkForEssentialLists(index, value) {
+    if (value is List && _fields.contents[index].isEssential) {
+      return new DesignatedRuleForObject(value,
+          (SerializationRule rule) => rule is ListRuleEssential);
+    } else {
+      return value;
+    }
+  }
+
+  /** Remove any MapWrapper from the extracted state. */
+  _unwrap(result) => (result is _MapWrapper) ? result.asMap() : result;
+
+  /**
+   * Call the designated constructor with the appropriate fields from [state],
+   * first resolving references in the context of [reader].
+   */
+  inflateEssential(state, Reader reader) {
+    InstanceMirror mirror = constructor.constructFrom(
+        makeIndexableByNumber(state), reader);
+    return mirror.reflectee;
+  }
+
+  /** For all [rawState] not required in the constructor, set it in the
+   * [object], resolving references in the context of [reader].
+   */
+  inflateNonEssential(rawState, object, Reader reader) {
+    InstanceMirror mirror = reflect(object);
+    var state = makeIndexableByNumber(rawState);
+    _fields.forEachRegularField( (_Field field) {
+      var value = reader.inflateReference(state[field.index]);
+      field.setValue(mirror, value);
+    });
+  }
+
+  /**
+   * Determine if this rule applies to the object in question. In our case
+   * this is true if the type mirrors are the same.
+   */
+  // TODO(alanknight): This seems likely to be slow. Verify. Other options?
+  bool appliesTo(object, Writer w) => reflect(object).type == type;
+
+  bool get hasVariableLengthEntries => false;
+
+  int get dataLength => _fields.length;
+
+  /**
+   * Extract the value of [field] from the object reflected
+   * by [mirror].
+   */
+  // TODO(alanknight): The framework should be resilient if there are fields
+  // it expects that are missing, either for the case of de-serializing to a
+  // different definition, or for the case that tree-shaking has removed state.
+  // TODO(alanknight): This, and other places, rely on synchronous access to
+  // mirrors. Should be changed to use a synchronous API once one is available,
+  // or to be async, but that would be extremely ugly.
+  _value(InstanceMirror mirror, _Field field) => field.valueIn(mirror);
+}
+
+/**
+ * This represents a field in an object. It is intended to be used as part of
+ * a [_FieldList].
+ */
+abstract class _Field implements Comparable<_Field> {
+
+  /** The FieldList that contains us. */
+  final _FieldList fieldList;
+
+  /**
+   * Our position in the [fieldList._contents] collection. This is used
+   * to index into the state, so it's extremely important.
+   */
+  int index;
+
+  /** Is this field used in the constructor? */
+  bool usedInConstructor = false;
+
+  /**
+   * Create a new [_Field] instance. This will be either a [_NamedField] or a
+   * [_ConstantField] depending on whether or not [value] corresponds to a
+   * field in the class which [fieldList] models.
+   */
+  factory _Field(value, _FieldList fieldList) {
+    if (_isReallyAField(value, fieldList)) {
+      return new _NamedField._internal(value, fieldList);
+    } else {
+      return new _ConstantField._internal(value, fieldList);
+    }
+  }
+
+  /**
+   * Determine if [value] represents a field or getter in the class that
+   * [fieldList] models.
+   */
+  static bool _isReallyAField(value, _FieldList fieldList) {
+    var symbol = _asSymbol(value);
+    return hasField(symbol, fieldList.mirror) ||
+        hasGetter(symbol, fieldList.mirror);
+  }
+
+  /** Private constructor. */
+  _Field._internal(this.fieldList);
+
+  /**
+   * Extracts the value for the field that this represents from the instance
+   * mirrored by [mirror] and return it.
+   */
+  valueIn(InstanceMirror mirror);
+
+  // TODO(alanknight): Is this the right name, or is it confusing that essential
+  // is not the inverse of regular.
+  /** Return true if this is field is not used in the constructor. */
+  bool get isRegular => !usedInConstructor;
+
+  /**
+   * Return true if this field is treated as essential state, either because
+   * it is used in the constructor, or because it's been designated
+   * using [BasicRule.setFieldWith].
+   */
+  bool get isEssential => usedInConstructor;
+
+  /** Set the [value] of our field in the given mirrored [object]. */
+  void setValue(InstanceMirror object, value);
+
+  // Because [x] may not be a named field, we compare the toString. We don't
+  // care that much where constants come in the sort order as long as it's
+  // consistent.
+  int compareTo(_Field x) => toString().compareTo(x.toString());
+}
+
+/**
+ * This represents a field in the object, either stored as a field or
+ * accessed via getter/setter/constructor parameter. It has a name and
+ * will attempt to access the state for that name using an [InstanceMirror].
+ */
+class _NamedField extends _Field {
+  /** The name of the field (or getter) */
+  String _name;
+  Symbol nameSymbol;
+
+  /**
+   * If this is set, then it is used as a way to set the value rather than
+   * using the default mechanism.
+   */
+  Function customSetter;
+
+  _NamedField._internal(fieldName, fieldList) : super._internal(fieldList) {
+    nameSymbol = _asSymbol(fieldName);
+    if (nameSymbol == null) {
+      throw new SerializationException("Invalid field name $fieldName");
+    }
+  }
+
+  String get name =>
+      _name == null ? _name = MirrorSystem.getName(nameSymbol) : _name;
+
+  operator ==(x) => x is _NamedField && (nameSymbol == x.nameSymbol);
+  int get hashCode => name.hashCode;
+
+  /**
+   * Return true if this field is treated as essential state, either because
+   * it is used in the constructor, or because it's been designated
+   * using [BasicRule.setFieldWith].
+   */
+  bool get isEssential => super.isEssential || customSetter != null;
+
+  /** Set the [value] of our field in the given mirrored [object]. */
+  void setValue(InstanceMirror object, value) {
+    setter(object, value);
+  }
+
+  valueIn(InstanceMirror mirror) => mirror.getField(nameSymbol).reflectee;
+
+  /** Return the function to use to set our value. */
+  Function get setter =>
+      (customSetter != null) ? customSetter : defaultSetter;
+
+  /** The default setter function. */
+  void defaultSetter(InstanceMirror object, value) {
+    object.setField(nameSymbol, value);
+  }
+
+  String toString() => 'Field($name)';
+}
+
+/**
+ * This represents a constant value that will be passed as a constructor
+ * parameter. Rather than having a name it has a constant value.
+ */
+class _ConstantField extends _Field {
+
+  /** The value we always return.*/
+  final value;
+
+  _ConstantField._internal(this.value, fieldList) : super._internal(fieldList);
+
+  operator ==(x) => x is _ConstantField && (value == x.value);
+  int get hashCode => value.hashCode;
+  String toString() => 'ConstantField($value)';
+  valueIn(InstanceMirror mirror) => value;
+
+  /** We cannot be set, so setValue is a no-op. */
+  void setValue(InstanceMirror object, value) {}
+
+  /** There are places where the code expects us to have an identifier, so
+   * use the value for that.
+   */
+  get name => value;
+}
+
+/**
+ * The organization of fields in an object can be reasonably complex, so they
+ * are kept in a separate object, which also has the ability to compute the
+ * default fields to use reflectively.
+ */
+class _FieldList extends IterableBase<_Field> {
+  /**
+   * All of our fields, indexed by name. Note that the names are
+   * typically Symbols, but can also be arbitrary constants.
+   */
+  Map<dynamic, _Field> allFields = new Map<dynamic, _Field>();
+
+  /**
+   * The fields which are used in the constructor. The fields themselves also
+   * know if they are constructor fields or not, but we need to keep this
+   * information here because the order matters.
+   */
+  List _constructorFields = const [];
+
+  /** The list of fields to exclude if we are computing the list ourselves. */
+  List<Symbol> _excludedFieldNames = const [];
+
+  /** The mirror we will use to compute the fields. */
+  final ClassMirror mirror;
+
+  /** Cached, sorted list of fields. */
+  List<_Field> _contents;
+
+  /** Should we compute the fields or just use whatever we were given. */
+  bool _shouldFigureOutFields = true;
+
+  _FieldList(this.mirror);
+
+  /** Look up a field by [name]. */
+  _Field named(name) => allFields[name];
+
+  /** Set the fields to be used in the constructor. */
+  set constructorFields(List fieldNames) {
+    if (fieldNames == null || fieldNames.isEmpty) return;
+    _constructorFields = [];
+    for (var each in fieldNames) {
+      var symbol = _asSymbol(each);
+      var name = _Field._isReallyAField(symbol, this) ? symbol : each;
+      var field = new _Field(name, this)..usedInConstructor = true;
+      allFields[name] = field;
+      _constructorFields.add(field);
+    }
+    invalidate();
+  }
+
+  /** Set the fields that aren't used in the constructor. */
+  set regular(List<String> fields) {
+    if (fields == null) return;
+    _shouldFigureOutFields = false;
+    addAllByName(fields);
+  }
+
+  /** Set the fields to be excluded. This is mutually exclusive with setting
+   * the regular fields.
+   */
+  set exclude(List<String> fields) {
+    // TODO(alanknight): This isn't well tested.
+    if (fields == null || fields.isEmpty) return;
+    if (allFields.length > _constructorFields.length) {
+      throw "You can't specify both excludeFields and regular fields";
+    }
+    _excludedFieldNames = fields.map((x) => new Symbol(x)).toList();
+  }
+
+  int get length => allFields.length;
+
+  /** Add all the fields which aren't on the exclude list. */
+  void addAllNotExplicitlyExcluded(Iterable<String> aCollection) {
+    if (aCollection == null) return;
+    var names = aCollection;
+    names = names.where((x) => !_excludedFieldNames.contains(x));
+    addAllByName(names);
+  }
+
+  /** Add all the fields with the given names without any special properties. */
+  void addAllByName(Iterable<String> names) {
+    for (var each in names) {
+      var symbol = _asSymbol(each);
+      var field = new _Field(symbol, this);
+      allFields.putIfAbsent(symbol, () => new _Field(symbol, this));
+    }
+    invalidate();
+  }
+
+  /**
+   * Fields have been added. In case we had already forced calculation of the
+   * list of contents, re-set it.
+   */
+  void invalidate() {
+    _contents = null;
+    contents;
+  }
+
+  Iterator<_Field> get iterator => contents.iterator;
+
+  /** Return a cached, sorted list of all the fields. */
+  List<_Field> get contents {
+    if (_contents == null) {
+      _contents = allFields.values.toList()..sort();
+      for (var i = 0; i < _contents.length; i++)
+        _contents[i].index = i;
+    }
+    return _contents;
+  }
+
+  /** Iterate over the regular fields, i.e. those not used in the constructor.*/
+  void forEachRegularField(Function f) {
+    for (var each in contents) {
+      if (each.isRegular) {
+        f(each);
+      }
+    }
+  }
+
+  /** Iterate over the fields used in the constructor. */
+  void forEachConstructorField(Function f) {
+    for (var each in contents) {
+      if (each.usedInConstructor) {
+        f(each);
+      }
+    }
+  }
+
+  List get constructorFields => _constructorFields;
+  List constructorFieldNames() =>
+      constructorFields.map((x) => x.name).toList();
+  List constructorFieldIndices() =>
+      constructorFields.map((x) => x.index).toList();
+  List regularFields() => contents.where((x) => !x.usedInConstructor).toList();
+  List regularFieldNames() => regularFields().map((x) => x.name).toList();
+  List regularFieldIndices() =>
+      regularFields().map((x) => x.index).toList();
+
+  /**
+   * If we weren't given any non-constructor fields to use, figure out what
+   * we think they ought to be, based on the class definition.
+   * We find public fields, getters that have corresponding setters, and getters
+   * that are listed in the constructor fields.
+   */
+  void figureOutFields() {
+    Iterable names(Iterable<DeclarationMirror> mirrors) =>
+        mirrors.map((each) => each.simpleName).toList();
+
+    if (!_shouldFigureOutFields || !regularFields().isEmpty) return;
+    var fields = publicFields(mirror);
+    var getters = publicGetters(mirror);
+    var gettersWithSetters = getters.where( (each)
+        => mirror.declarations[
+            new Symbol("${MirrorSystem.getName(each.simpleName)}=")] != null);
+    var gettersThatMatchConstructor = getters.where((each)
+        => (named(each.simpleName) != null) &&
+            (named(each.simpleName).usedInConstructor)).toList();
+    addAllNotExplicitlyExcluded(names(fields));
+    addAllNotExplicitlyExcluded(names(gettersWithSetters));
+    addAllNotExplicitlyExcluded(names(gettersThatMatchConstructor));
+  }
+
+  toString() => "FieldList($contents)";
+}
+
+/**
+ *  Provide a typedef for the setWith argument to setFieldWith. It would
+ * be nice if we could put this closer to the definition.
+ */
+typedef SetWithFunction(InstanceMirror m, object);
+
+/**
+ * This represents a constructor that is to be used when re-creating a
+ * serialized object.
+ */
+class Constructor {
+  /** The mirror of the class we construct. */
+  final ClassMirror type;
+
+  /** The name of the constructor to use, if not the default constructor.*/
+  String name;
+  Symbol nameSymbol;
+
+  /**
+   * The indices of the fields used as constructor arguments. We will look
+   * these up in the state by number. The index is according to a list of the
+   * fields in alphabetical order by name.
+   */
+  List<int> fieldNumbers;
+
+  /**
+   * Creates a new constructor for the [type] with the constructor named [name]
+   * and the [fieldNumbers] of the constructor fields.
+   */
+  Constructor(this.type, this.name, this.fieldNumbers) {
+    if (name == null) name = '';
+    nameSymbol = new Symbol(name);
+    if (fieldNumbers == null) fieldNumbers = const [];
+  }
+
+  /**
+   * Find the field values in [state] and pass them to the constructor.
+   * If any of [fieldNumbers] is not an int, then use it as a literal value.
+   */
+  constructFrom(state, Reader r) {
+    // TODO(alanknight): Handle named parameters
+    Iterable inflated = fieldNumbers.map(
+        (x) => (x is int) ? r.inflateReference(state[x]) : x);
+    return type.newInstance(nameSymbol, inflated.toList());
+  }
+}
+
+/**
+ * This wraps a map to make it indexable by integer field numbers. It translates
+ * from the index into a field name and then looks it up in the map.
+ */
+class _MapWrapper {
+  final Map _map;
+  final List fieldList;
+  _MapWrapper(this.fieldList) : _map = new Map();
+  _MapWrapper.fromMap(this._map, this.fieldList);
+
+  operator [](key) => _map[fieldList[key].name];
+
+  operator []=(key, value) { _map[fieldList[key].name] = value; }
+  get length => _map.length;
+
+  Map asMap() => _map;
+}
+
+/**
+ * Return a symbol corresponding to [value], which may be a String or a
+ * Symbol. If it is any other type, or if the string is an
+ * invalid symbol, return null;
+ */
+Symbol _asSymbol(value) {
+  if (value is Symbol) return value;
+  if (value is String) {
+    try {
+      return new Symbol(value);
+    } on ArgumentError {
+      return null;
+    };
+  } else {
+    return null;
+  }
+}