An XML/HTML stream reader, now with less suck.
npm install xml-flowDealing with XML data can be frustrating. Especially if you have a whole-lot of it. Most XML readers work on the entire XML document as a String: this can be problematic if you need to read very large XML files. With xml-flow, you can use streams to only load a small part of an XML document into memory at a time.
xml-flow has only one dependency, sax-js. This means it will run nicely on windows environments.
``
$ npm install xml-flow
xml
Bill
1
27
Sally
2
29
Kelly
3
37
`$3
js
var fs = require('fs')
, flow = require('xml-flow')
, inFile = fs.createReadStream('./your-xml-file.xml')
, xmlStream = flow(inFile)
;xmlStream.on('tag:person', function(person) {
console.log(person);
});
`$3
js
{name: 'Bill', id: '1', age: '27'}
{name: 'Sally', id: '2', age: '29'}
{name: 'Kelly', id: '3', age: '37'}
`Features
$3
The above example shows the of an XML document with no attributes. What about the opposite?##### Input
XML
`##### Output
js
{name: 'Bill', id: '1', age: '27'}
{name: 'Sally', id: '2', age: '29'}
{name: 'Kelly', id: '3', age: '37'}
`$3
When you have tags that have both Attributes and subtags, here's how the output looks:##### Input
XML
Kelly likes to ride ponies.
`##### Output
js
{
$attrs: {name: 'Bill', id: '1', age: '27'},
friend:'2'
}
{
$attrs: {name: 'Sally', id: '2', age: '29'},
friend: ['1', '3']
}
{
$attrs: {name: 'Kelly', id: '3', age: '37'},
friend: '2',
$text: 'Kelly likes to ride ponies.'
}
`$3
If you need to keep track of sub-tag order within a tag, or if it makes sense to have a more markup-style object model, here's how it works:##### Input
HTML
Title
Some introduction
Subtitle
Some more text
This text is not inside a p-tag.
`##### Output
js
{
$attrs: {class: 'science'},
$markup: [
{$name: 'h1', $text: 'Title'},
{$name: 'p', $text: 'Some Introduction'},
{$name: 'h2', $text: 'Subtitle'},
{$name: 'p', $text: 'Some more text'},
'This text is not inside a p-tag.'
]
}
`Options
You may add a second argument when calling the function, as . All are optional:
* strict - Boolean. Default = false. Refer to sax-js documentation for more info.
* lowercase - Boolean. Default = true. When not in strict mode, all tags are lowercased, or uppercased when set to false.
* trim - Boolean. Default = true. Whether or not to trim leading and trailing whitespace from text
* normalize - Boolean. Default = true. Turns all whitespace into a single space.
* preserveMarkup - One of flow.ALWAYS, flow.SOMETIMES (default), or flow.NEVER. When set to ALWAYS, All subtags and text are stored in the $markup property with their original order preserved. When set to NEVER, all subtags are collected as separate properties. When set to SOMETIMES, markup is preserved only when subtags have non-contiguous repetition.
* simplifyNodes - Boolean. Default = true. Whether to drop empty $attrs, pull properties out of the $attrs when there are no subtags, or to only use a String instead of an object when $text is the only property.
useArrays - One of flow.ALWAYS, flow.SOMETIMES (default), or flow.NEVER. When set to ALWAYS, All subtags and text are enclosed in arrays, even if there's only one found. When set to NEVER, only the first instance of a subtag or text node are kept. When set to SOMETIMES, arrays are used only when multiple items are found. NOTE:* When set to NEVER, preserveMarkup is ignored.
* cdataAsText - Boolean. Default = false. Appends CDATA text to other nearby text instead of putting it into its own $cdata property. NOTE: If you plan to run the toXml() function on data that has CDATA in it, you might. Consider a more robust escape function than what is provided. See below for more information.Events
All events can be listened to via common nodeJS EventEmitter syntax.tag:< - Fires when any < is parsed. Note that this is case sensitive. If the lowercase option is set, make sure you listen to lowercase tag names. If the strict option is set, match the case of the tags in your document.end - Fires when the end of the stream has been reached.error - Fires when there are errors.query:< - Coming soon...toXml Utility
toXml(node, options) - Returns a string, XML-encoding of an object. Encodes $name, $attrs, $text, and $markup as you would expect. the following options are available:*
indent – How to indent tags for pretty-printing, use ' ' for two-spaces, or '\t' for tabs. If no indent value is provided, output will not be pretty-printed.
* selfClosing – Whether to self close tags (like instead of ) whenever possible. Defaults to true.
* escape – Optionally provide an escape function for all text, to prevent malformed XML. As a default, a very simplistic escape function has been provided. You can provide a more robust escape function that suits your needs. For example, take a look at he. To turn escaping off, provide a simple, non-escaping function like this: function(str) { return str; }`MIT
[npm-image]: https://img.shields.io/npm/v/xml-flow.svg?style=flat
[npm-url]: https://npmjs.org/package/xml-flow
[travis-image]: https://img.shields.io/travis/matthewmatician/xml-flow.svg?style=flat
[travis-url]: https://travis-ci.org/matthewmatician/xml-flow
[david-image]: https://img.shields.io/david/matthewmatician/xml-flow.svg?style=flat