Initial commit
This commit is contained in:
Luis Fernando Molina committed
commit
ec49fedc45
1288 files changed
+226749
No files matched your search
+248
@@ -0,0 +1,248 @@
|
||||
node-xml2js
|
||||
===========
|
||||
|
||||
Ever had the urge to parse XML? And wanted to access the data in some sane,
|
||||
easy way? Don't want to compile a C parser, for whatever reason? Then xml2js is
|
||||
what you're looking for!
|
||||
|
||||
Description
|
||||
===========
|
||||
|
||||
Simple XML to JavaScript object converter. Uses
|
||||
[sax-js](https://github.com/isaacs/sax-js/).
|
||||
|
||||
Note: If you're looking for a full DOM parser, you probably want
|
||||
[JSDom](https://github.com/tmpvar/jsdom).
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Simplest way to install `xml2js` is to use [npm](http://npmjs.org), just `npm
|
||||
install xml2js` which will download xml2js and all dependencies.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
No extensive tutorials required because you are a smart developer! The task of
|
||||
parsing XML should be an easy one, so let's make it so! Here's some examples.
|
||||
|
||||
Shoot-and-forget usage
|
||||
----------------------
|
||||
|
||||
You want to parse XML as simple and easy as possible? It's dangerous to go
|
||||
alone, take this:
|
||||
|
||||
```javascript
|
||||
var parseString = require('xml2js').parseString;
|
||||
var xml = "<root>Hello xml2js!</root>"
|
||||
parseString(xml, function (err, result) {
|
||||
console.dir(result);
|
||||
});
|
||||
```
|
||||
|
||||
Can't get easier than this, right? This works starting with `xml2js` 0.2.3.
|
||||
With CoffeeScript it looks like this:
|
||||
|
||||
```coffeescript
|
||||
parseString = require('xml2js').parseString
|
||||
xml = "<root>Hello xml2js!</root>"
|
||||
parseString xml, (err, result) ->
|
||||
console.dir result
|
||||
```
|
||||
|
||||
If you need some special options, fear not, `xml2js` supports a number of
|
||||
options (see below), you can specify these as second argument:
|
||||
|
||||
```javascript
|
||||
parseString(xml, {trim: true}, function (err, result) {
|
||||
});
|
||||
```
|
||||
|
||||
Simple as pie usage
|
||||
-------------------
|
||||
|
||||
That's right, if you have been using xml-simple or a home-grown
|
||||
wrapper, this is was added in 0.1.11 just for you:
|
||||
|
||||
```javascript
|
||||
var fs = require('fs'),
|
||||
xml2js = require('xml2js');
|
||||
|
||||
var parser = new xml2js.Parser();
|
||||
fs.readFile(__dirname + '/foo.xml', function(err, data) {
|
||||
parser.parseString(data, function (err, result) {
|
||||
console.dir(result);
|
||||
console.log('Done');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Look ma, no event listeners!
|
||||
|
||||
You can also use `xml2js` from
|
||||
[CoffeeScript](http://jashkenas.github.com/coffee-script/), further reducing
|
||||
the clutter:
|
||||
|
||||
```coffeescript
|
||||
fs = require 'fs',
|
||||
xml2js = require 'xml2js'
|
||||
|
||||
parser = new xml2js.Parser()
|
||||
fs.readFile __dirname + '/foo.xml', (err, data) ->
|
||||
parser.parseString data, (err, result) ->
|
||||
console.dir result
|
||||
console.log 'Done.'
|
||||
```
|
||||
|
||||
But what happens if you forget the `new` keyword to create a new `Parser`? In
|
||||
the middle of a nightly coding session, it might get lost, after all. Worry
|
||||
not, we got you covered! Starting with 0.2.8 you can also leave it out, in
|
||||
which case `xml2js` will helpfully add it for you, no bad surprises and
|
||||
inexplicable bugs!
|
||||
|
||||
"Traditional" usage
|
||||
-------------------
|
||||
|
||||
Alternatively you can still use the traditional `addListener` variant that was
|
||||
supported since forever:
|
||||
|
||||
```javascript
|
||||
var fs = require('fs'),
|
||||
xml2js = require('xml2js');
|
||||
|
||||
var parser = new xml2js.Parser();
|
||||
parser.addListener('end', function(result) {
|
||||
console.dir(result);
|
||||
console.log('Done.');
|
||||
});
|
||||
fs.readFile(__dirname + '/foo.xml', function(err, data) {
|
||||
parser.parseString(data);
|
||||
});
|
||||
```
|
||||
|
||||
If you want to parse multiple files, you have multiple possibilites:
|
||||
|
||||
* You can create one `xml2js.Parser` per file. That's the recommended one
|
||||
and is promised to always *just work*.
|
||||
* You can call `reset()` on your parser object.
|
||||
* You can hope everything goes well anyway. This behaviour is not
|
||||
guaranteed work always, if ever. Use option #1 if possible. Thanks!
|
||||
|
||||
So you wanna some JSON?
|
||||
-----------------------
|
||||
|
||||
Just wrap the `result` object in a call to `JSON.stringify` like this
|
||||
`JSON.stringify(result)`. You get a string containing the JSON representation
|
||||
of the parsed object that you can feed to JSON-hungry consumers.
|
||||
|
||||
Displaying results
|
||||
------------------
|
||||
|
||||
You might wonder why, using `console.dir` or `console.log` the output at some
|
||||
level is only `[Object]`. Don't worry, this is not because xml2js got lazy.
|
||||
That's because Node uses `util.inspect` to convert the object into strings and
|
||||
that function stops after `depth=2` which is a bit low for most XML.
|
||||
|
||||
To display the whole deal, you can use `console.log(util.inspect(result, false,
|
||||
null))`, which displays the whole result.
|
||||
|
||||
So much for that, but what if you use
|
||||
[eyes](https://github.com/cloudhead/eyes.js) for nice colored output and it
|
||||
truncates the output with `…`? Don't fear, there's also a solution for that,
|
||||
you just need to increase the `maxLength` limit by creating a custom inspector
|
||||
`var inspect = require('eyes').inspector({maxLength: false})` and then you can
|
||||
easily `inspect(result)`.
|
||||
|
||||
Options
|
||||
=======
|
||||
|
||||
Apart from the default settings, there is a number of options that can be
|
||||
specified for the parser. Options are specified by ``new Parser({optionName:
|
||||
value})``. Possible options are:
|
||||
|
||||
* `attrkey` (default: `$`): Prefix that is used to access the attributes.
|
||||
Version 0.1 default was `@`.
|
||||
* `charkey` (default: `_`): Prefix that is used to access the character
|
||||
content. Version 0.1 default was `#`.
|
||||
* `explicitCharkey` (default: `false`)
|
||||
* `trim` (default: `false`): Trim the whitespace at the beginning and end of
|
||||
text nodes.
|
||||
* `normalizeTags` (default: `false`): Normalize all tag names to lowercase.
|
||||
* `normalize` (default: `false`): Trim whitespaces inside text nodes.
|
||||
* `explicitRoot` (default: `true`): Set this if you want to get the root
|
||||
node in the resulting object.
|
||||
* `emptyTag` (default: `undefined`): what will the value of empty nodes be.
|
||||
Default is `{}`.
|
||||
* `explicitArray` (default: `true`): Always put child nodes in an array if
|
||||
true; otherwise an array is created only if there is more than one.
|
||||
* `ignoreAttrs` (default: `false`): Ignore all XML attributes and only create
|
||||
text nodes.
|
||||
* `mergeAttrs` (default: `false`): Merge attributes and child elements as
|
||||
properties of the parent, instead of keying attributes off a child
|
||||
attribute object. This option is ignored if `ignoreAttrs` is `false`.
|
||||
* `validator` (default `null`): You can specify a callable that validates
|
||||
the resulting structure somehow, however you want. See unit tests
|
||||
for an example.
|
||||
* `xmlns` (default `false`): Give each element a field usually called '$ns'
|
||||
(the first character is the same as attrkey) that contains its local name
|
||||
and namespace URI.
|
||||
* `explicitChildren` (default `false`): Put child elements to separate
|
||||
property. Doesn't work with `mergeAttrs = true`. If element has no children
|
||||
then "children" won't be created. Added in 0.2.5.
|
||||
* `childkey` (default `$$`): Prefix that is used to access child elements if
|
||||
`explicitChildren` is set to `true`. Added in 0.2.5.
|
||||
* `charsAsChildren` (default `false`): Determines whether chars should be
|
||||
considered children if `explicitChildren` is on. Added in 0.2.5.
|
||||
* `async` (default `false`): Should the callbacks be async? This *might* be
|
||||
an incompatible change if your code depends on sync execution of callbacks.
|
||||
xml2js 0.3 might change this default, so the recommendation is to not
|
||||
depend on sync execution anyway. Added in 0.2.6.
|
||||
* `strict` (default `true`): Set sax-js to strict or non-strict parsing mode.
|
||||
Defaults to `true` which is *highly* recommended, since parsing HTML which
|
||||
is not well-formed XML might yield just about anything. Added in 0.2.7.
|
||||
|
||||
Updating to new version
|
||||
=======================
|
||||
|
||||
Version 0.2 changed the default parsing settings, but version 0.1.14 introduced
|
||||
the default settings for version 0.2, so these settings can be tried before the
|
||||
migration.
|
||||
|
||||
```javascript
|
||||
var xml2js = require('xml2js');
|
||||
var parser = new xml2js.Parser(xml2js.defaults["0.2"]);
|
||||
```
|
||||
|
||||
To get the 0.1 defaults in version 0.2 you can just use
|
||||
`xml2js.defaults["0.1"]` in the same place. This provides you with enough time
|
||||
to migrate to the saner way of parsing in xml2js 0.2. We try to make the
|
||||
migration as simple and gentle as possible, but some breakage cannot be
|
||||
avoided.
|
||||
|
||||
So, what exactly did change and why? In 0.2 we changed some defaults to parse
|
||||
the XML in a more universal and sane way. So we disabled `normalize` and `trim`
|
||||
so xml2js does not cut out any text content. You can reenable this at will of
|
||||
course. A more important change is that we return the root tag in the resulting
|
||||
JavaScript structure via the `explicitRoot` setting, so you need to access the
|
||||
first element. This is useful for anybody who wants to know what the root node
|
||||
is and preserves more information. The last major change was to enable
|
||||
`explicitArray`, so everytime it is possible that one might embed more than one
|
||||
sub-tag into a tag, xml2js >= 0.2 returns an array even if the array just
|
||||
includes one element. This is useful when dealing with APIs that return
|
||||
variable amounts of subtags.
|
||||
|
||||
Running tests, development
|
||||
==========================
|
||||
|
||||
[](https://travis-ci.org/Leonidas-from-XIV/node-xml2js)
|
||||
|
||||
The development requirements are handled by npm, you just need to install them.
|
||||
We also have a number of unit tests, they can be run using `npm test` directly
|
||||
from the project root. This runs zap to discover all the tests and execute
|
||||
them.
|
||||
|
||||
If you like to contribute, keep in mind that xml2js is written in CoffeeScript,
|
||||
so don't develop on the JavaScript files that are checked into the repository
|
||||
for convenience reasons. Also, please write some unit test to check your
|
||||
behaviour and if it is some user-facing thing, add some documentation to this
|
||||
README, so people will know it exists. Thanks in advance!
|
||||
Reference in new issue
Block a user