@cntwg/xml-lib-js 0.0.33 → 0.0.35

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+#### *v0.0.35*
+
+Pre-release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.0;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.2.4;
+> - move some functions from `$lib/xmldoc-lib.js` into new `$lib/xml-base.js` module;
+> - add function: `readAsAttrValue`.
+
+#### *v0.0.34*
+
+Pre-release version.
+
+> - update `xmldoc-lib.md`;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.2.3;
+> - (`TXmlElementController`) remove methods: `_getChildRaw`, `_addChildRaw`, `_setChildRaw`;
+> - (`TXmlElementsListController`) add special static method: `__getItemRaw`;
+> - (`TXmlElementsListController`) add special static method: `__setItemRaw`;
+> - (`TXmlElementsListController`) deprecate methods: `_getItemRaw`, `_setItemRaw`;
+> - (`TXmlElementsListController`) add iterator method.
+
 #### *v0.0.33*
 
 Pre-release version.

package/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.1.9|
+|***rev.*:**|0.1.10|
 |:---|---:|
-|***date***:|2024-08-01|
+|***date***:|2024-08-23|
 
 ## Introduction
 
@@ -25,6 +25,7 @@ xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` modu
 
 	+ `readAsTagName` (*experimental*);
 	+ `readAsAttrName` (*experimental*);
+	+ `readAsAttrValue` (*experimental*);
 	+ `valueToElementID` (*experimental*);
 
 - classes:

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.37|
+>|***rev.*:**|0.1.41|
 >|:---|---:|
->|date:|2025-02-06|
+>|date:|2025-08-23|
 
 ## Introduction
 
@@ -91,6 +91,17 @@ This function tries to convert a given `value` to the value of type which is sui
 |:---|---|---:|:---|
 | `value` | `any` | --- | some value to read |
 
+<a name="readAsAttrValue"></a>
+#### **readAsAttrValue(value)** => `string`
+
+> since: \[`v0.0.35`]
+
+This function tries to convert a given `value` to the value of type which is suitable for an XML-element's attribute. If failed a `null` is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value |
+
 <a name="valueToElementID"></a>
 #### **valueToElementID(value)**
 
@@ -409,20 +420,6 @@ This method loads an element content from a string given by a `str` parameter.
 
 This methods throws `Error` if something goes wrong through a parsing process of a string.
 
-#### class methods (*special*)
-
-##### **_getChildRaw(name)** => `?any`
-
-> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__getChildRaw` method of the class*).
-
-##### **_addChildRaw(name)** => `?object`
-
-> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__addChildRaw` method of the class*).
-
-##### **_setChildRaw(name, obj)** => `boolean`
-
-> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__setChildRaw` method of the class*).
-
 #### class methods (*static*)
 
 ##### **clear(item)** => `void`
@@ -455,6 +452,8 @@ This method adds an element addressed by `name` as a child element.
 
 ##### **__setChildRaw(node, name, obj)** => `boolean`
 
+> since: \[`v0.0.31`]
+
 This method inserts a given object as a child element addressed by `name`.
 
 <a name="TXmlElementsListController"></a>
@@ -619,7 +618,9 @@ The `options` structure is listed below:
 
 #### class methods (*special*)
 
-##### **_getItemRaw(name)**
+##### **_getItemRaw(index)**
+
+> WARNING: \[since `v0.0.34`] this method deprecated (*use `__getItemRaw`, a static method of the class, instead*).
 
 This method returns an element addressed by `index` as object. If failed `null` is returned.
 
@@ -629,12 +630,30 @@ This method adds an element to a list members as object. If succeed an index of
 
 ##### **_setItemRaw(index, obj)**
 
+> WARNING: \[since `v0.0.34`] this method deprecated (*use `__setItemRaw`, a static method of the class, instead*).
+
 This method replaces an element addressed by `index` with a new element which is saved as raw object. If succeed `true` is returned.
 
 ##### **_insItemRaw(index, obj)**
 
 This method inserts an element as a raw object in the position addressed by `index`. If succeed `true` is returned.
 
+#### class methods (*static, special*)
+
+<a name="TXmlElementsListController.__getItemRaw"></a>
+##### **__getItemRaw(node, index)** => `?any`
+
+> since: \[`v0.0.34`]
+
+This method returns an element addressed by `index` as object. If failed `null` is returned.
+
+<a name="TXmlElementsListController.__setItemRaw"></a>
+##### **__setItemRaw(node, index, item)** => `?any`
+
+> since: \[`v0.0.34`]
+
+This method replaces an element addressed by `index` with a new element which is saved as raw object. If succeed `true` is returned.
+
 <a name="TXmlContentDeclaration"></a>
 ### **TXmlContentDeclaration**
 

package/index.js

@@ -1,12 +1,13 @@
-// [v0.1.016-20240801]
+// [v0.2.018-20250823]
 
 // === module init block ===
 
 const xObj = require('@ygracs/xobj-lib-js');
-const xmldoc = require('./lib/xmldoc-lib.js');
-const xmlHelper = require('./lib/xml-helper.js');
+const xmldoc = require('./lib/xmldoc-lib');
+const xmlHelper = require('./lib/xml-helper');
+const xmlBase = require('./lib/xml-base');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 // === module main block ===
 
