You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If `value` is defined, the document `contents` are initialised with that value, wrapped recursively in appropriate [content nodes](#content-nodes).
73
-
If `value` is `undefined`, the document's `contents` is initialised as `null`.
74
-
If defined, a `replacer` may filter or modify the initial document contents, following the same algorithm as the [JSON implementation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter).
72
+
The document `value` is initialised with `value`, wrapped recursively in appropriate [content nodes](#content-nodes).
73
+
If defined, a `replacer` may filter or modify the initial document value, following the same algorithm as the [JSON implementation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter).
75
74
See [Options](#options) for more information on the last argument.
| commentBefore |`string?`| A comment at the very beginning of the document. If not empty, separated from the rest of the document by a blank line or the doc-start indicator when stringified. |
80
79
| comment |`string?`| A comment at the end of the document. If not empty, separated from the rest of the document by a blank line when stringified. |
81
-
|contents|[`Node`](#content-nodes)`⎮ any`| The document contents.|
80
+
|value|[`Node`](#content-nodes)`⎮ any`| The document value. |
82
81
| directives |[`Directives`](#stream-directives)| Controls for the `%YAML` and `%TAG` directives, as well as the doc-start marker `---`. |
83
82
| errors |[`Error[]`](#errors)| Errors encountered during parsing. |
84
83
| schema |`Schema`| The schema used with the document. |
@@ -99,21 +98,21 @@ String(doc)
99
98
```
100
99
101
100
The Document members are all modifiable, though it's unlikely that you'll have reason to change `errors`, `schema` or `warnings`.
102
-
In particular you may be interested in both reading and writing **`contents`**.
103
-
Although `parseDocument()` and `parseAllDocuments()` will leave it with `YAMLMap`, `YAMLSeq`, `Scalar`or `null` contents, it can be set to anything.
101
+
In particular you may be interested in both reading and writing **`value`**,
102
+
which is expected to always contain a `YAMLMap`, `YAMLSeq`, or `Scalar` value.
| clone() |`Document`| Create a deep copy of this Document and its contents. Custom Node values that inherit from `Object` still refer to their original instances. |
110
-
| createAlias(node: Node, name?: string) |`Alias`| Create a new `Alias` node, adding the required anchor for `node`. If `name` is empty, a new anchor name will be generated. |
111
-
| createNode(value, options?) |`Node`| Recursively wrap any input with appropriate `Node` containers. See [Creating Nodes](#creating-nodes) for more information. |
112
-
| createPair(key, value, options?) |`Pair`| Recursively wrap `key` and `value` into a `Pair` object. See [Creating Nodes](#creating-nodes) for more information. |
113
-
| setSchema(version, options?) |`void`| Change the YAML version and schema used by the document. `version` must be either `'1.1'` or `'1.2'`; accepts all Schema options. |
114
-
| toJS(options?) |`any`| A plain JavaScript representation of the document `contents`. |
115
-
| toJSON() |`any`| A JSON representation of the document `contents`. |
116
-
| toString(options?) |`string`| A YAML representation of the document. |
| clone() |`Document`| Create a deep copy of this Document and its value. Custom Node values that inherit from `Object` still refer to their original instances. |
109
+
| createAlias(node: Node, name?: string) |`Alias`| Create a new `Alias` node, adding the required anchor for `node`. If `name` is empty, a new anchor name will be generated. |
110
+
| createNode(value, options?) |`Node`| Recursively wrap any input with appropriate `Node` containers. See [Creating Nodes](#creating-nodes) for more information. |
111
+
| createPair(key, value, options?) |`Pair`| Recursively wrap `key` and `value` into a `Pair` object. See [Creating Nodes](#creating-nodes) for more information. |
112
+
| setSchema(version, options?) |`void`| Change the YAML version and schema used by the document. `version` must be either `'1.1'` or `'1.2'`; accepts all Schema options. |
113
+
| toJS(options?) |`any`| A plain JavaScript representation of the document `value`. |
114
+
| toJSON() |`any`| A JSON representation of the document `value`. |
115
+
| toString(options?) |`string`| A YAML representation of the document. |
117
116
118
117
```js
119
118
constdoc=parseDocument('a: 1\nb: [2, 3]\n')
@@ -127,7 +126,7 @@ doc.getIn(['b', 1]) // 4
127
126
128
127
In addition to the above, the document object also provides the same **accessor methods** as [collections](#collections), based on the top-level collection:
129
128
`add`, `delete`, `get`, `has`, and `set`, along with their deeper variants `addIn`, `deleteIn`, `getIn`, `hasIn`, and `setIn`.
130
-
For the `*In` methods using an empty `path` value (i.e. `null`, `undefined`, or `[]`) will refer to the document's top-level `contents`.
129
+
For the `*In` methods using an empty `path` value (i.e. `[]`) will refer to the document's top-level `value`.
131
130
132
131
#### `Document#toJS()`, `Document#toJSON()` and `Document#toString()`
133
132
@@ -177,5 +176,5 @@ The contents of `doc.directives.tags` are used both for the `%TAG` directives an
177
176
Each of the handles must start and end with a `!` character; `!` is by default the local tag and `!!` is used for default tags.
178
177
See the section on [custom tags](#writing-custom-tags) for more on this topic.
179
178
180
-
`doc.contents.yaml` determines if an explicit `%YAML` directive should be included in the output, and what version it should use.
179
+
`doc.directives.yaml` determines if an explicit `%YAML` directive should be included in the output, and what version it should use.
181
180
If changing the version after the document's creation, you'll probably want to use `doc.setSchema()` as it will also update the schema accordingly.
Copy file name to clipboardExpand all lines: docs/05_content_nodes.md
+17-64Lines changed: 17 additions & 64 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Content Nodes
2
2
3
-
After parsing, the `contents` value of each `YAML.Document` is the root of an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of nodes representing the document (or `null` for an empty document).
3
+
After parsing, the `value` value of each `YAML.Document` is the root of an [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree) of nodes representing the document.
4
4
5
5
Both scalar and collection values may have an `anchor` associated with them; this is rendered in the string representation with a `&` prefix, so e.g. in `foo: &aa bar`, the value `bar` has the anchor `aa`.
6
6
Anchors are used by [Alias nodes](#alias-nodes) to allow for the same value to be used in multiple places in the document.
A parsed document's contents will have all of its non-object values wrapped in `Scalar` objects, which themselves may be in some hierarchy of `YAMLMap` and `YAMLSeq` collections.
44
+
A parsed document's value will have all of its non-object values wrapped in `Scalar` objects, which themselves may be in some hierarchy of `YAMLMap` and `YAMLSeq` collections.
45
45
However, this is not a requirement for the document's stringification, which is rather tolerant regarding its input values, and will use [`doc.createNode()`](#creating-nodes) when encountering an unwrapped value.
46
46
47
47
When stringifying, the node `type` will be taken into account by `!!str` and `!!binary` values, and ignored by other scalars.
@@ -50,21 +50,21 @@ On the other hand, `!!int` and `!!float` stringifiers will take `format` into ac
50
50
## Collections
51
51
52
52
```js
53
-
classPair<K= unknown, V= unknown> {
54
-
key:K// When parsed, key and value are always
55
-
value:V//Node or null, but can be set to anything
53
+
classPair {
54
+
key:Node
55
+
value:Node|null
56
56
}
57
57
58
58
classCollectionextendsNodeBase {
59
59
anchor?: string // an anchor associated with this node
60
60
flow?: boolean // use flow style when stringifying this
Within all YAML documents, two forms of collections are supported: sequential `YAMLSeq` collections and key-value `YAMLMap` collections.
90
-
The JavaScript representations of these collections both have an `items` array, which may (`YAMLSeq`) or must (`YAMLMap`) consist of `Pair` objects that contain a `key` and a `value` of any type, including`null`.
91
-
The `items` array of a `YAMLSeq` object may contain values of any type.
90
+
The JavaScript representations of these collections both have an `items` array, which may (`YAMLSeq`) or must (`YAMLMap`) consist of `Pair` objects that contain a `key` and a `value` of any node type, or`null` for `value`.
91
+
The `items` array of a `YAMLSeq` object may contain any node values.
92
92
93
93
When stringifying collections, by default block notation will be used.
94
94
Flow notation will be selected if `flow` is `true`, the collection is within a surrounding flow collection, or if the collection is in an implicit key.
@@ -169,7 +169,7 @@ When nodes are constructed from JS structures (e.g. during `YAML.stringify()`),
169
169
```js
170
170
constdoc=newYAML.Document(['some', 'values'])
171
171
// Document {
172
-
//contents:
172
+
//value:
173
173
// YAMLSeq {
174
174
// items:
175
175
// [ Scalar { value: 'some' },
@@ -209,8 +209,7 @@ For all available options, see the [CreateNode Options](#createnode-options) sec
The primary purpose of this method is to enable attaching comments or other metadata to a value, or to otherwise exert more fine-grained control over the stringified output.
212
-
To that end, you'll need to assign its return value to the `contents` of a document (or somewhere within said contents), as the document's schema is required for YAML string output.
213
-
If you're not interested in working with such metadata, document `contents` may also include non-`Node` values at any level.
212
+
To that end, you'll need to assign its return value to the `value` of a document (or somewhere within said value), as the document's schema is required for YAML string output.
@@ -236,12 +235,11 @@ You should make sure to only add alias nodes to the document after the nodes to
236
235
```js
237
236
import { Document, YAMLSeq } from'yaml'
238
237
239
-
constdoc=newDocument(newYAMLSeq())
240
-
doc.contents.items= [
238
+
constdoc=newDocument([
241
239
'some values',
242
240
42,
243
241
{ including:'objects', 3:'a string' }
244
-
]
242
+
])
245
243
doc.add(doc.createPair(1, 'a number'))
246
244
247
245
doc.toString()
@@ -320,7 +318,7 @@ The return value of the visitor may be used to control the traversal:
320
318
- `number`: While iterating the items of a sequence or map, set the index of the next step.
321
319
This is useful especially if the index of the current node has changed.
322
320
323
-
If `visitor` is a single function, it will be called with all values encountered in the tree, including e.g. `null` values.
321
+
If `visitor` is a single function, it will be called with all values encountered in the tree, including `null` values.
324
322
Alternatively, separate visitor functions may be defined for each `Map`, `Pair`, `Seq`, `Alias` and `Scalar` node.
325
323
To define the same visitor function for more than one node type,
326
324
use the `Collection` (map and seq), `Value` (map, seq & scalar) and `Node` (alias, map, seq & scalar) targets.
@@ -332,51 +330,6 @@ The same as `visit()`,
332
330
but allows for visitor functions that return a promise
333
331
which resolves to one of the above-defined control values.
334
332
335
-
## Identifying Node Types
336
-
337
-
```js
338
-
import {
339
-
isAlias,
340
-
isCollection, // map or seq
341
-
isDocument,
342
-
isMap,
343
-
isNode, // alias, scalar, map or seq
344
-
isPair,
345
-
isScalar,
346
-
isSeq
347
-
} from'yaml'
348
-
349
-
constdoc=newDocument({ foo: [13, 42] })
350
-
isDocument(doc) ===true
351
-
isNode(doc) ===false
352
-
isMap(doc.contents) ===true
353
-
isNode(doc.contents) ===true
354
-
isPair(doc.contents.items[0]) ===true
355
-
isCollection(doc.get('foo')) ===true
356
-
isScalar(doc.getIn(['foo', 1])) ===true
357
-
```
358
-
359
-
#### `isAlias(x: unknown): boolean`
360
-
361
-
#### `isCollection(x: unknown): boolean`
362
-
363
-
#### `isDocument(x: unknown): boolean`
364
-
365
-
#### `isMap(x: unknown): boolean`
366
-
367
-
#### `isNode(x: unknown): boolean`
368
-
369
-
#### `isPair(x: unknown): boolean`
370
-
371
-
#### `isScalar(x: unknown): boolean`
372
-
373
-
#### `isSeq(x: unknown): boolean`
374
-
375
-
To find out what you've got, a family of custom type guard functions is provided.
376
-
These should be preferred over other methods such as `instanceof` checks, as they'll work even if the nodes have been created by a different instance of the library.
377
-
378
-
Internally, node identification uses property symbols that are set on instances during their construction.
0 commit comments