docs: Reference alternate XML parser (#345)

Signed-off-by: Wyatt Teeter <teeterwyatt@gmail.com>
Signed-off-by: xWyatt <wteeter@ppi-global.com>

README.md

@@ -47,11 +47,11 @@ XMLSERVICE will run the command and respond with XML output.
 </myscript>
 ```
 
-`itoolkit` can run the same CL command with:
+`itoolkit`, with the help of an XML parser, can run the same CL command with:
 
 ```js
 const { Connection, CommandCall } = require('itoolkit');
-const { parseString } = require('xml2js');
+const { XMLParser } = require('fast-xml-parser');
 
 const connection = new Connection({
   transport: 'ssh',
@@ -66,12 +66,11 @@ connection.run((error, xmlOutput) => {
   if (error) {
     throw error;
   }
-  parseString(xmlOutput, (parseError, result) => {
-    if (parseError) {
-      throw parseError;
-    }
-    console.log(JSON.stringify(result));
-  });
+
+  const Parser = new XMLParser();
+  const result = Parser.parse(xmlOutput);
+
+  console.log(JSON.stringify(result));
 });
 ```
 

docs/examples/cosine.js

@@ -1,5 +1,5 @@
 const { Connection, ProgramCall } = require('itoolkit');
-const { parseString } = require('xml2js');
+const { XMLParser } = require('fast-xml-parser');
 
 const conn = new Connection({
   transport: 'ssh',
@@ -18,10 +18,9 @@ conn.run((error, xmlOutput) => {
   if (error) {
     throw error;
   }
-  parseString(xmlOutput, (parseError, result) => {
-    if (parseError) {
-      throw parseError;
-    }
-    console.log(result.myscript.pgm[0].return[0].data[0]._); // 1
-  });
+
+  const Parser = new XMLParser();
+  const result = Parser.parse(xmlOutput);
+
+  console.log(result.myscript.pgm.return.data); // 1
 });

docs/examples/qusrobjd.js

@@ -1,5 +1,5 @@
 const { Connection, ProgramCall } = require('itoolkit');
-const { parseString } = require('xml2js');
+const { XMLParser } = require('fast-xml-parser');
 
 const conn = new Connection({
   transport: 'ssh',
@@ -71,10 +71,9 @@ conn.run((error, xmlOutput) => {
   if (error) {
     throw error;
   }
-  parseString(xmlOutput, (parseError, result) => {
-    if (parseError) {
-      throw parseError;
-    }
-    console.log(JSON.stringify(result));
-  });
+
+  const Parser = new XMLParser();
+  const result = Parser.parse(result);
+
+  console.log(JSON.stringify(result));
 });

docs/examples/rtvjoba.js

@@ -1,5 +1,5 @@
 const { Connection, CommandCall } = require('itoolkit');
-const { parseString } = require('xml2js');
+const { XMLParser } = require('fast-xml-parser');
 
 
 const connection = new Connection({
@@ -15,10 +15,9 @@ connection.run((error, xmlOutput) => {
   if (error) {
     throw error;
   }
-  parseString(xmlOutput, (parseError, result) => {
-    if (parseError) {
-      throw parseError;
-    }
-    console.log(JSON.stringify(result));
-  });
+
+  const Parser = new XMLParser();
+  const result = Parser.parse(xmlOutput);
+
+  console.log(JSON.stringify(result));
 });

docs/migratation-guide-v1.0.rst

@@ -20,13 +20,13 @@ Sync Mode Operations
 ``iConn.run()`` no longer supports sync mode. Sync mode is not reccommended and since it did not work properly it was removed.
 See (`#32 <https://github.com/IBM/nodejs-itoolkit/issues/32>`__) for more details.
 
-``iConn.setTimeout()`` is removed. This function was used to set the timeout for ``iConn.run`` 
+``iConn.setTimeout()`` is removed. This function was used to set the timeout for ``iConn.run``
 sync mode.
 
 iSql Authentication
 -------------------
 
-``iSql.connect()`` and ``iSql.setOptions()`` are removed. These functions were used in conjunction 
+``iSql.connect()`` and ``iSql.setOptions()`` are removed. These functions were used in conjunction
 for XMLSERVICE user
 authentication. The transports already handle user authentication.
 
@@ -81,8 +81,8 @@ Migrating from ``iConn`` to ``Connection``
    passed to their run methods. You cannot simply replace iConn with Connection without adjusting
    your callbacks. See the :ref:`iconn-to-connection-run` section.
 
-When connecting using idb-connector, ``iConn`` takes 3 arguments: ``database``, ``username``, 
-and ``password``. These can be passed as attributes on the ``transportOptions`` attribute of the 
+When connecting using idb-connector, ``iConn`` takes 3 arguments: ``database``, ``username``,
+and ``password``. These can be passed as attributes on the ``transportOptions`` attribute of the
 object passed to ``Connection`` and specify the transport is ``idb``. eg.
 
 .. code:: js
@@ -95,9 +95,9 @@ object passed to ``Connection`` and specify the transport is ``idb``. eg.
    });
 
 When connecting using rest, ``iConn`` takes 4 arguments: ``database``, ``username``, ``password``,
-and ``options``. The options object included ``host``, ``port``, and ``path`` to 
-generate the url string. Instead specify ``database``, ``username``, ``password``, and ``url`` 
-on the ``transportOptions`` attribute of the object passed to ``Connection`` and specify the 
+and ``options``. The options object included ``host``, ``port``, and ``path`` to
+generate the url string. Instead specify ``database``, ``username``, ``password``, and ``url``
+on the ``transportOptions`` attribute of the object passed to ``Connection`` and specify the
 transport is ``rest``. eg.
 
 .. code:: js
@@ -292,7 +292,7 @@ xmlToJson
 ---------
 
 ``xmlToJson`` is deprecated and will be removed in ``v2.x``. Use
-`xml2js <https://www.npmjs.com/package/xml2js>`__ instead.
+an external XML parser such as `fast-xml-parser <https://www.npmjs.com/package/fast-xml-parser>`__.
 
 iDataQueue
 ----------

lib/Deprecated.js

@@ -4345,7 +4345,7 @@ function iSh(sh, options) {
  * @returns {object[]} - The array of result objects.
  */
 function xmlToJson(xml) {
-  xmlToJsonDeprecate('As of v1.0, \'xmlToJson\' is deprecated. Use xml2js npm package instead.');
+  xmlToJsonDeprecate('As of v1.0, \'xmlToJson\' is deprecated. Use the fast-xml-parser npm package instead.');
 
   const cmdRegG = /<cmd.*?>[\s\S]+?<\/cmd>/g;
   const shRegG = /<sh.*?>[\s\S]+?<\/sh>/g;