Xamel provides an easy way to extract data from XML using XPath-like expressions and map/reduce operations. It's designed to be fast and memory-friendly.
Quick start
var xamel = ; xamel;
xamel.parse(xml, [options], callback)
xml
string contains XML to parse;options
hash of parsing options, includes sax options, incapsulates sax paramstrict
as an option, and two xamel-specific options:buildPath
cdata
– if evaluated totrue
thenparse
process CDATA sections,false
by default;
callback
called when parsing done, passes error or null as the first argument and NodeSet as the second argument.
buildPath
Lets take an example:
XML (article.xml)
... ...
Suppose, you want only <article>
and its content as result of the parse
, so pass the buildPath
option to the parse
:
var xamel = xmlSource = ; xamel;
You can also check the partial parsing test.
xamel.serialize(nodeset, [options])
nodeset
NodeSet to serialize;options
parsing options:header
– when evaluated tofalse
the document will not contain a<?xml?>
header,true
by default;pretty
– when evaluated totrue
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)
Opel Astra 2011
JavaScript
var xamel = xmlSource = ; { return nodeset;} xamel;
NodeSet preserves nodes' order
So processing a bad-designed xml, where order of nodes is significant, is completely possible:
XML (query.xml)
markOpel modelAstra year2011
JavaScript
{ return nodeset;}
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:
<path> ::= <node-check> | <path> "/" <node-check><node-check> ::= "node()" | "text()" | "comment()" | "cdata()" | "*" | "element()" | <xml-tag-name>
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 <node-check>
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()
:
xml 'Text 1' 'Text of second para' ... xml '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.
nodesettexttrue '1' '2' 'test'nodesettext '12test'nodesettextfalse '12test'
eq(index)
Method returns child node by its index.
Title Lorem ipsum…
JavaScript
var nodeset = xml // $ and find return NodeSet title = nodeset; // retrieve Tag from NodeSet console; // use Tag's field
hasAttr(name)
Method filters tags with attribute name
and returns a new NodeSet.
Home Products About
JavaScript
var currentItemTitle = xmltext;
isAttr(name, value)
Filters tags with name
attribute equals value
and returns a new NodeSet.
Home Products About
JavaScript
var currentItemTitle = xmltext;
get(expr)
Method filters nodes satisfying expr
and returns new NodeSet.
Argument expr
is <node-check>
as described above in the NodeSet#find
section.
<!-- Music --> Pink Floyd - The Fletchers Memorial Home <!-- Video --> Kids on the slope
JavaScript
var media = xml; media NodeSet contains two comments: ' Music ' ' Video 'media NodeSet contains two elements: <item>Pink…</item> <item>Kids…</item>
It looks the same as NodeSet#find
without traversing through the tree,
but nodeset.get(<CHECK>)
is a bit faster than nodeset.find(<CHECK>)
.
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()
returnscomment
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 togetData
;toJSON()
returns object{ cdata : "cdata content …" }
.
Why such complexity? I just want to translate XML to JSON!
;