ahmad-module 1.0.0

package/xml2js/README.md

@@ -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
+==========================
+
+[![Build Status](https://secure.travis-ci.org/Leonidas-from-XIV/node-xml2js.png?branch=master)](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!