@cntwg/xml-lib-js 0.0.26 → 0.0.27

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+#### *v0.0.27*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - fix error in a `addChildByPath` function;
+> - add functions (`xmlHelper` module): `extractTextValues`, `extractTextValuesLn`.
+
 #### *v0.0.26*
 
 Pre-release version.

package/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.1.5|
+|***rev.*:**|0.1.6|
 |:---|---:|
-|***date***:|2024-06-26|
+|***date***:|2024-07-02|
 
 ## Introduction
 
@@ -33,12 +33,14 @@ xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` modu
 
 For more read the `xmldoc-lib.md` in the project `doc` directory.
 
-### 3. an `xmlHelper` module extention
+### 3. an `xmlHelper` module extension
 
 - functions:
 
 	+ `getChildByPath`;
-	+ `addChildByPath`.
+	+ `addChildByPath`;
+	+ `extractTextValues`;
+	+ `extractTextValuesLn`.
 
 For more read the `xmldoc-lib.md` in the project `doc` directory.
 

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.23|
+>|***rev.*:**|0.1.24|
 >|:---|---:|
->|date:|2024-06-26|
+>|date:|2024-07-02|
 
 ## Introduction
 
@@ -41,6 +41,10 @@ The settings listed in the table below:
 
 This constant defines a default value for naming the root element for XML-document. Its value is `root`.
 
+### **XML\_LANG\_ATTR\_TNAME**
+
+This constant defines a default value for naming the language attribute for XML-element. Its value is `lang`.
+
 ## Module classes
 
 ### **TXmlContentParseOptions**
@@ -200,7 +204,7 @@ This method checks whether or not a child element addressed by `name` is exists.
 
 ##### **getChild(name)**
 
-This method returns a child element addressed by `name`.
+This method returns a child element addressed by `name`. If failed `null` is returned.
 
 ##### **addChild(name)**
 
@@ -210,7 +214,7 @@ This method adds an element as a child element addressed by a `name`.
 
 This method deletes a child element addressed by a `name`.
 
-> Warning: method not fully implemented. not used for list like elements.
+> Warning: A method not fully implemented yet. Not use it for list like elements. If list contains a more than one element, a method will fail.
 
 ##### **clear()**
 
@@ -526,3 +530,15 @@ The `chain` parameter contains an array of an element names.
 This function tries to add a new child element into a given object following path provided by `chain` parameter. If succeed a new element returned. If failed `null` is returned.
 
 The `chain` parameter contains an array of an element names. The last name in `chain` is a name of the element which will be added.
+
+#### **extractTextValues(object)**
+
+> since: \[v0.0.27]
+
+This function tries to get a text value from a given element.
+
+#### **extractTextValuesLn(object)**
+
+> since: \[v0.0.27]
+
+This function tries to get a text value with its language attribute from a given element.

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.012-20240626]
+// [v0.1.013-20240701]
 
 // === module init block ===
 
@@ -14,9 +14,11 @@ const xmlHelper = require('./lib/xml-helper.js');
 
 module.exports.xObj = xObj;
 module.exports.xmlHelper = xmlHelper;
+module.exports.xmlDoc = xmldoc;
 
 module.exports.XML_DEF_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
 module.exports.XML_DEF_ROOT_ETAG_NAME = xmldoc.XML_DEF_ROOT_ETAG_NAME;
+module.exports.XML_LANG_ATTR_TNAME = xmldoc.XML_LANG_ATTR_TNAME;
 
 module.exports.TXmlContentParseOptions = xmldoc.TXmlContentParseOptions;
 

package/lib/xml-helper.js

@@ -1,4 +1,4 @@
-// [v0.0.001-20240626]
+// [v0.1.004-20240702]
 
 // === module init block ===
 
@@ -8,6 +8,7 @@ const {
 
 const {
   TXmlElementController,
+  TXmlElementsListController,
 } = require('./xmldoc-lib');
 
 // === module extra block (helper functions) ===
@@ -60,6 +61,7 @@ function getChildByPath(obj, chain) {
  * @description Tries to get a child element.
  */
 function addChildByPath(obj, chain){
+  let item = obj;
   let child = null;
   if (obj instanceof TXmlElementController) {
     const list = valueToArray(chain);
@@ -71,13 +73,63 @@ function addChildByPath(obj, chain){
       if ((child instanceof TXmlElementController)) {
         item = child;
       } else {
-        child = null; break;
+        child = null;
+        break;
       };
     };
   };
   return child;
 };
 
+/**
+ * @function extractTextValues
+ * @param {(TXmlElementController|TXmlElementsListController)}
+ * @returns {array}
+ * @description Reads a text values from a given XML-element.
+ */
+function extractTextValues(obj){
+  const pushValue = (result, item) => {
+    if (item instanceof TXmlElementController) {
+      let value = item.textValue;
+      if (value !== '') result.push(value);
+    };
+  };
+  let result = [];
+  if (obj instanceof TXmlElementsListController) {
+    for (let i = 0; i < obj.size; i++) {
+      pushValue(result, obj.getItem(i));
+    };
+  } else {
+    pushValue(result, obj);
+  };
+  return result;
+};
+
+/**
+ * @function extractTextValuesLn
+ * @param {(TXmlElementController|TXmlElementsListController)}
+ * @returns {array}
+ * @description Reads a text values with a `lang` attribute
+ *              from a given XML-element.
+ */
+function extractTextValuesLn(obj){
+  const pushValue = (result, item) => {
+    if (item instanceof TXmlElementController) {
+      let [ lang, value ] = item.getTextValue();
+      if (value !== '') result.push([ lang, value ]);
+    };
+  };
+  let result = [];
+  if (obj instanceof TXmlElementsListController) {
+    for (let i = 0; i < obj.size; i++) {
+      pushValue(result, obj.getItem(i));
+    };
+  } else {
+    pushValue(result, obj);
+  };
+  return result;
+};
+
 /***
  * (* class definitions *)
  */
@@ -86,3 +138,5 @@ function addChildByPath(obj, chain){
 
 module.exports.getChildByPath = getChildByPath;
 module.exports.addChildByPath = addChildByPath;
+module.exports.extractTextValues = extractTextValues;
+module.exports.extractTextValuesLn = extractTextValuesLn;

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.077-20240625]
+// [v0.1.081-20240701]
 
 // === module init block ===
 
@@ -394,16 +394,16 @@ class TXmlElementController {
    * @returns {bool}
    * @description Checks whether an element has a child element.
    */
-  hasChild(name){
+  hasChild(name) {
     const _name = xObj.evalXObjEName(name);
+    if (_name === null) return false;
     let result = false;
-    if (typeof _name === 'string' && _name !== '') {
-      try {
-        result = isObject(xObj.getXObjElement(this.#_host, name));
-      } catch (err) {
-        // // TODO: [?] verify what error is thrown
-        throw err;
-      };
+    try {
+      result = isObject(xObj.getXObjElement(this.#_host, _name));
+    } catch (err) {
+      // // TODO: [?] verify what error is thrown
+      //throw err;
+      result = false;
     };
     return result;
   }
@@ -413,21 +413,21 @@ class TXmlElementController {
    * @returns {(null|TXmlElementController|TXmlElementsListController)}
    * @description Returns a child element.
    */
-  getChild(name){
-    const _name = xObj.evalXObjEName(name);
-    let result = null;
-    if (typeof _name === 'string' && _name !== '') {
-      try {
-        const item = xObj.getXObjElement(this.#_host, name);
-        if (isArray(item)) {
-          result = new TXmlElementsListController(item, this.#_options);
-        } else if (isObject(item)) {
-          result = new TXmlElementController(item, this.#_options);
-        };
-      } catch (err) {
-        // // TODO: [?] verify what error is thrown
-        throw err;
+  getChild(name) {
+    let result = xObj.evalXObjEName(name);
+    if (result === null) return null;
+    try {
+      const item = xObj.getXObjElement(this.#_host, result);
+      if (isArray(item)) {
+        result = new TXmlElementsListController(item, this.#_options);
+      } else if (isObject(item)) {
+        result = new TXmlElementController(item, this.#_options);
+      } else {
+        result = null;
       };
+    } catch (err) {
+      // // TODO: [?] verify what error is thrown
+      result = null;
     };
     return result;
   }
@@ -483,17 +483,17 @@ class TXmlElementController {
    * @returns {?TXmlElementController}
    * @description Adds a new child element.
    */
-  addChild(name){
+  addChild(name) {
     const _name = xObj.evalXObjEName(name);
+    if (_name === null) return null;
     let result = null;
-    if (typeof _name === 'string' && _name !== '') {
-      try {
-        let { item } = xObj.addXObjElement(this.#_host, name);
-        if (item) result = new TXmlElementController(item, this.#_options)
-      } catch (err) {
-        // // TODO: [?] verify what error is thrown
-        throw err;
-      };
+    try {
+      const { item } = xObj.addXObjElement(this.#_host, _name);
+      if (item) result = new TXmlElementController(item, this.#_options)
+    } catch (err) {
+      // // TODO: [?] verify what error is thrown
+      //throw err;
+      result = null;
     };
     return result;
   }
@@ -503,33 +503,32 @@ class TXmlElementController {
    * @returns {bool}
    * @description Deletes a child element.
    */
-  delChild(name){
+  delChild(name) {
     const _name = xObj.evalXObjEName(name);
-    let isSUCCEED = false;
-    if (typeof _name === 'string' && _name !== '') {
-      try {
-        const item = xObj.getXObjElement(this.#_host, name);
-        let isACCEPTED = false;
-        if (isArray(item)) {
-          //console.log('CHECK: TXmlElementController.delChild() => item.typeof() => [object Array]');
-          if (item.length < 2) {
-            isACCEPTED = true;
-          } else {
-            //console.log('CHECK: TXmlElementController.delChild() => item.length() => ['+item.length+']');
-          };
-        } else if (isObject(item)) {
+    if (_name === null) return false;
+    let isSucceed = false;
+    try {
+      const item = xObj.getXObjElement(this.#_host, _name);
+      let isACCEPTED = false;
+      if (isArray(item)) {
+        //console.log('CHECK: TXmlElementController.delChild() => item.typeof() => [object Array]');
+        if (item.length < 2) {
           isACCEPTED = true;
         } else {
-          //console.log('CHECK: TXmlElementController.delChild() => item.typeof() => ['+typeof item+']');
-          //console.log('CHECK: TXmlElementController.delChild() => item.value() => ['+item+']');
+          //console.log('CHECK: TXmlElementController.delChild() => item.length() => ['+item.length+']');
         };
-        if (isACCEPTED) isSUCCEED = xObj.deleteXObjElement(this.#_host, name);
-      } catch (err) {
-        // // TODO: [?] verify what error is thrown
-        throw err;
+      } else {
+        isACCEPTED = item !== null;
+        //console.log('CHECK: TXmlElementController.delChild() => item.typeof() => ['+typeof item+']');
+        //console.log('CHECK: TXmlElementController.delChild() => item.value() => ['+item+']');
       };
+      if (isACCEPTED) isSucceed = xObj.deleteXObjElement(this.#_host, _name);
+    } catch (err) {
+      // // TODO: [?] verify what error is thrown
+      //throw err;
+      isSucceed = false;
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
@@ -1440,13 +1439,14 @@ class TXmlContentContainer {
 
 // === module exports block ===
 
-exports.XML_DEF_PARSE_OPTIONS = XML_DEF_PARSE_OPTIONS;
-exports.XML_DEF_ROOT_ETAG_NAME = XML_DEF_ROOT_ETAG_NAME;
-
-exports.TXmlAttributesMapper = TXmlAttributesMapper;
-exports.TXmlElementController = TXmlElementController;
-exports.TXmlElementsListController = TXmlElementsListController;
-exports.TXmlContentParseOptions = TXmlContentParseOptions;
-exports.TXmlContentDeclaration = TXmlContentDeclaration;
-exports.TXmlContentRootElement = TXmlContentRootElement;
-exports.TXmlContentContainer = TXmlContentContainer;
+module.exports.XML_DEF_PARSE_OPTIONS = XML_DEF_PARSE_OPTIONS;
+module.exports.XML_DEF_ROOT_ETAG_NAME = XML_DEF_ROOT_ETAG_NAME;
+module.exports.XML_LANG_ATTR_TNAME = XML_LANG_ATTR_TNAME;
+
+module.exports.TXmlAttributesMapper = TXmlAttributesMapper;
+module.exports.TXmlElementController = TXmlElementController;
+module.exports.TXmlElementsListController = TXmlElementsListController;
+module.exports.TXmlContentParseOptions = TXmlContentParseOptions;
+module.exports.TXmlContentDeclaration = TXmlContentDeclaration;
+module.exports.TXmlContentRootElement = TXmlContentRootElement;
+module.exports.TXmlContentContainer = TXmlContentContainer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/xml-lib-js",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "description": "A library for handling an XML-documents",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",