(XML -> JavaScript Object) low memory streaming parser based on node-expat C bindings
npm install xml2obj-stream
> Interface to iterate through XML resources and map them into JavaScript objects (allows custom transformations).
``bash`
npm install xml2obj-stream --save
Create an instance of parser to read from any readStream.
- coerce - make type coercion (e.g. numbers and booleans present in attributes and element values are converted from string to its correspondent data types), default true
- - remove leading and trailing whitespaces as well as line terminators in attributes and element values, default true
- - sanitizes such characters as <, >, (, ), #, &, ", ' present in element values, default false
Executes iterator function on every 'element' inside XML resource. Iterator receives an element that is already tranformed into object.
Default transformation produces an object that follows such rules:
- each becomes 1 object (including it's children, their attributes etc.), e.g. turns to {id: 12345, name: 'foo'}
- element's attributes like become properties of the object prefixed with element's name - {'tag': 'text', 'tag-foo': 'bar'}
You're able to manage custom transform on the element if default one doesn't suit you. Provided func receives proto object as the only argument. It has the following structure, example:
`xml`
Check proto object of the tag:
`javascript
{
$name: 'value', // name of the element
$text: 'bird', // content of the element
// hash-map of attributes if they are present
$attrs: {
type: 'string'
},
// parent element object
$parent: {
$name: 'column',
$parent: null,
// array of children objects if they are present
$children: [{
$name: 'name',
$text: 'dodo'
}, {
$name: 'value',
$text: 'bird',
$attrs: {
type: 'string'
}
}]
}
}
`
It's required for transform function to return some value. It will be used as an argument for each iterator function.
Bind callback function to one of the following read stream events - 'error', 'end', 'close'.
Pause the read stream.
Resume the read stream.
resource.xml
`xml`
app.js
`javascript
var xml2obj = require('xml2obj-stream');
var fs = require('fs');
var readStream = fs.createReadStream('resource.xml');
var parseStream = new xml2obj.Parser(readStream);
var results = [];
parseStream.each('column', function (item) {
// do something with item
results.push(item);
});
parseStream.on('end', function () {
console.dir(results);
// outputs ->
// [
// { name: 'dodo', value: 'bird', 'value-type': 'string' },
// { name: 'mighty', value: 'boosh', 'value-type': 'string' },
// { name: 'crack', value: 'fox', 'value-type': 'string' },
// { name: 'foo', value: true, 'value-type': 'boolean' },
// { name: 'uid', value: 12345, 'value-type': 'number' }
// ]
});
`
resource.xml
`xml`
app.js
`javascript
var xml2obj = require('xml2obj-stream');
var request = require('request');
var readStream = request('http://example.com/api/resource.xml');
var parseStream = new xml2obj.Parser(readStream);
var results = [];
parseStream.setTransformation(function (_proto) {
// map _proto to your needs here
// e.g. take only attributes of every tag
var obj = {};
mapper(_proto);
function mapper (o) {
for (var attr in o.$attrs) {
obj[attr] = o.$attrs[attr];
}
if (Array.isArray(o.$children)) {
o.$children.forEach(mapper);
}
}
return obj;
});
parseStream.each('floor_action', function (item) {
results.push(item);
});
parseStream.on('end', function () {
console.dir(results);
// outputs ->
// [{
// 'act-id': 'H38310',
// 'update-date-time': '20130628T11:24',
// 'for-search': '20130628T11:22:19'
// }]
});
`
If you're on Windows and have problems with instalation please check this troubleshoot links of node-expat:
- dependencies for node-gyp https://github.com/TooTallNate/node-gyp#installation
- see https://github.com/node-xmpp/node-expat/issues/78 if you are getting errors about not finding nan.h`.
- node-expat
- xml2json
- xml-object-stream
MIT Licensed
Copyright (c) 2014 Dmitri Voronianski dmitri.voronianski@gmail.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.