If you want to parse multiple files, you have multiple possibilities:
* 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)`.
XML builder usage
-----------------
Since 0.4.0, objects can be also be used to build XML:
```javascript
varxml2js=require('xml2js');
varobj={name:"Super",Surname:"Man",age:23};
varbuilder=newxml2js.Builder();
varxml=builder.buildObject(obj);
```
At the moment, a one to one bi-directional conversion is guaranteed only for
default configuration, except for `attrkey`, `charkey` and `explicitArray` options
you can redefine to your taste. Writing CDATA is supported via setting the `cdata`
option to `true`.
To specify attributes:
```javascript
varxml2js=require('xml2js');
varobj={root:{$:{id:"my id"},_:"my inner text"}};
varbuilder=newxml2js.Builder();
varxml=builder.buildObject(obj);
```
### Adding xmlns attributes
You can generate XML that declares XML namespace prefix / URI pairs with xmlns attributes.
Example declaring a default namespace on the root element:
```javascript
letobj={
Foo:{
$:{
"xmlns":"http://foo.com"
}
}
};
```
Result of `buildObject(obj)`:
```xml
<Fooxmlns="http://foo.com"/>
```
Example declaring non-default namespaces on non-root elements:
```javascript
letobj={
'foo:Foo':{
$:{
'xmlns:foo':'http://foo.com'
},
'bar:Bar':{
$:{
'xmlns:bar':'http://bar.com'
}
}
}
}
```
Result of `buildObject(obj)`:
```xml
<foo:Fooxmlns:foo="http://foo.com">
<bar:Barxmlns:bar="http://bar.com"/>
</foo:Foo>
```
Processing attribute, tag names and values
------------------------------------------
Since 0.4.1 you can optionally provide the parser with attribute name and tag name processors as well as element value processors (Since 0.4.14, you can also optionally provide the parser with attribute value processors):
```javascript
functionnameToUpperCase(name){
returnname.toUpperCase();
}
//transform all attribute and tag names and values to uppercase
parseString(xml,{
tagNameProcessors:[nameToUpperCase],
attrNameProcessors:[nameToUpperCase],
valueProcessors:[nameToUpperCase],
attrValueProcessors:[nameToUpperCase]},
function(err,result){
// processed data
});
```
The `tagNameProcessors` and `attrNameProcessors` options
accept an `Array` of functions with the following signature:
```javascript
function(name){
//do something with `name`
returnname
}
```
The `attrValueProcessors` and `valueProcessors` options
accept an `Array` of functions with the following signature:
```javascript
function(value,name){
//`name` will be the node name or attribute name
//do something with `value`, (optionally) dependent on the node/attr name
returnvalue
}
```
Some processors are provided out-of-the-box and can be found in `lib/processors.js`:
-`normalize`: transforms the name to lowercase.
(Automatically used when `options.normalize` is set to `true`)
-`firstCharLowerCase`: transforms the first character to lower case.
E.g. 'MyTagName' becomes 'myTagName'
-`stripPrefix`: strips the xml namespace prefix. E.g `<foo:Bar/>` will become 'Bar'.
(N.B.: the `xmlns` prefix is NOT stripped.)
-`parseNumbers`: parses integer-like strings as integers and float-like strings as floats
E.g. "0" becomes 0 and "15.56" becomes 15.56
-`parseBooleans`: parses boolean-like strings to booleans
E.g. "true" becomes true and "False" becomes false
Options
=======
Apart from the default settings, there are 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: `''`): what will the value of empty nodes be.
*`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 `true`.
*`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.
*`preserveChildrenOrder` (default `false`): Modifies the behavior of
`explicitChildren` so that the value of the "children" property becomes an
ordered array. When this is `true`, every node will also get a `#name` field
whose value will correspond to the XML nodeName, so that you may iterate
the "children" array and still be able to determine node names. The named
(and potentially unordered) properties are also retained in this
configuration at the same level as the ordered "children" array. Added in
0.4.9.
*`charsAsChildren` (default `false`): Determines whether chars should be
considered children if `explicitChildren` is on. Added in 0.2.5.
All notable changes to this project are documented in this file. This project adheres to [Semantic Versioning](http://semver.org/#semantic-versioning-200).
## [11.0.0] - 2019-02-18
- Calling `end()` with arguments no longer overwrites writer options. See [#120](https://github.com/oozcitak/xmlbuilder-js/issues/120).
- Added writer state and customizable space and endline functions to help customize writer behavior. Also added `openNode` and `closeNode` functions to writer. See [#193](https://github.com/oozcitak/xmlbuilder-js/issues/193).
- Fixed a bug where writer functions would not be called for nodes with a single child node in pretty print mode. See [#195](https://github.com/oozcitak/xmlbuilder-js/issues/195).
- Renamed `elEscape` to `textEscape` in `XMLStringifier`.
- Fixed a bug where empty arrays would produce child nodes. See [#190](https://github.com/oozcitak/xmlbuilder-js/issues/190).
- Removed the `skipNullAttributes` option. `null` attributes are now skipped by default. Added the `keepNullAttributes` option in case someone needs the old behavior.
- Removed the `skipNullNodes` option. `null` nodes are now skipped by default. Added the `keepNullNodes` option in case someone needs the old behavior.
-`undefined` values are now skipped when converting JS objects.
- Renamed stringify functions. See [#194](https://github.com/oozcitak/xmlbuilder-js/issues/194):
*`eleName` -> `name`
*`attName` -> `name`
*`eleText` -> `text`
- Fixed argument order for `attribute` function in the writer. See [#196](https://github.com/oozcitak/xmlbuilder-js/issues/196).
- Added `openAttribute` and `closeAttribute` functions to writer. See [#196](https://github.com/oozcitak/xmlbuilder-js/issues/196).
- Added node types to node objects. Node types and writer states are exported by the module with the `nodeType` and `writerState` properties.
- Fixed a bug where array items would not be correctly converted. See [#159](https://github.com/oozcitak/xmlbuilder-js/issues/159).
- Fixed a bug where mixed-content inside JS objects with `#text` decorator would not be correctly converted. See [#171](https://github.com/oozcitak/xmlbuilder-js/issues/171).
- Fixed a bug where JS objects would not be expanded in callback mode. See [#173](https://github.com/oozcitak/xmlbuilder-js/issues/173).
- Fixed a bug where character validation would not obey document's XML version. Added separate validation for XML 1.0 and XML 1.1 documents. See [#169](https://github.com/oozcitak/xmlbuilder-js/issues/169).
- Fixed a bug where names would not be validated according to the spec. See [#49](https://github.com/oozcitak/xmlbuilder-js/issues/49).
- Renamed `text` property to `value` in comment and cdata nodes to unify the API.
- Removed `doctype` function to prevent name clash with DOM implementation. Use the `dtd` function instead.
- Removed dummy nodes from the XML tree (Those were created while chain-building the tree).
- Renamed `attributes`property to `attribs` to prevent name clash with DOM property with the same name.
- Implemented the DOM standard (read-only) to support XPath lookups. XML namespaces are not currently supported. See [#122](https://github.com/oozcitak/xmlbuilder-js/issues/122).
## [10.1.1] - 2018-10-24
- Fixed an edge case where a null node at root level would be printed although `skipNullNodes` was set. See [#187](https://github.com/oozcitak/xmlbuilder-js/issues/187).
## [10.1.0] - 2018-10-10
- Added the `skipNullNodes` option to skip nodes with null values. See [#158](https://github.com/oozcitak/xmlbuilder-js/issues/158).
## [10.0.0] - 2018-04-26
- Added current indentation level as a parameter to the onData function when in callback mode. See [#125](https://github.com/oozcitak/xmlbuilder-js/issues/125).
- Added name of the current node and parent node to error messages where possible. See [#152](https://github.com/oozcitak/xmlbuilder-js/issues/152). This has the potential to break code depending on the content of error messages.
- Fixed an issue where objects created with Object.create(null) created an error. See [#176](https://github.com/oozcitak/xmlbuilder-js/issues/176).
- Added test builds for node.js v8 and v10.
## [9.0.7] - 2018-02-09
- Simplified regex used for validating encoding.
## [9.0.4] - 2017-08-16
-`spacebeforeslash` writer option accepts `true` as well as space char(s).
## [9.0.3] - 2017-08-15
-`spacebeforeslash` writer option can now be used with XML fragments.
## [9.0.2] - 2017-08-15
- Added the `spacebeforeslash` writer option to add a space character before closing tags of empty elements. See
and [#43](https://github.com/oozcitak/xmlbuilder-js/issues/43).
- Added title case to name conversion options.
## [8.1.0] - 2016-03-29
- Added the callback option to the `begin` export function. When used with a
callback function, the XML document will be generated in chunks and each chunk
will be passed to the supplied function. In this mode, `begin` uses a different
code path and the builder should use much less memory since the entire XML tree
is not kept. There are a few drawbacks though. For example, traversing the document
tree or adding attributes to a node after it is written is not possible. It is
also not possible to remove nodes or attributes.
``` js
varresult='';
builder.begin(function(chunk){result+=chunk;})
.dec()
.ele('root')
.ele('xmlbuilder').up()
.end();
```
- Replaced native `Object.assign` with `lodash.assign` to support old JS engines. See [#111](https://github.com/oozcitak/xmlbuilder-js/issues/111).
## [8.0.0] - 2016-03-25
- Added the `begin` export function. See the wiki for details.
- Added the ability to add comments and processing instructions before and after the root element. Added `commentBefore`, `commentAfter`, `instructionBefore` and `instructionAfter` functions for this purpose.
- Dropped support for old node.js releases. Minimum required node.js version is now 4.0.
## [7.0.0] - 2016-03-21
- Processing instructions are now created as regular nodes. This is a major breaking change if you are using processing instructions. Previously processing instructions were inserted before their parent node. After this change processing instructions are appended to the children of the parent node. Note that it is not currently possible to insert processing instructions before or after the root element.
```js
root.ele('node').ins('pi');
// pre-v7
<?pi?><node/>
// v7
<node><?pi?></node>
```
## [6.0.0] - 2016-03-20
- Added custom XML writers. The default string conversion functions are now collected under the `XMLStringWriter` class which can be accessed by the `stringWriter(options)` function exported by the module. An `XMLStreamWriter` is also added which outputs the XML document to a writable stream. A stream writer can be created by calling the `streamWriter(stream, options)` function exported by the module. Both classes are heavily customizable and the details are added to the wiki. It is also possible to write an XML writer from scratch and use it when calling `end()` on the XML document.
## [5.0.1] - 2016-03-08
- Moved require statements for text case conversion to the top of files to reduce lazy requires.
## [5.0.0] - 2016-03-05
- Added text case option for element names and attribute names. Valid cases are `lower`, `upper`, `camel`, `kebab` and `snake`.
- Attribute and element values are escaped according to the [Canonical XML 1.0 specification](http://www.w3.org/TR/2000/WD-xml-c14n-20000119.html#charescaping). See [#54](https://github.com/oozcitak/xmlbuilder-js/issues/54) and [#86](https://github.com/oozcitak/xmlbuilder-js/issues/86).
- Added the `allowEmpty` option to `end()`. When this option is set, empty elements are not self-closed.
- Added support for [nested CDATA](https://en.wikipedia.org/wiki/CDATA#Nesting). The triad `]]>` in CDATA is now automatically replaced with `]]]]><![CDATA[>`.
## [4.2.1] - 2016-01-15
- Updated lodash dependency to 4.0.0.
## [4.2.0] - 2015-12-16
- Added the `noDoubleEncoding` option to `create()` to control whether existing html entities are encoded.
## [4.1.0] - 2015-11-11
- Added the `separateArrayItems` option to `create()` to control how arrays are handled when converting from objects. e.g.
```js
root.ele({number:["one","two"]});
// with separateArrayItems: true
<number>
<one/>
<two/>
</number>
// with separateArrayItems: false
<number>one</number>
<number>two</number>
```
## [4.0.0] - 2015-11-01
- Removed the `#list` decorator. Array items are now created as child nodes by default.
- Fixed a bug where the XML encoding string was checked partially.
## [3.1.0] - 2015-09-19
-`#list` decorator ignores empty arrays.
## [3.0.0] - 2015-09-10
- Allow `\r`, `\n` and `\t` in attribute values without escaping. See [#86](https://github.com/oozcitak/xmlbuilder-js/issues/86).
## [2.6.5] - 2015-09-09
- Use native `isArray` instead of lodash.
- Indentation of processing instructions are set to the parent element's.
## [2.6.4] - 2015-05-27
- Updated lodash dependency to 3.5.0.
## [2.6.3] - 2015-05-27
- Bumped version because previous release was not published on npm.
## [2.6.2] - 2015-03-10
- Updated lodash dependency to 3.5.0.
## [2.6.1] - 2015-02-20
- Updated lodash dependency to 3.3.0.
## [2.6.0] - 2015-02-20
- Fixed a bug where the `XMLNode` constructor overwrote the super class parent.
- Removed document property from cloned nodes.
- Switched to mocha.js for testing.
## [2.5.2] - 2015-02-16
- Updated lodash dependency to 3.2.0.
## [2.5.1] - 2015-02-09
- Updated lodash dependency to 3.1.0.
- Support all node >= 0.8.
## [2.5.0] - 2015-00-03
- Updated lodash dependency to 3.0.0.
## [2.4.6] - 2015-01-26
- Show more information from attribute creation with null values.
- Added iojs as an engine.
- Self close elements with empty text.
## [2.4.5] - 2014-11-15
- Fixed prepublish script to run on windows.
- Fixed bug in XMLStringifier where an undefined value was used while reporting an invalid encoding value.
- Moved require statements to the top of files to reduce lazy requires. See [#62](https://github.com/oozcitak/xmlbuilder-js/issues/62).
## [2.4.4] - 2014-09-08
- Added the `offset` option to `toString()` for use in XML fragments.
## [2.4.3] - 2014-08-13
- Corrected license in package description.
## [2.4.2] - 2014-08-13
- Dropped performance test and memwatch dependency.
## [2.4.1] - 2014-08-12
- Fixed a bug where empty indent string was omitted when pretty printing. See [#59](https://github.com/oozcitak/xmlbuilder-js/issues/59).
## [2.4.0] - 2014-08-04
- Correct cases of pubID and sysID.
- Use single lodash instead of separate npm modules. See [#53](https://github.com/oozcitak/xmlbuilder-js/issues/53).
- Escape according to Canonical XML 1.0. See [#54](https://github.com/oozcitak/xmlbuilder-js/issues/54).
## [2.3.0] - 2014-07-17
- Convert objects to JS primitives while sanitizing user input.
- Object builder preserves items with null values. See [#44](https://github.com/oozcitak/xmlbuilder-js/issues/44).
- Use modularized lodash functions to cut down dependencies.
- Process empty objects when converting from objects so that we don't throw on empty child objects.
## [2.2.1] - 2014-04-04
- Bumped version because previous release was not published on npm.
## [2.2.0] - 2014-04-04
- Switch to lodash from underscore.
- Removed legacy `ext` option from `create()`.
- Drop old node versions: 0.4, 0.5, 0.6. 0.8 is the minimum requirement from now on.
## [2.1.0] - 2013-12-30
- Removed duplicate null checks from constructors.
- Fixed node count in performance test.
- Added option for skipping null attribute values. See [#26](https://github.com/oozcitak/xmlbuilder-js/issues/26).
- Allow multiple values in `att()` and `ins()`.
- Added ability to run individual performance tests.
- Added flag for ignoring decorator strings.
## [2.0.1] - 2013-12-24
- Removed performance tests from npm package.
## [2.0.0] - 2013-12-24
- Combined loops for speed up.
- Added support for the DTD and XML declaration.
-`clone` includes attributes.
- Added performance tests.
- Evaluate attribute value if function.
- Evaluate instruction value if function.
## [1.1.2] - 2013-12-11
- Changed processing instruction decorator to `?`.
## [1.1.1] - 2013-12-11
- Added processing instructions to JS object conversion.
## [1.1.0] - 2013-12-10
- Added license to package.
-`create()` and `element()` accept JS object to fully build the document.
- Added `nod()` and `n()` aliases for `node()`.
- Renamed `convertAttChar` decorator to `convertAttKey`.
- Ignore empty decorator strings when converting JS objects.
## [1.0.2] - 2013-11-27
- Removed temp file which was accidentally included in the package.
## [1.0.1] - 2013-11-27
- Custom stringify functions affect current instance only.
## [1.0.0] - 2013-11-27
- Added processing instructions.
- Added stringify functions to sanitize and convert input values.
- Added option for headless XML documents.
- Added vows tests.
- Removed Makefile. Using npm publish scripts instead.
- Removed the `begin()` function. `create()` begins the document by creating the root node.
## [0.4.3] - 2013-11-08
- Added option to include surrogate pairs in XML content. See [#29](https://github.com/oozcitak/xmlbuilder-js/issues/29).
- Fixed empty value string representation in pretty mode.
- Added pre and postpublish scripts to package.json.
- Filtered out prototype properties when appending attributes. See [#31](https://github.com/oozcitak/xmlbuilder-js/issues/31).
## [0.4.2] - 2012-09-14
- Removed README.md from `.npmignore`.
## [0.4.1] - 2012-08-31
- Removed `begin()` calls in favor of `XMLBuilder` constructor.
- Added the `end()` function. `end()` is a convenience over `doc().toString()`.
## [0.4.0] - 2012-08-31
- Added arguments to `XMLBuilder` constructor to allow the name of the root element and XML prolog to be defined in one line.
- Soft deprecated `begin()`.
## [0.3.11] - 2012-08-13
- Package keywords are fixed to be an array of values.
## [0.3.10] - 2012-08-13
- Brought back npm package contents which were lost due to incorrect configuration of `package.json` in previous releases.
## [0.3.3] - 2012-07-27
- Implemented `importXMLBuilder()`.
## [0.3.2] - 2012-07-20
- Fixed a duplicated escaping problem on `element()`.
- Fixed a problem with text node creation from empty string.
- Calling `root()` on the document element returns the root element.
-`XMLBuilder` no longer extends `XMLFragment`.
## [0.3.1] - 2011-11-28
- Added guards for document element so that nodes cannot be inserted at document level.
## [0.3.0] - 2011-11-28
- Added `doc()` to return the document element.
## [0.2.2] - 2011-11-28
- Prevent code relying on `up()`'s older behavior to break.
## [0.2.1] - 2011-11-28
- Added the `root()` function.
## [0.2.0] - 2011-11-21
- Added Travis-CI integration.
- Added coffee-script dependency.
- Added insert, traversal and delete functions.
## [0.1.7] - 2011-10-25
- No changes. Accidental release.
## [0.1.6] - 2011-10-25
- Corrected `package.json` bugs link to `url` from `web`.
## [0.1.5] - 2011-08-08
- Added missing npm package contents.
## [0.1.4] - 2011-07-29
- Text-only nodes are no longer indented.
- Added documentation for multiple instances.
## [0.1.3] - 2011-07-27
- Exported the `create()` function to return a new instance. This allows multiple builder instances to be constructed.
- Fixed `u()` function so that it now correctly calls `up()`.
- Fixed typo in `element()` so that `attributes` and `text` can be passed interchangeably.
## [0.1.2] - 2011-06-03
-`ele()` accepts element text.
-`attributes()` now overrides existing attributes if passed the same attribute name.
## [0.1.1] - 2011-05-19
- Added the raw output option.
- Removed most validity checks.
## [0.1.0] - 2011-04-27
-`text()` and `cdata()` now return parent element.
- Attribute values are escaped.
## [0.0.7] - 2011-04-23
- Coerced text values to string.
## [0.0.6] - 2011-02-23
- Added support for XML comments.
- Text nodes are checked against CharData.
## [0.0.5] - 2010-12-31
- Corrected the name of the main npm module in `package.json`.
## [0.0.4] - 2010-12-28
- Added `.npmignore`.
## [0.0.3] - 2010-12-27
- root element is now constructed in `begin()`.
- moved prolog to `begin()`.
- Added the ability to have CDATA in element text.
- Removed unused prolog aliases.
- Removed `builder()` function from main module.
- Added the name of the main npm module in `package.json`.
## [0.0.2] - 2010-11-03
-`element()` expands nested arrays.
- Added pretty printing.
- Added the `up()`, `build()` and `prolog()` functions.
It is also possible to convert objects into nodes:
``` js
builder.create({
root:{
xmlbuilder:{
repo:{
'@type':'git',// attributes start with @
'#text':'git://github.com/oozcitak/xmlbuilder-js.git'// text node
}
}
}
});
```
If you need to do some processing:
``` js
varroot=builder.create('squares');
root.com('f(x) = x^2');
for(vari=1;i<=5;i++)
{
varitem=root.ele('data');
item.att('x',i);
item.att('y',i*i);
}
```
This will result in:
``` xml
<?xml version="1.0"?>
<squares>
<!-- f(x) = x^2 -->
<datax="1"y="1"/>
<datax="2"y="4"/>
<datax="3"y="9"/>
<datax="4"y="16"/>
<datax="5"y="25"/>
</squares>
```
See the [wiki](https://github.com/oozcitak/xmlbuilder-js/wiki) for details and [examples](https://github.com/oozcitak/xmlbuilder-js/wiki/Examples) for more complex examples.