@@ -14,16 +15,17 @@ const xmlHelper = require('./lib/xml-helper.js');
 
 module.exports.xObj = xObj;
 module.exports.xmlHelper = xmlHelper;
-module.exports.xmlDoc = xmldoc;
+module.exports.xmlDoc = xmldoc; // // TODO: [?]
+
+module.exports.readAsTagName = xmlBase.readAsTagName;
+module.exports.readAsAttrName = xmlBase.readAsAttrName;
+module.exports.readAsAttrValue = xmlBase.readAsAttrValue;
+module.exports.valueToElementID = xmlBase.valueToElementID;
 
 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/xml-base.js

@@ -0,0 +1,129 @@
+// [v0.1.001-20250823]
+
+// === module init block ===
+
+const {
+  //valueToIndex, readAsBool, readAsString, isNotEmptyString,
+  //isArray, isObject, isPlainObject,
+  //valueToArray, valueToEntry,
+  valueToIDString,
+} = require('@ygracs/bsfoc-lib-js');
+
+// === module inner block ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * Tries to convert a given value to a valid tag name of an XML-element.
+ * @since v0.0.28
+ * @function readAsTagName
+ * @param {any} value - some value
+ * @returns {string}
+ */
+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;
+};
+
+/**
+ * Tries to convert a given value to a valid name of an XML-attribute.
+ * @since v0.0.28
+ * @function readAsAttrName
+ * @param {any} value - some value
+ * @returns {string}
+ */
+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;
+};
+
+/**
+ * Tries to convert a given value to a valid "attribute value".
+ * @since v0.0.35
+ * @function readAsAttrValue
+ * @param {any} value - some value
+ * @return {?string}
+ */
+function readAsAttrValue(value) {
+  let result = null;
+  switch (typeof value) {
+    case 'boolean': {
+      result = value.toString();
+      break;
+    }
+    case 'number': {
+      if (Number.isNaN(value)) break;
+      result = value.toString();
+      break;
+    }
+    case 'string': {
+      result = value.trim();
+      break;
+    }
+    default: {}
+  };
+  return result;
+};
+
+/**
+ * Tries to convert a given value to a valid identifier
+ * suitable as a value for an "ID-attribute" of an XML-element.
+ * @since v0.0.28
+ * @function valueToElementID
+ * @param {any} value - some value
+ * @returns {string}
+ * @see valueToIDString
+ */
+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 *)
+ */
+
+// === module exports block ===
+
+module.exports.readAsTagName = readAsTagName;
+module.exports.readAsAttrName = readAsAttrName;
+module.exports.readAsAttrValue = readAsAttrValue;
+module.exports.valueToElementID = valueToElementID;

package/lib/xml-helper.js

@@ -1,4 +1,4 @@
-// [v0.1.005-20250206]
+// [v0.1.006-20250822]
 
 // === module init block ===
 
@@ -24,11 +24,11 @@ const {
  */
 
 /**
+ * Tries to get a child element.
  * @function getChildByPath
  * @param {TXmlElementController} obj - some element
  * @param {string[]} chain - path to a target child element
  * @returns {?TXmlElementController}
- * @description Tries to get a child element.
  */
 function getChildByPath(obj, chain) {
   let result = null;
@@ -54,11 +54,11 @@ function getChildByPath(obj, chain) {
 };
 
 /**
+ * Tries to get a child element.
  * @function addChildByPath
  * @param {TXmlElementController} obj - some element
  * @param {string[]} chain - path to a target child element
  * @returns {?TXmlElementController}
- * @description Tries to get a child element.
  */
 function addChildByPath(obj, chain) {
   let item = obj;
@@ -82,19 +82,19 @@ function addChildByPath(obj, chain) {
 };
 
 /**
+ * Reads a text values from a given XML-element.
  * @function extractTextValues
  * @param {(TXmlElementController|TXmlElementsListController)} obj - some element
  * @returns {string[]}
- * @description Reads a text values from a given XML-element.
  */
 function extractTextValues(obj) {
   /**
+   * Reads element value and adds it to the list
    * @function pushValue
    * @param {string[]} result - accumulator array
    * @param {any} item - some element
    * @returns {void}
    * @protected
-   * @description Reads element value and adds it to the list
    */
   const pushValue = (result, item) => {
     if (item instanceof TXmlElementController) {
@@ -115,20 +115,19 @@ function extractTextValues(obj) {
 };
 
 /**
+ * Reads a text values with a `lang` attribute from a given XML-element.
  * @function extractTextValuesLn
  * @param {(TXmlElementController|TXmlElementsListController)} obj - some element
  * @returns {any[]}
- * @description Reads a text values with a `lang` attribute
- *              from a given XML-element.
  */
 function extractTextValuesLn(obj) {
   /**
+   * Reads element value and adds it to the list
    * @function pushValue
    * @param {any[]} result - accumulator array
    * @param {any} item - some element
    * @returns {void}
    * @protected
-   * @description Reads element value and adds it to the list
    */
   const pushValue = (result, item) => {
     if (item instanceof TXmlElementController) {