` and its content as result of the `parse`, so pass the `buildPath` option to the `parse`: ```javascript var xamel = require('xamel'), xmlSource = require('fs').readFileAsync('./article.xml'); xamel.parse(xmlSource, { buildPath : 'root/body/article' }, function(err, xml) { if (err !== null) { throw err; } console.dir(JSON.stringify(xml)); }); ``` You can also check the [partial parsing test](https://github.com/nodules/xamel/blob/master/test/parse.js#L25). ## xamel.serialize(nodeset, [options]) * `nodeset` NodeSet to serialize; * `options` parsing options: * `header` – when evaluated to `false` the document will not contain a `` header, `true` by default; * `pretty` – when evaluated to `true` the document will be beautified with indents and line breaks, `false` by default; ## NodeSets and map/reduce Result of `xamel.parse(…)` is a NodeSet. You can think of NodeSet as an array of nodes (internally it's true). NodeSet provides all _non-mutator_ methods of the `Array.prototype`. ### Example of key-value query concatenation XML (query.xml) ```xml Opel Astra 2011 ``` JavaScript ```javascript var xamel = require('xamel'), xmlSource = require('fs').readFileAsync('./query.xml'); function buildQuery(nodeset) { return nodeset.$('query/key').reduce(function(query, key) { return [query, '&', key.attr('name'), '=', key.text()].join(''); }, ''); } xamel.parse(xmlSource, function(err, xml) { if (err !== null) { throw err; } buildQuery(xml); } ); ``` ## NodeSet preserves nodes' order So processing a bad-designed xml, where order of nodes is significant, is completely possible: XML (query.xml) ```xml markOpel modelAstra year2011 ``` JavaScript ```javascript function buildQuery(nodeset) { return nodeset.$('query/*').reduce(function(query, tag) { if (tag.name === 'key') { return [query, '&', tag.text(), '='].join(''); } else { return query + tag.text(); } }, ''); } ``` ## Ok, but why we need a NodeSet? Why not a regular array? NodeSet provides some powerful methods to find, extract and process data. ### find(path), $(path) These methods traverse the tree, trying to find nodes satisfying `path` expression. Result is a NodeSet. `length` property should be used to check if something is found. Path looks pretty much similar to XPath, but it's not completely so. That's the path grammar in BNF: ```bnf ::= | "/"

::= "node()" | "text()" | "comment()" | "cdata()" | "*" | "element()" | ``` As described above, valid paths are: ``` country country/state/city country/*/city */*/city/text() * text() element/text() ... ``` Invalid paths: ``` /country # leading '/' is not allowed country/state/ # trailing '/' is not allowed ./state # '.' are not supported ``` Method `NodeSet#$` was designed as an alias for `NodeSet#find`, but it slightly differs. Internally `NodeSet#$` calls `NodeSet#find`, but method returns concatenated string instead of NodeSet, if last check in the path is `text()`: ```javascript xml.find('article/para/text()') => [ 'Text 1', 'Text of second para', ... ] xml.$('article/para/text()') => 'Text 1Text of second para...' ``` ### text(keepArray = false) Method returns content of text nodes in the NodeSet. Being called without an argument or with a first argument equals `false`, it returns a string (concatenated text nodes content). If not, result is an array of strings. ```javascript nodeset.text(true) => ['1', '2', 'test'] nodeset.text() => '12test' nodeset.text(false) => '12test' ``` ### eq(index) Method returns child node by its index. ```xml

Title

Lorem ipsum…

``` JavaScript ```javascript var nodeset = xml.$('article/h1'), // $ and find return NodeSet title = nodeset.eq(0); // retrieve Tag from NodeSet console.log('Header level: %s', title.name[1]); // use Tag's field ``` ### hasAttr(name) Method filters tags with attribute `name` and returns a new NodeSet. ```xml Home Products About ``` JavaScript ```javascript var currentItemTitle = xml.find('list/item').hasAttr('current').eq(0).text(); ``` ### isAttr(name, value) Filters tags with `name` attribute equals `value` and returns a new NodeSet. ```xml Home Products About ``` JavaScript ```javascript var currentItemTitle = xml.find('list/item').isAttr('current', 'yes').eq(0).text(); ``` ### get(expr) Method filters nodes satisfying `expr` and returns new NodeSet. Argument `expr` is `` as described above in the `NodeSet#find` section. ```xml Pink Floyd - The Fletchers Memorial Home Kids on the slope ``` JavaScript ```javascript var media = xml.$('media').eq(0); media.get('comment()') => NodeSet contains two comments: ' Music ', ' Video ' media.get('item') => NodeSet contains two elements: Pink…, Kids… ``` It looks the same as `NodeSet#find` without traversing through the tree, but `nodeset.get()` is a bit faster than `nodeset.find()`. Method is used internally by `NodeSet#find`. ## Types of nodes ### Text Text nodes are represented by strings. ### Comment Fields: * `comment` represents comment content as a string. Methods: * `toString()` returns `comment` field value. ### Tag Tag is a descendant of NodeSet, all `NodeSet.prototype` methods are available. Fields: * `name` contains XML tag name; * `attrs` is a hash of attributes; * `parent` points to parent tag or a root NodeSet. Methods: * `attr(name)` returns attribute value by name, or null if attribute isn't defined. ### CData Methods: * `getData()` returns CDATA section content; * `toString()` similiar to `getData`; * `toJSON()` returns object `{ cdata : "cdata content …" }`. ## Why such complexity? I just want to translate XML to JSON! ```javascript require('xamel').parse(xmlString, function(err, xml) { if (!err) { console.log( JSON.stringify(xml) ); } }); ``` --- _Source: https://npm.io/package/xamel · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._