Add new constructors to YamlNode subclasses.

pkg/yaml/lib/src/yaml_node.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.
 
-library yaml.map;
+library yaml.yaml_node;
 
 import 'dart:collection' as collection;
 
 import 'package:collection/collection.dart';
 import 'package:source_maps/source_maps.dart';
 
+import 'dummy_span.dart';
+import 'yaml_node_wrapper.dart';
+
 /// An interface for parsed nodes from a YAML source tree.
 ///
 /// [YamlMap]s and [YamlList]s implement this interface in addition to the
 /// normal [Map] and [List] interfaces, so any maps and lists will be
 /// [YamlNode]s regardless of how they're accessed.
 ///
 /// Scalars values like strings and numbers, on the other hand, don't have this
 /// interface by default. Instead, they can be accessed as [YamlScalar]s via
 /// [YamlMap.nodes] or [YamlList.nodes].
 abstract class YamlNode {
   /// The source span for this node.
   ///
   /// [Span.getLocationMessage] can be used to produce a human-friendly message
   /// about this node.
   Span get span;
 
   /// The inner value of this node.
   ///
   /// For [YamlScalar]s, this will return the wrapped value. For [YamlMap] and
   /// [YamlList], it will return [this], since they already implement [Map] and
   /// [List], respectively.
   get value;
 }
 
 /// A read-only [Map] parsed from YAML.
 class YamlMap extends YamlNode with collection.MapMixin, UnmodifiableMapMixin  {
   final Span span;
 
+  /// A view of [this] where the keys and values are guaranteed to be
+  /// [YamlNode]s.
+  ///
+  /// The key type is `dynamic` to allow keys to be accessed using
+  /// non-[YamlNode] values, but [Map.keys] and [Map.forEach] will always expose

[Bob Nystrom, 2014/06/21 00:14:15]

I didn't follow what "allow keys to be accessed using non-[YamlNode] values"
means. Can you clarify?

[nweiz, 2014/06/23 22:23:06]

Done.

+  /// them as [YamlNode]s.
   final Map<dynamic, YamlNode> nodes;
 
   Map get value => this;
 
   Iterable get keys => nodes.keys.map((node) => node.value);
 
-  /// Users of the library should not construct [YamlMap]s manually.
-  YamlMap(Map<dynamic, YamlNode> nodes, this.span)
+  /// Creates an empty YamlMap.
+  ///
+  /// This map's [span] will be a dummy without useful location information.
+  /// However, it will have a reasonable implementation of
+  /// [Span.getLocationMessage]. If [sourceName] is passed, it's used as

[Bob Nystrom, 2014/06/21 00:14:15]

"as" -> "as the"

[nweiz, 2014/06/23 22:23:06]

Done.

+  /// [Span.sourceUrl].
+  factory YamlMap({String sourceName}) =>
+      new YamlMapWrapper(const {}, sourceName);
+
+  /// Wraps a Dart map so that it can be accessed (recursively) like a
+  /// [YamlMap].
+  ///
+  /// Any [Span]s returned by this map or its children will be dummies without
+  /// useful location information. However, they will have a reasonable
+  /// implementation of [Span.getLocationMessage]. If [sourceName] is passed,
+  /// it's used as [Span.sourceUrl].
+  factory YamlMap.wrap(Map dartMap, {String sourceName}) =>
+      new YamlMapWrapper(dartMap, sourceName);
+
+  /// Users of the library should not use this constructor.
+  YamlMap.internal(Map<dynamic, YamlNode> nodes, this.span)
       : nodes = new UnmodifiableMapView<dynamic, YamlNode>(nodes);
 
   operator [](key) {
     var node = nodes[key];
     return node == null ? null : node.value;
   }
 }
 
 // TODO(nweiz): Use UnmodifiableListMixin when issue 18970 is fixed.
 /// A read-only [List] parsed from YAML.
 class YamlList extends YamlNode with collection.ListMixin {
   final Span span;
 
   final List<YamlNode> nodes;
 
   List get value => this;
 
   int get length => nodes.length;
 
   set length(int index) {
     throw new UnsupportedError("Cannot modify an unmodifiable List");
   }
 
-  /// Users of the library should not construct [YamlList]s manually.
-  YamlList(List<YamlNode> nodes, this.span)
+  /// Creates an empty YamlList.
+  ///
+  /// This list's [span] will be a dummy without useful location information.
+  /// However, it will have a reasonable implementation of
+  /// [Span.getLocationMessage]. If [sourceName] is passed, it's used as
+  /// [Span.sourceUrl].
+  factory YamlList({String sourceName}) =>
+      new YamlListWrapper(const [], sourceName);
+
+  /// Wraps a Dart list so that it can be accessed (recursively) like a
+  /// [YamlList].
+  ///
+  /// Any [Span]s returned by this list or its children will be dummies without
+  /// useful location information. However, they will have a reasonable
+  /// implementation of [Span.getLocationMessage]. If [sourceName] is passed,
+  /// it's used as [Span.sourceUrl].
+  factory YamlList.wrap(List dartList, {String sourceName}) =>
+      new YamlListWrapper(dartList, sourceName);
+
+  /// Users of the library should not use this constructor.

[Bob Nystrom, 2014/06/21 00:14:15]

For cases like this, I like the pattern of making the method (here ctor) private
and adding a top-level, non-exported function to invoke it.

[nweiz, 2014/06/23 22:23:06]

I disagree. That adds a lot of overhead to internal uses of the class for very
little benefit.

The language's privacy rules are never going to be able to perfectly enforce a
library's usage restrictions—for example, a user could always just import
something from src. Some of those restrictions have to be encoded in the
documentation instead. Given how clear the documentation is here, I think it's
fine not to bend over backwards to make it language-private as well.

[Bob Nystrom, 2014/06/23 23:11:44]

I don't look at it as preventing the user from doing something so much as
avoiding clutter in the API.
Sure, but not this. It's not like the pattern is that hard. Barback uses it in a
number of places. What's different here?

[nweiz, 2014/06/24 00:03:09]

It would be nice to be able to tell docgen "don't document this member", but I'd
rather not make the code more complicated to work around the lack of that
feature.
It's pretty gross. It involves an unnecessary level of indirection that's
confusing for anyone reading the code that uses it.
I'm not a big fan of the pattern in Barback either. I think you introduced it.

+  YamlList.internal(List<YamlNode> nodes, this.span)
       : nodes = new UnmodifiableListView<YamlNode>(nodes);
 
   operator [](int index) => nodes[index].value;
 
   operator []=(int index, value) {
     throw new UnsupportedError("Cannot modify an unmodifiable List");
   }
 }
 
 /// A wrapped scalar value parsed from YAML.
 class YamlScalar extends YamlNode {
   final Span span;
 
   final value;
 
-  /// Users of the library should not construct [YamlScalar]s manually.
-  YamlScalar(this.value, this.span);
+  /// Wraps a Dart value in a [YamlScalar].
+  ///
+  /// This scalar's [span] will be a dummy without useful location information.
+  /// However, it will have a reasonable implementation of
+  /// [Span.getLocationMessage]. If [sourceName] is passed, it's used as
+  /// [Span.sourceUrl].
+  YamlScalar.wrap(this.value, {String sourceName})
+      : span = new DummySpan(sourceName);
+
+  /// Users of the library should not use this constructor.
+  YamlScalar.internal(this.value, this.span);
 
   String toString() => value.toString();
 }