@cntwg/xml-lib-js 0.0.34 → 0.0.35

package/CHANGELOG.md

@@ -1,14 +1,23 @@
+#### *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`;
+> - (`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;
+> - (`TXmlElementsListController`) add iterator method.
 
 #### *v0.0.33*
 

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.40|
+>|***rev.*:**|0.1.41|
 >|:---|---:|
->|date:|2025-07-19|
+>|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)**
 

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) {

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.2.117-20250719]
+// [v0.2.118-20250823]
 
 // === module init block ===
 
@@ -25,7 +25,17 @@ const {
   DEF_XML_PARSE_OPTIONS: XML_DEF_PARSE_OPTIONS,
 } = xObj;
 
-// === module extra block (helper functions) ===
+const {
+  readAsTagName,
+  readAsAttrName,
+  valueToElementID,
+} = require('./xml-base');
+
+// === module inner block ===
+
+/***
+ * (* helper function definitions *)
+ */
 
 /**
  * An XML-element controller settings.
@@ -109,73 +119,6 @@ const XML_TE_NROOT_EMSG = 'root element not found';
  * (* 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 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}
- */
-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 *)
  */
@@ -1640,10 +1583,6 @@ 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;
@@ -1651,3 +1590,8 @@ module.exports.TXmlContentParseOptions = TXmlContentParseOptions;
 module.exports.TXmlContentDeclaration = TXmlContentDeclaration;
 module.exports.TXmlContentRootElement = TXmlContentRootElement;
 module.exports.TXmlContentContainer = TXmlContentContainer;
+
+// * re-expected *
+module.exports.readAsTagName = readAsTagName;
+module.exports.readAsAttrName = readAsAttrName;
+module.exports.valueToElementID = valueToElementID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/xml-lib-js",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "description": "A library for handling an XML-documents",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "doc/xmldoc-lib.md",
     "lib/xmldoc-lib.js",
     "lib/xml-helper.js",
+    "lib/xml-base.js",
     "index.js",
     "CHANGELOG.md"
   ],
@@ -37,13 +38,13 @@
   },
   "dependencies": {
     "@cntwg/file-helper": "^0.0.1",
-    "@ygracs/bsfoc-lib-js": "^0.2.3",
+    "@ygracs/bsfoc-lib-js": "^0.3.0",
     "@ygracs/xml-js6": "^0.0.5-b",
-    "@ygracs/xobj-lib-js": "^0.2.3"
+    "@ygracs/xobj-lib-js": "^0.2.4"
   },
   "devDependencies": {
-    "jest": "^30.0.4",
-    "jsdoc-to-markdown": "^9.1.1",
+    "jest": "^30.0.5",
+    "jsdoc-to-markdown": "^9.1.2",
     "minimist": "^1.2.8"
   }
 }