yaml-source-map
v2.1.1
Published
Resolve source location of Objects parsed from YAML.
Downloads
4,226
Readme
YAMLSourceMap
A support library for resolving the YAML source location of objects parsed with the Node.js yaml library.
Install along with yaml:
npm 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:
---
# file: example.yml
a:
b: 1
# another comment
c: 2
We would first pass it through YAML.parseDocument
and then
through our source map for indexing:
const fs = require('fs')
const YAML = require('yaml')
const YAMLSourceMap = require('yaml-source-map')
const sourceMap = new YAMLSourceMap()
const document = sourceMap.index(
YAML.parseDocument(
fs.readFileSync('./example.yml', 'utf8'),
{ keepCstNodes: true /* must specify this */ }
),
{ filename: 'example.yml' /* optional */ }
)
// => { a: { b: 1, c: 2 } }
Now we're ready to look up documents:
sourceMap.lookup([], document)
// => { filename: 'example.yml', line: 3 }
sourceMap.lookup([ 'a' ], document)
// => { filename: 'example.yml', line: 4 }
sourceMap.lookup([ 'a', 'b' ], document)
// => { filename: 'example.yml', line: 4 }
sourceMap.lookup([ 'a', 'c' ], document)
// => { filename: 'example.yml', line: 6 }
sourceMap.lookup([], document.a)
// => { 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:
{
filename: ?String,
start: {
line: Number,
col: Number
},
end: {
line: Number,
col: Number
}
}
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
.