Skip to content

Commit 74a86e2

Browse files
committed
docs: Add yaml-types mention
1 parent e80a4c5 commit 74a86e2

File tree

2 files changed

+55
-47
lines changed

2 files changed

+55
-47
lines changed

docs/05_content_nodes.md

Lines changed: 46 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -258,52 +258,7 @@ Once created, normal array operations may be used to modify the `items` array.
258258
New `Pair` objects may created either by importing the class from `yaml` and using its `new Pair(key, value)` constructor, or by using the `doc.createPair(key, value, options?)` method.
259259
The latter will recursively wrap the `key` and `value` as nodes, and accepts the same options as `doc.createNode()`
260260
261-
## Identifying Nodes
262-
263-
```js
264-
import {
265-
isAlias,
266-
isCollection, // map or seq
267-
isDocument,
268-
isMap,
269-
isNode, // alias, scalar, map or seq
270-
isPair,
271-
isScalar,
272-
isSeq
273-
} from 'yaml'
274-
275-
const doc = new Document({ foo: [13, 42] })
276-
isDocument(doc) === true
277-
isNode(doc) === false
278-
isMap(doc.contents) === true
279-
isNode(doc.contents) === true
280-
isPair(doc.contents.items[0]) === true
281-
isCollection(doc.get('foo')) === true
282-
isScalar(doc.getIn(['foo', 1])) === true
283-
```
284-
285-
#### `isAlias(x: unknown): boolean`
286-
287-
#### `isCollection(x: unknown): boolean`
288-
289-
#### `isDocument(x: unknown): boolean`
290-
291-
#### `isMap(x: unknown): boolean`
292-
293-
#### `isNode(x: unknown): boolean`
294-
295-
#### `isPair(x: unknown): boolean`
296-
297-
#### `isScalar(x: unknown): boolean`
298-
299-
#### `isSeq(x: unknown): boolean`
300-
301-
To find out what you've got, a family of custom type guard functions is provided.
302-
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.
303-
304-
Internally, node identification uses property symbols that are set on instances during their construction.
305-
306-
## Modifying Nodes
261+
## Finding and Modifying Nodes
307262
308263
```js
309264
const doc = YAML.parseDocument(`
@@ -377,6 +332,51 @@ The same as `visit()`,
377332
but allows for visitor functions that return a promise
378333
which resolves to one of the above-defined control values.
379334
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+
const doc = new Document({ 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.
379+
380380
## Comments and Blank Lines
381381
382382
```js

docs/06_custom_tags.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,14 @@ The easiest way to extend a [schema](#data-schemas) is by defining the additiona
1818

1919
For further customisation, `customTags` may also be a function `(Tag[]) => (Tag[])` that may modify the schema's base tag array.
2020

21+
Some additional data types are available separately via the [`yaml-types`](https://github.com/eemeli/yaml-types) package, including support for:
22+
23+
- BigInt values
24+
- Error objects
25+
- Objects with a null prototype
26+
- RegExp values
27+
- Symbols
28+
2129
## Built-in Custom Tags
2230

2331
```js
@@ -180,7 +188,7 @@ stringify(
180188

181189
In YAML-speak, a custom data type is represented by a _tag_. To define your own tag, you need to account for the ways that your data is both parsed and stringified. Furthermore, both of those processes are split into two stages by the intermediate AST node structure.
182190

183-
If you wish to implement your own custom tags, the [`!!binary`](https://github.com/eemeli/yaml/blob/main/src/schema/yaml-1.1/binary.ts) and [`!!set`](https://github.com/eemeli/yaml/blob/main/src/schema/yaml-1.1/set.ts) tags provide relatively cohesive examples to study in addition to the simple examples in the sidebar here.
191+
If you wish to implement your own custom tags, the [`!!binary`](https://github.com/eemeli/yaml/blob/main/src/schema/yaml-1.1/binary.ts) and [`!!set`](https://github.com/eemeli/yaml/blob/main/src/schema/yaml-1.1/set.ts) tags as well as the [`yaml-types`](https://github.com/eemeli/yaml-types) package provide relatively cohesive examples to study in addition to the simple examples in the sidebar here.
184192

185193
Custom collection types (ie, Maps, Sets, objects, and arrays; anything with child properties that may not be propertly serialized to a scalar value) may provide a `nodeClass` property that extends the [`YAMLMap`](https://github.com/eemeli/yaml/blob/main/src/nodes/YAMLMap.ts) and [`YAMLSeq`](https://github.com/eemeli/yaml/blob/main/src/nodes/YAMLSeq.ts) classes, which will be used for parsing and stringifying objects with the specified tag.
186194

0 commit comments

Comments
 (0)