1 | # js2xmlparser #
|
2 |
|
3 | [![Build Status](https://travis-ci.org/michaelkourlas/node-js2xmlparser.svg?branch=master)](https://travis-ci.org/michaelkourlas/node-js2xmlparser)
|
4 | [![npm version](https://badge.fury.io/js/js2xmlparser.svg)](https://badge.fury.io/js/js2xmlparser)
|
5 |
|
6 | ## Overview ##
|
7 |
|
8 | js2xmlparser is a Node.js module that parses JavaScript objects into XML.
|
9 |
|
10 | ## Features ##
|
11 |
|
12 | Since XML is a data-interchange format, js2xmlparser is designed primarily for
|
13 | JSON-type objects, arrays and primitive data types, like many of the other
|
14 | JavaScript to XML parsers currently available for Node.js.
|
15 |
|
16 | However, js2xmlparser is capable of parsing any object, including native
|
17 | JavaScript objects such as `Date` and `RegExp`, by taking advantage of each
|
18 | object's `toString` function or, if this function does not exist, the `String`
|
19 | constructor.
|
20 |
|
21 | js2xmlparser also has support for the `Map` and `Set` objects introduced in
|
22 | ECMAScript 2015, treating them as JSON-type objects and arrays respectively.
|
23 | Support for `Map`s is necessary to generate XML with elements in a specific
|
24 | order, since JSON-type objects do not guarantee insertion order. `Map` keys are
|
25 | always converted to strings using the method described above.
|
26 |
|
27 | js2xmlparser also supports a number of constructs unique to XML:
|
28 |
|
29 | * attributes (through an attribute property in objects)
|
30 | * mixed content (through value properties in objects)
|
31 | * multiple elements with the same name (through arrays)
|
32 |
|
33 | js2xmlparser can also pretty-print the XML it outputs.
|
34 |
|
35 | ## Installation ##
|
36 |
|
37 | The easiest way to install js2xmlparser is using npm:
|
38 |
|
39 | ```
|
40 | npm install js2xmlparser
|
41 | ```
|
42 |
|
43 | You can also build js2xmlparser from source using npm:
|
44 |
|
45 | ```
|
46 | git clone https://github.com/michaelkourlas/node-js2xmlparser.git
|
47 | npm install
|
48 | npm run-script build
|
49 | ```
|
50 |
|
51 | The `build` script will build the production variant of js2xmlparser, run all
|
52 | tests, and build the documentation.
|
53 |
|
54 | You can build the production variant without running tests using the script
|
55 | `prod`. You can also build the development version using the script `dev`.
|
56 | The only difference between the two is that the development version includes
|
57 | source maps.
|
58 |
|
59 | ## Usage ##
|
60 |
|
61 | The documentation for the current version is available [here](http://www.kourlas.com/node-js2xmlparser/docs/4.0.1/).
|
62 |
|
63 | You can also build the documentation using npm:
|
64 |
|
65 | ```
|
66 | npm run-script docs
|
67 | ```
|
68 |
|
69 | ## Examples ##
|
70 |
|
71 | The following example illustrates the basic usage of js2xmlparser:
|
72 |
|
73 | ```javascript
|
74 | var js2xmlparser = require("js2xmlparser");
|
75 |
|
76 | var obj = {
|
77 | "firstName": "John",
|
78 | "lastName": "Smith",
|
79 | "dateOfBirth": new Date(1964, 7, 26),
|
80 | "address": {
|
81 | "@": {
|
82 | "type": "home"
|
83 | },
|
84 | "streetAddress": "3212 22nd St",
|
85 | "city": "Chicago",
|
86 | "state": "Illinois",
|
87 | "zip": 10000
|
88 | },
|
89 | "phone": [
|
90 | {
|
91 | "@": {
|
92 | "type": "home"
|
93 | },
|
94 | "#": "123-555-4567"
|
95 | },
|
96 | {
|
97 | "@": {
|
98 | "type": "cell"
|
99 | },
|
100 | "#": "890-555-1234"
|
101 | },
|
102 | {
|
103 | "@": {
|
104 | "type": "work"
|
105 | },
|
106 | "#": "567-555-8901"
|
107 | }
|
108 | ],
|
109 | "email": "john@smith.com"
|
110 | };
|
111 |
|
112 | console.log(js2xmlparser.parse("person", obj));
|
113 | ```
|
114 |
|
115 | This example produces the following XML:
|
116 |
|
117 | ```xml
|
118 | <?xml version='1.0'?>
|
119 | <person>
|
120 | <firstName>John</firstName>
|
121 | <lastName>Smith</lastName>
|
122 | <dateOfBirth>Wed Aug 26 1964 00:00:00 GMT-0400 (Eastern Summer Time)</dateOfBirth>
|
123 | <address type='home'>
|
124 | <streetAddress>3212 22nd St</streetAddress>
|
125 | <city>Chicago</city>
|
126 | <state>Illinois</state>
|
127 | <zip>10000</zip>
|
128 | </address>
|
129 | <phone type='home'>123-555-4567</phone>
|
130 | <phone type='cell'>890-555-1234</phone>
|
131 | <phone type='work'>567-555-8901</phone>
|
132 | <email>john@smith.com</email>
|
133 | </person>
|
134 | ```
|
135 |
|
136 | Additional examples can be found in the examples directory.
|
137 |
|
138 | ## Tests ##
|
139 |
|
140 | js2xmlparser includes a set of tests to verify core functionality. You can run
|
141 | the tests using npm:
|
142 |
|
143 | ```
|
144 | npm run-script test-prod
|
145 | ```
|
146 |
|
147 | The only difference between the `test-prod` and `test-dev` scripts is that the
|
148 | development version includes source maps.
|
149 |
|
150 | ## License ##
|
151 |
|
152 | js2xmlparser is licensed under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).
|
153 | Please see the LICENSE.md file for more information.
|