Add new constructors to YamlNode subclasses.

pkg/yaml/lib/src/yaml_node.dart

Index: pkg/yaml/lib/src/yaml_node.dart
diff --git a/pkg/yaml/lib/src/yaml_node.dart b/pkg/yaml/lib/src/yaml_node.dart
index d0e0578995b5e9d8faf5fcd6d8202f6198dce8bb..240a57bece331450a04e8cf61d66e6ba479cc831 100644
--- a/pkg/yaml/lib/src/yaml_node.dart
+++ b/pkg/yaml/lib/src/yaml_node.dart
@@ -2,13 +2,16 @@
 // 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
@@ -37,14 +40,39 @@ abstract class YamlNode {
 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) {
@@ -68,8 +96,27 @@ class YamlList extends YamlNode with collection.ListMixin {
     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;
@@ -85,8 +132,17 @@ class YamlScalar extends YamlNode {
 
   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();
 }