Skip to content

Commit

Permalink
docs: Add yaml-types mention
Browse files Browse the repository at this point in the history
  • Loading branch information
eemeli committed Feb 25, 2024
1 parent e80a4c5 commit 74a86e2
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 47 deletions.
92 changes: 46 additions & 46 deletions docs/05_content_nodes.md
Original file line number Diff line number Diff line change
Expand Up @@ -258,52 +258,7 @@ Once created, normal array operations may be used to modify the `items` array.
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.
The latter will recursively wrap the `key` and `value` as nodes, and accepts the same options as `doc.createNode()`
## Identifying Nodes
```js
import {
isAlias,
isCollection, // map or seq
isDocument,
isMap,
isNode, // alias, scalar, map or seq
isPair,
isScalar,
isSeq
} from 'yaml'

const doc = new Document({ foo: [13, 42] })
isDocument(doc) === true
isNode(doc) === false
isMap(doc.contents) === true
isNode(doc.contents) === true
isPair(doc.contents.items[0]) === true
isCollection(doc.get('foo')) === true
isScalar(doc.getIn(['foo', 1])) === true
```
#### `isAlias(x: unknown): boolean`
#### `isCollection(x: unknown): boolean`
#### `isDocument(x: unknown): boolean`
#### `isMap(x: unknown): boolean`
#### `isNode(x: unknown): boolean`
#### `isPair(x: unknown): boolean`
#### `isScalar(x: unknown): boolean`
#### `isSeq(x: unknown): boolean`
To find out what you've got, a family of custom type guard functions is provided.
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.
Internally, node identification uses property symbols that are set on instances during their construction.
## Modifying Nodes
## Finding and Modifying Nodes
```js
const doc = YAML.parseDocument(`
Expand Down Expand Up @@ -377,6 +332,51 @@ The same as `visit()`,
but allows for visitor functions that return a promise
which resolves to one of the above-defined control values.
## Identifying Node Types
```js
import {
isAlias,
isCollection, // map or seq
isDocument,
isMap,
isNode, // alias, scalar, map or seq
isPair,
isScalar,
isSeq
} from 'yaml'

const doc = new Document({ foo: [13, 42] })
isDocument(doc) === true
isNode(doc) === false
isMap(doc.contents) === true
isNode(doc.contents) === true
isPair(doc.contents.items[0]) === true
isCollection(doc.get('foo')) === true
isScalar(doc.getIn(['foo', 1])) === true
```
#### `isAlias(x: unknown): boolean`
#### `isCollection(x: unknown): boolean`
#### `isDocument(x: unknown): boolean`
#### `isMap(x: unknown): boolean`
#### `isNode(x: unknown): boolean`
#### `isPair(x: unknown): boolean`
#### `isScalar(x: unknown): boolean`
#### `isSeq(x: unknown): boolean`
To find out what you've got, a family of custom type guard functions is provided.
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.
Internally, node identification uses property symbols that are set on instances during their construction.
## Comments and Blank Lines
```js
Expand Down
10 changes: 9 additions & 1 deletion docs/06_custom_tags.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,14 @@ The easiest way to extend a [schema](#data-schemas) is by defining the additiona

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

Some additional data types are available separately via the [`yaml-types`](https://github.com/eemeli/yaml-types) package, including support for:

- BigInt values
- Error objects
- Objects with a null prototype
- RegExp values
- Symbols

## Built-in Custom Tags

```js
Expand Down Expand Up @@ -180,7 +188,7 @@ stringify(

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.

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.
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.

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.

Expand Down

0 comments on commit 74a86e2

Please sign in to comment.