OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /// A parser for [YAML](http://www.yaml.org/). | |
6 /// | |
7 /// ## Installing ## | |
8 /// | |
9 /// Use [pub][] to install this package. Add the following to your | |
10 /// `pubspec.yaml` file. | |
11 /// | |
12 /// dependencies: | |
13 /// yaml: any | |
14 /// | |
15 /// Then run `pub install`. | |
16 /// | |
17 /// For more information, see the | |
18 /// [yaml package on pub.dartlang.org][pkg]. | |
19 /// | |
20 /// ## Using ## | |
21 /// | |
22 /// Use [loadYaml] to load a single document, or [loadYamlStream] to load a | |
23 /// stream of documents. For example: | |
24 /// | |
25 /// import 'package:yaml/yaml.dart'; | |
26 /// main() { | |
27 /// var doc = loadYaml("YAML: YAML Ain't Markup Language"); | |
28 /// print(doc['YAML']); | |
29 /// } | |
30 /// | |
31 /// This library currently doesn't support dumping to YAML. You should use | |
32 /// `JSON.encode` from `dart:convert` instead: | |
33 /// | |
34 /// import 'dart:convert'; | |
35 /// import 'package:yaml/yaml.dart'; | |
36 /// main() { | |
37 /// var doc = loadYaml("YAML: YAML Ain't Markup Language"); | |
38 /// print(JSON.encode(doc)); | |
39 /// } | |
40 /// | |
41 /// [pub]: http://pub.dartlang.org | |
42 /// [pkg]: http://pub.dartlang.org/packages/yaml | |
43 library yaml; | 5 library yaml; |
44 | 6 |
45 import 'src/composer.dart'; | 7 import 'src/composer.dart'; |
46 import 'src/constructor.dart'; | 8 import 'src/constructor.dart'; |
47 import 'src/parser.dart'; | 9 import 'src/parser.dart'; |
48 import 'src/yaml_exception.dart'; | 10 import 'src/yaml_exception.dart'; |
49 | 11 |
50 export 'src/yaml_exception.dart'; | 12 export 'src/yaml_exception.dart'; |
51 export 'src/yaml_map.dart'; | 13 export 'src/yaml_map.dart'; |
52 | 14 |
53 /// Loads a single document from a YAML string. If the string contains more than | 15 /// Loads a single document from a YAML string. |
54 /// one document, this throws an error. | 16 /// |
| 17 /// If the string contains more than one document, this throws a |
| 18 /// [YamlException]. In future releases, this will become an [ArgumentError]. |
55 /// | 19 /// |
56 /// The return value is mostly normal Dart objects. However, since YAML mappings | 20 /// The return value is mostly normal Dart objects. However, since YAML mappings |
57 /// support some key types that the default Dart map implementation doesn't | 21 /// support some key types that the default Dart map implementation doesn't |
58 /// (null, NaN, booleans, lists, and maps), all maps in the returned document | 22 /// (NaN, lists, and maps), all maps in the returned document are [YamlMap]s. |
59 /// are [YamlMap]s. These have a few small behavioral differences from the | 23 /// These have a few small behavioral differences from the default Map |
60 /// default Map implementation; for details, see the [YamlMap] class. | 24 /// implementation; for details, see the [YamlMap] class. |
| 25 /// |
| 26 /// In future versions, maps will instead be [HashMap]s with a custom equality |
| 27 /// operation. |
61 loadYaml(String yaml) { | 28 loadYaml(String yaml) { |
62 var stream = loadYamlStream(yaml); | 29 var stream = loadYamlStream(yaml); |
63 if (stream.length != 1) { | 30 if (stream.length != 1) { |
64 throw new YamlException("Expected 1 document, were ${stream.length}"); | 31 throw new YamlException("Expected 1 document, were ${stream.length}."); |
65 } | 32 } |
66 return stream[0]; | 33 return stream[0]; |
67 } | 34 } |
68 | 35 |
69 /// Loads a stream of documents from a YAML string. | 36 /// Loads a stream of documents from a YAML string. |
70 /// | 37 /// |
71 /// The return value is mostly normal Dart objects. However, since YAML mappings | 38 /// The return value is mostly normal Dart objects. However, since YAML mappings |
72 /// support some key types that the default Dart map implementation doesn't | 39 /// support some key types that the default Dart map implementation doesn't |
73 /// (null, NaN, booleans, lists, and maps), all maps in the returned document | 40 /// (NaN, lists, and maps), all maps in the returned document are [YamlMap]s. |
74 /// are [YamlMap]s. These have a few small behavioral differences from the | 41 /// These have a few small behavioral differences from the default Map |
75 /// default Map implementation; for details, see the [YamlMap] class. | 42 /// implementation; for details, see the [YamlMap] class. |
| 43 /// |
| 44 /// In future versions, maps will instead be [HashMap]s with a custom equality |
| 45 /// operation. |
76 List loadYamlStream(String yaml) { | 46 List loadYamlStream(String yaml) { |
77 return new Parser(yaml).l_yamlStream() | 47 return new Parser(yaml).l_yamlStream() |
78 .map((doc) => new Constructor(new Composer(doc).compose()).construct()) | 48 .map((doc) => new Constructor(new Composer(doc).compose()).construct()) |
79 .toList(); | 49 .toList(); |
80 } | 50 } |
OLD | NEW |