pixl-xml - npm Package Compare versions

Comparing version 1.0.7 to 1.0.8

package.json

 {
   "name": "pixl-xml",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "A simple module for parsing and composing XML.",
@@ -5,0 +5,0 @@ "author": "Joseph Huckaby <[e-mail]>",

README.md

@@ -28,2 +28,6 @@ # Overview
 
+# Simplified API
+
+The simplified API provides basic `parse()` and `stringify()` functions for parsing and serializing XML.
+
 Parse some XML by passing a string to `XML.parse()`:
@@ -192,9 +196,58 @@
 
-## Utility Functions
+# Object-Oriented API
 
-Here are a few utility functions you can use:
+In addition to the [Simplified API](#simplified-api), an object-oriented API is also available.  Using this, you instantiate an `XML.Parser` class instance, and use that to parse, manipulate and serialize XML.  The constructor accepts up to two arguments, the raw XML string, and an optional object with configuration options.
 
-### encodeEntities
+After constructing the `XML.Parser` object, and no error was thrown, call `getTree()` to get a reference to the simplified XML structure in memory, manipulate it if you want, then call `compose()` to serialize the object tree back into XML.
 
+The main reason for using this API is that it preserves any PI (Processing Instructions) and DTD (Document Type Definition) elements in the source XML file, and they will be serialized into the output.  Example:
+
+```js
+var xml_string = '<?xml version="1.0" encoding="UTF-8"?><Document>' + 
+	'<Simple>Hello</Simple>' + 
+	'<Node Key="Value">Complex</Node>' + 
+	'</Document>';
+
+var parser = null;
+try {
+	parser = new XML.Parser( xml_string, { preserveAttributes: true } );
+}
+catch (err) {
+	throw err;
+}
+
+var doc = parser.getTree();
+doc.Simple = "Hello, I changed this.";
+
+console.log( parser.compose() );
 ```
+
+This would produce the following output:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Document>
+	<Node Key="Value">Complex</Node>
+	<Simple>Hello, I changed this.</Simple>
+</Document>
+```
+
+Notice that the PI element with its `encoding` attribute was preserved and serialized.
+
+To manipulate the PI nodes, access the `piNodeList` property.  It is an array of strings, each one representing one raw PI node sans the surrounding angle brackets, e.g. `?xml version="1.0"?`.  Similarly, any DTD nodes are stored in the `dtdNodeList` property (also an array).  Feel free to change these to customize your serialized XML document.
+
+```js
+parser.piNodeList = [ '?xml version="1.0" encoding="UTF-8"?' ];
+parser.dtdNodeList = [ '!DOCTYPE MyAppConfig SYSTEM "/dtds/AppConfig.dtd"' ];
+
+console.log( parser.compose() );
+```
+
+# Utility Functions
+
+Here are a few utility functions that are provided in the package:
+
+## encodeEntities
+
+```
 STRING encodeEntities( STRING )
@@ -211,3 +264,3 @@ ```
 
-### encodeAttribEntities
+## encodeAttribEntities
 
@@ -226,3 +279,3 @@ ```
 
-### decodeEntities
+## decodeEntities
 
@@ -241,3 +294,3 @@ ```
 
-### alwaysArray
+## alwaysArray
 
@@ -254,3 +307,3 @@ ```
 
-### hashKeysToArray
+## hashKeysToArray
 
@@ -273,3 +326,3 @@ ```
 
-### isaHash
+## isaHash
 
@@ -287,3 +340,3 @@ ```
 
-### isaArray
+## isaArray
 
@@ -301,3 +354,3 @@ ```
 
-### numKeys
+## numKeys
 
@@ -315,3 +368,3 @@ ```
 
-### firstKey
+## firstKey
 
@@ -318,0 +371,0 @@ ```

xml.js

@@ -37,3 +37,3 @@ /*
 
-var XML = exports.XML = function XML(args) {
+var XML = exports.XML = exports.Parser = function XML(args, opts) {
 	// class constructor for XML parser class
@@ -47,2 +47,7 @@ // pass in args hash or text to parse
 	
+	// options may be 2nd argument as well
+	if (opts) {
+		for (var key in opts) this[key] = opts[key];
+	}
+	
 	// stringify buffers
@@ -390,3 +395,6 @@ if (this.text instanceof Buffer) {
 	// compose tree back into XML
-	var raw = compose_xml( this.tree, this.documentNodeName );
+	var tree = this.tree;
+	if (this.preserveDocumentNode) tree = tree[this.documentNodeName];
+	
+	var raw = compose_xml( tree, this.documentNodeName );
 	var body = raw.substring( raw.indexOf("\n") + 1, raw.length );
@@ -393,0 +401,0 @@ var xml = '';

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

29933

increased by8.58%

Lines of code

519

increased by1.17%

Number of lines in readme file

400

increased by15.27%

No dependency changes