@cntwg/xml-lib-js 0.0.27 → 0.0.28

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+#### *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.

package/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.1.6|
+|***rev.*:**|0.1.9|
 |:---|---:|
-|***date***:|2024-07-02|
+|***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`;

package/doc/xmldoc-lib.md

@@ -1,10 +1,10 @@
->|***rev.*:**|0.1.24|
+>|***rev.*:**|0.1.27|
 >|:---|---:|
->|date:|2024-07-02|
+>|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
 
@@ -45,6 +45,30 @@ This constant defines a default value for naming the root element for XML-docume
 
 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**

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.013-20240701]
+// [v0.1.016-20240801]
 
 // === module init block ===
 
@@ -20,6 +20,10 @@ 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;
 
 module.exports.TXmlAttributesMapper = xmldoc.TXmlAttributesMapper;

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.081-20240701]
+// [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;
   }
@@ -1443,6 +1516,10 @@ 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;

package/package.json

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