@cntwg/xml-lib-js 0.0.25 → 0.0.27

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+#### *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.
+
+> - `xmldoc-lib.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.1;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.1.2;
+> - improve error handling on file load/save ops for `TXmlContentContainer`;
+> - fix behavior for a `setTextValue` method of a `TXmlElementController`;
+> - add `xml-helper.js` module.
+
 #### *v0.0.25*
 
 Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2023 Yuri Grachev
+Copyright (c) 2019-2024 Yuri Grachev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,17 +1,11 @@
-|***rev.*:**|0.1.4|
+|***rev.*:**|0.1.6|
 |:---|---:|
-|***date***:|2023-09-19|
+|***date***:|2024-07-02|
 
 ## Introduction
 
 This module provide a base functionality for handling an XML-documents.
 
-## Use cases
-
-### Installation
-
-`npm install @cntwg/xml-lib-js`
-
 ## Description
 
 This module contains the following components:
@@ -38,3 +32,20 @@ xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` modu
 	+ `TXmlContentContainer`.
 
 For more read the `xmldoc-lib.md` in the project `doc` directory.
+
+### 3. an `xmlHelper` module extension
+
+- functions:
+
+	+ `getChildByPath`;
+	+ `addChildByPath`;
+	+ `extractTextValues`;
+	+ `extractTextValuesLn`.
+
+For more read the `xmldoc-lib.md` in the project `doc` directory.
+
+## Use cases
+
+### Installation
+
+`npm install @cntwg/xml-lib-js`

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.22|
+>|***rev.*:**|0.1.24|
 >|:---|---:|
->|date:|2023-09-19|
+>|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**
@@ -189,6 +193,7 @@ This method returns an array witch contain a value of a `textValue` property and
 This method sets the value of a `textValue` property and its `lang` attribute and if succeed returns `true`.
 
 The method received value that can be a string or an array. If value is an array it must be in the following format:
+
 `[ <textValue> ]`
 or
 `[ <lang>, <textValue> ]`.
@@ -199,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)**
 
@@ -209,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()**
 
@@ -501,3 +506,39 @@ This method returns a document content as a string in the JSON-format.
 This method binds a given object as a document content.
 
 For `options` parameter details see the class constructor description.
+
+## Module `xmlHelper`
+
+This section contains functions provided by `xmlHelper` module.
+
+### 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.
+
+#### **getChildByPath(object, chain)**
+
+> since: \[v0.0.26]
+
+This function tries to get a child element from a given object following path provided by `chain` parameter. If failed `null` is returned.
+
+The `chain` parameter contains an array of an element names.
+
+#### **addChildByPath(object, chain)**
+
+> since: \[v0.0.26]
+
+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,9 +1,10 @@
-// [v0.1.011-20230919]
+// [v0.1.013-20240701]
 
 // === module init block ===
 
 const xObj = require('@ygracs/xobj-lib-js');
 const xmldoc = require('./lib/xmldoc-lib.js');
+const xmlHelper = require('./lib/xml-helper.js');
 
 // === module extra block (helper functions) ===
 
@@ -11,16 +12,19 @@ const xmldoc = require('./lib/xmldoc-lib.js');
 
 // === module exports block ===
 
-exports.xObj = xObj;
+module.exports.xObj = xObj;
+module.exports.xmlHelper = xmlHelper;
+module.exports.xmlDoc = xmldoc;
 
-exports.XML_DEF_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
-exports.XML_DEF_ROOT_ETAG_NAME = xmldoc.XML_DEF_ROOT_ETAG_NAME;
+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;
 
-exports.TXmlContentParseOptions = xmldoc.TXmlContentParseOptions;
+module.exports.TXmlContentParseOptions = xmldoc.TXmlContentParseOptions;
 
-exports.TXmlAttributesMapper = xmldoc.TXmlAttributesMapper;
-exports.TXmlElementController = xmldoc.TXmlElementController;
-exports.TXmlElementsListController = xmldoc.TXmlElementsListController;
-exports.TXmlContentDeclaration = xmldoc.TXmlContentDeclaration;
-exports.TXmlContentRootElement = xmldoc.TXmlContentRootElement;
-exports.TXmlContentContainer = xmldoc.TXmlContentContainer;
+module.exports.TXmlAttributesMapper = xmldoc.TXmlAttributesMapper;
+module.exports.TXmlElementController = xmldoc.TXmlElementController;
+module.exports.TXmlElementsListController = xmldoc.TXmlElementsListController;
+module.exports.TXmlContentDeclaration = xmldoc.TXmlContentDeclaration;
+module.exports.TXmlContentRootElement = xmldoc.TXmlContentRootElement;
+module.exports.TXmlContentContainer = xmldoc.TXmlContentContainer;

package/lib/xml-helper.js

@@ -0,0 +1,142 @@
+// [v0.1.004-20240702]
+
+// === module init block ===
+
+const {
+  valueToArray,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  TXmlElementController,
+  TXmlElementsListController,
+} = require('./xmldoc-lib');
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * @function getChildByPath
+ * @param {TXmlElementController}
+ * @param {array}
+ * @returns {?TXmlElementController}
+ * @description Tries to get a child element.
+ */
+function getChildByPath(obj, chain) {
+  let result = null;
+  if (obj instanceof TXmlElementController) {
+    const list = valueToArray(chain);
+    let child = obj;
+    let isFound = false;
+    for (let name of list) {
+      child = child.getChild(name);
+      if (
+        child !== null
+        && (child instanceof TXmlElementController)
+      ) {
+        isFound = true;
+      } else {
+        isFound = false;
+        break;
+      };
+    };
+    if (isFound) result = child;
+  };
+  return result;
+};
+
+/**
+ * @function addChildByPath
+ * @param {TXmlElementController}
+ * @param {array}
+ * @returns {?TXmlElementController}
+ * @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);
+    for (let name of list) {
+      child = item.getChild(name);
+      if (child === null) {
+        child = item.addChild(name);
+      };
+      if ((child instanceof TXmlElementController)) {
+        item = child;
+      } else {
+        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 *)
+ */
+
+// === module exports block ===
+
+module.exports.getChildByPath = getChildByPath;
+module.exports.addChildByPath = addChildByPath;
+module.exports.extractTextValues = extractTextValues;
+module.exports.extractTextValuesLn = extractTextValuesLn;