@cntwg/xml-lib-js 0.0.26 → 0.0.28

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+#### *v0.0.28*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - add functions: readAsTagName, `readAsAttrName`, valueToElementID;
+> - some fixes in `xmldoc-lib.js` module.
+
+#### *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.9|
 |:---|---:|
-|***date***:|2024-06-26|
+|***date***:|2024-08-01|
 
 ## Introduction
 
@@ -21,6 +21,12 @@ xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` modu
 	+ `XML_DEF_ROOT_ETAG_NAME`;
 	+ `XML_DEF_PARSE_OPTIONS`;
 
+- functions:
+
+	+ `readAsTagName` (*experimental*);
+	+ `readAsAttrName` (*experimental*);
+	+ `valueToElementID` (*experimental*);
+
 - classes:
 
 	+ `TXmlAttributesMapper`;
@@ -33,12 +39,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,10 +1,10 @@
->|***rev.*:**|0.1.23|
+>|***rev.*:**|0.1.27|
 >|:---|---:|
->|date:|2024-06-26|
+>|date:|2024-08-01|
 
 ## Introduction
 
-This paper describes a constants and an object classes provided by `xmldoc-lib.js` module.
+This paper describes a constants, functions and an object classes provided by `xmldoc-lib.js` module.
 
 ## Module constants
 
@@ -41,6 +41,34 @@ 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 functions
+
+### Experimental functions
+
+> Note: Purpose of those functions will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+#### **readAsTagName(value)**
+
+> since: `v0.0.28`
+
+This function tries to convert a given `value` to the value of type which is suitable for an XML-element's tag name. If failed an empty string is returned.
+
+#### **readAsAttrName(value)**
+
+> since: `v0.0.28`
+
+This function tries to convert a given `value` to the value of type which is suitable for an XML-element's attribute name. If failed an empty string is returned.
+
+#### **valueToElementID(value)**
+
+> since: `v0.0.28`
+
+This function tries to convert a given `value` to the value of a valid identifier which is suitable for an XML-element's ID-attribute. If failed an empty string is returned.
+
 ## Module classes
 
 ### **TXmlContentParseOptions**
@@ -200,7 +228,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 +238,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 +554,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.016-20240801]
 
 // === module init block ===
 
@@ -14,9 +14,15 @@ 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.readAsTagName = xmldoc.readAsTagName;
+module.exports.readAsAttrName = xmldoc.readAsAttrName;
+module.exports.valueToElementID = xmldoc.valueToElementID;
 
 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.085-20240801]
 
 // === module init block ===
 
@@ -10,6 +10,7 @@ const {
   valueToIndex, readAsBool, readAsString, isNotEmptyString,
   isArray, isObject, isPlainObject,
   valueToArray, valueToEntry,
+  valueToIDString,
 } = require('@ygracs/bsfoc-lib-js');
 
 const xObj = require('@ygracs/xobj-lib-js');
@@ -66,6 +67,75 @@ const XML_TE_NROOT_EMSG = 'root element not found';
  * (* function definitions *)
  */
 
+/**
+ * @function readAsTagName
+ * @param {any}
+ * @return {string}
+ * @since v0.0.28
+ * @description Tries to convert a given value to a valid tag name
+ *              of an XML-element.
+ */
+function readAsTagName(value) {
+  let tagName = valueToIDString(value, { ignoreNumbers: true });
+  if (tagName === null) return '';
+  if (tagName !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = tagName.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      tagName = '';
+    };
+  };
+  return tagName;
+};
+
+/**
+ * @function readAsAttrName
+ * @param {any}
+ * @return {string}
+ * @since v0.0.28
+ * @description Tries to convert a given value to a valid name
+ *              of an XML-attribute.
+ */
+function readAsAttrName(value) {
+  let attrName = valueToIDString(value, { ignoreNumbers: true });
+  if (attrName === null) return '';
+  if (attrName !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = attrName.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      attrName = '';
+    };
+  };
+  return attrName;
+};
+
+/**
+ * @function valueToElementID
+ * @param {any}
+ * @return {string}
+ * @since v0.0.28
+ * @description Tries to convert a given value to a valid identifier
+ *              suitable as a value for an "ID-attribute" of an XML-element.
+ */
+function valueToElementID(value) {
+  let id = valueToIDString(value);
+  if (id === null) return '';
+  if (id !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = id.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      id = '';
+    };
+  };
+  return id;
+};
+
 /***
  * (* class definitions *)
  */
@@ -166,17 +236,20 @@ class TXmlAttributesMapper {
    * @description Sets an attribute value.
    */
   setAttribute(name, value){
+    const attrName = readAsAttrName(name);
     let result = false;
-    try {
-      result = xObj.writeXObjAttr(
-        this.#_host,
-        name,
-        value,
-        this.#_options.settings.attributesKey,
-      );
-    } catch (err) {
-      // // TODO: verify what error is thrown
-      result = false;
+    if (attrName !== '') {
+      try {
+        result = xObj.writeXObjAttr(
+          this.#_host,
+          name,
+          value,
+          this.#_options.settings.attributesKey,
+        );
+      } catch (err) {
+        // // TODO: verify what error is thrown
+        result = false;
+      };
     };
     return result;
   }
@@ -394,16 +467,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 +486,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 +556,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 +576,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 +1512,18 @@ 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.readAsTagName = readAsTagName;
+module.exports.readAsAttrName = readAsAttrName;
+module.exports.valueToElementID = valueToElementID;
+
+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.28",
   "description": "A library for handling an XML-documents",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",