README
Super small (~60 LOC) library for retrieving values and attributes
from the XML AST generated by xml-reader
with an easy-to-use jQuery-like interface.
Install
npm install --save xml-query
Usage
Reading xml streams/strings
The following XML will be used to illustrate all examples
<message id="1001" date="2016-06-19">
<from>Bob</from>
<to>Alice</to>
<subject>Hello</subject>
<body>Bla bla bla</body>
</message>
Let's read the XML using xml-reader.
const XmlReader = require('xml-reader');
const xml =
`<message id="1001" date="2016-06-19">
<from>Bob</from>
<to>Alice</to>
<subject>Hello</subject>
<body>Bla bla bla</body>
</message>`;
const ast = XmlReader.parseSync(xml);
xmlQuery()
const xmlQuery = require('xml-query');
// creating from single ast
const xq = xmlQuery(ast);
// creating from an array of asts
const xq = xmlQuery([ast, ...more]);
.get()
Retrieve one of the elements.
xmlQuery(ast).find('body').get(2); // returns the `subject` node
.find()
Find by name. Including top level nodes and all its children.
xmlQuery(ast).find('body'); // xmlQuery containing the body element
.has()
Returns true
if it has the given element. Faster than find()
because it stops on first occurence.
xmlQuery(ast).has('body'); // true
.attr()
Get all attributes. If a name is provided, it returns the value for that key.
xmlQuery(ast).attr(); // {id: '1001', date: '2016-06-19'}
xmlQuery(ast).attr('id'); // '1001'
.children()
Returns a new xmlQuery object containing the children of the top level elements.
xmlQuery(ast).children();
.each()
Iterate over a xmlQuery object, executing a function for each element.
xmlQuery(ast).each(node => console.log(node.name));
// from
// to
// subject
// body
.map()
Iterate over a xmlQuery object, executing a function for each element. Returns the results in an array.
xmlQuery(ast).map(node => node.name); // ['from', 'to', 'subject', 'body']
.prop()
Get the value of a property for the first element in the set.
xmlQuery(ast).prop('name'); // 'message'
.text()
Get the combined text contents of each element, including their descendants
xmlQuery(ast).find('subject').text(); // 'hello'
.eq()
Returns a new XmlQuery object for the selected element by index
xmlQuery(ast).children().eq(2); // xmlQuery containing the 'subject' node
.first()
Returns a new XmlQuery object for the first element. Same as .eq(0)
xmlQuery(ast).children().first(); // xmlQuery containing the 'from' node
.last()
Returns a new XmlQuery object for the last element. Same as .eq(length - 1)
xmlQuery(ast).children().last(); // xmlQuery containing the 'body' node
.length
Number of elements. Returns the same result as .size()
xmlQuery(ast).children().length; // 4
.size()
Number of elements. Returns the same result as .length
xmlQuery(ast).children().size(); // 4
License
MIT