Index: pkg/yaml/lib/yaml.dart |
diff --git a/pkg/yaml/lib/yaml.dart b/pkg/yaml/lib/yaml.dart |
index fa5286164274d0b89c105807b3d95cff066082dd..dc895e655c60bf770ab7572664ed3a0b77b25c13 100644 |
--- a/pkg/yaml/lib/yaml.dart |
+++ b/pkg/yaml/lib/yaml.dart |
@@ -2,44 +2,6 @@ |
// 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 parser for [YAML](http://www.yaml.org/). |
-/// |
-/// ## Installing ## |
-/// |
-/// Use [pub][] to install this package. Add the following to your |
-/// `pubspec.yaml` file. |
-/// |
-/// dependencies: |
-/// yaml: any |
-/// |
-/// Then run `pub install`. |
-/// |
-/// For more information, see the |
-/// [yaml package on pub.dartlang.org][pkg]. |
-/// |
-/// ## Using ## |
-/// |
-/// Use [loadYaml] to load a single document, or [loadYamlStream] to load a |
-/// stream of documents. For example: |
-/// |
-/// import 'package:yaml/yaml.dart'; |
-/// main() { |
-/// var doc = loadYaml("YAML: YAML Ain't Markup Language"); |
-/// print(doc['YAML']); |
-/// } |
-/// |
-/// This library currently doesn't support dumping to YAML. You should use |
-/// `JSON.encode` from `dart:convert` instead: |
-/// |
-/// import 'dart:convert'; |
-/// import 'package:yaml/yaml.dart'; |
-/// main() { |
-/// var doc = loadYaml("YAML: YAML Ain't Markup Language"); |
-/// print(JSON.encode(doc)); |
-/// } |
-/// |
-/// [pub]: http://pub.dartlang.org |
-/// [pkg]: http://pub.dartlang.org/packages/yaml |
library yaml; |
import 'src/composer.dart'; |
@@ -50,18 +12,23 @@ import 'src/yaml_exception.dart'; |
export 'src/yaml_exception.dart'; |
export 'src/yaml_map.dart'; |
-/// Loads a single document from a YAML string. If the string contains more than |
-/// one document, this throws an error. |
+/// Loads a single document from a YAML string. |
+/// |
+/// If the string contains more than one document, this throws a |
+/// [YamlException]. In future releases, this will become an [ArgumentError]. |
/// |
/// The return value is mostly normal Dart objects. However, since YAML mappings |
/// support some key types that the default Dart map implementation doesn't |
-/// (null, NaN, booleans, lists, and maps), all maps in the returned document |
-/// are [YamlMap]s. These have a few small behavioral differences from the |
-/// default Map implementation; for details, see the [YamlMap] class. |
+/// (NaN, lists, and maps), all maps in the returned document are [YamlMap]s. |
+/// These have a few small behavioral differences from the default Map |
+/// implementation; for details, see the [YamlMap] class. |
+/// |
+/// In future versions, maps will instead be [HashMap]s with a custom equality |
+/// operation. |
loadYaml(String yaml) { |
var stream = loadYamlStream(yaml); |
if (stream.length != 1) { |
- throw new YamlException("Expected 1 document, were ${stream.length}"); |
+ throw new YamlException("Expected 1 document, were ${stream.length}."); |
} |
return stream[0]; |
} |
@@ -70,9 +37,12 @@ loadYaml(String yaml) { |
/// |
/// The return value is mostly normal Dart objects. However, since YAML mappings |
/// support some key types that the default Dart map implementation doesn't |
-/// (null, NaN, booleans, lists, and maps), all maps in the returned document |
-/// are [YamlMap]s. These have a few small behavioral differences from the |
-/// default Map implementation; for details, see the [YamlMap] class. |
+/// (NaN, lists, and maps), all maps in the returned document are [YamlMap]s. |
+/// These have a few small behavioral differences from the default Map |
+/// implementation; for details, see the [YamlMap] class. |
+/// |
+/// In future versions, maps will instead be [HashMap]s with a custom equality |
+/// operation. |
List loadYamlStream(String yaml) { |
return new Parser(yaml).l_yamlStream() |
.map((doc) => new Constructor(new Composer(doc).compose()).construct()) |