YAMLSourceMap

A support library for resolving the YAML source location of objects parsed with the Node.js yaml library.

Install along with yaml:

1npm install --save yaml yaml-source-map

Usage

Construct an instance of YAMLSourceMap and feed it every document you parse that you also want to look up later. Assume we have a YAML blob like the following:

1---
2# file: example.yml
3a:
4  b: 1
5  # another comment
6  c: 2

We would first pass it through YAML.parseDocument and then through our source map for indexing:

1const fs = require('fs')
2const YAML = require('yaml')
3const YAMLSourceMap = require('yaml-source-map')
4
5const sourceMap = new YAMLSourceMap()
6const document = sourceMap.index(
7    YAML.parseDocument(
8        fs.readFileSync('./example.yml', 'utf8'),
9        { keepCstNodes: true /* must specify this */ }
10    ),
11    { filename: 'example.yml' /* optional */ }
12)
13// => { a: { b: 1, c: 2 } }

Now we're ready to look up documents:

1sourceMap.lookup([], document)
2// => { filename: 'example.yml', line: 3 }
3
4sourceMap.lookup([ 'a' ], document)
5// => { filename: 'example.yml', line: 4 }
6
7sourceMap.lookup([ 'a', 'b' ], document)
8// => { filename: 'example.yml', line: 4 }
9
10sourceMap.lookup([ 'a', 'c' ], document)
11// => { filename: 'example.yml', line: 6 }
12
13sourceMap.lookup([], document.a)
14// => { filename: 'example.yml', line: 4 }

You can index as many documents as needed, which may come from different source files (you'd use the filename option to keep track of that.)

API

index(YAML.Document): Object

Add a YAML document you parsed previously to the source map. The returned value is a new and serialized version of the document that can be used in code and for lookups.

lookup(Array.<String>, Object): ?Location

Look up the location of a document you previously indexed. A path may be specified to resolve the location of a value found inside the starting value -- useful for scalars since they cannot be indexed in any meaningful way. Leave it empty to resolve the location of the passed value.

Location is defined as:

1{
2    filename: ?String,
3    start: {
4      line: Number,
5      col: Number
6    },
7    end: {
8      line: Number,
9      col: Number
10    }
11}

Limitations

The location reported for a map (a YAML dictionary) will be that of its first property. Likewise for an array (a YAML list), the location will be that of its first element. This is a limitation of the parser and the library does not work around it.

For example, consider the YAML blob from the earlier usage example: the line reported for a will actually be that for a.b -- line 4. This may be counter-intuitive for humans but is usually not a big deal in practice.

Changelog

2.1.0

Added support for more YAML types: flow maps and sequences, and aliases.

2.0.0

lookup() will now return all location information, not just line. To upgrade, change all references to lookup().line to lookup().start.line.