@cntwg/xml-lib-js 0.0.24 → 0.0.26

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+#### *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.
+
+> - `xmldoc-lib.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.0;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.1.1.
+
 #### *v0.0.24*
 
 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.3|
+|***rev.*:**|0.1.5|
 |:---|---:|
-|***date***:|2023-07-31|
+|***date***:|2024-06-26|
 
 ## 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:
@@ -26,8 +20,6 @@ xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` modu
 
 	+ `XML_DEF_ROOT_ETAG_NAME`;
 	+ `XML_DEF_PARSE_OPTIONS`;
-	+ `DEF_XML_ROOT_ETAG_NAME` (*will deprecate*);
-	+ `DEF_XML_PARSE_OPTIONS` (*will deprecate*).
 
 - classes:
 
@@ -40,3 +32,18 @@ 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 extention
+
+- functions:
+
+	+ `getChildByPath`;
+	+ `addChildByPath`.
+
+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.21|
+>|***rev.*:**|0.1.23|
 >|:---|---:|
->|date:|2023-07-31|
+>|date:|2024-06-26|
 
 ## Introduction
 
@@ -8,7 +8,7 @@ This paper describes a constants and an object classes provided by `xmldoc-lib.j
 
 ## Module constants
 
-### **DEF\_XML\_PARSE_OPTIONS** or **XML\_DEF\_PARSE_OPTIONS**
+### **XML\_DEF\_PARSE_OPTIONS**
 
 This constant object provided by the module contains a default settings of options for XML-parser module used within.
 
@@ -37,14 +37,10 @@ The settings listed in the table below:
 |`trim`|`boolean`|`true`|
 |`spaces`|`number`|`2`|
 
-> WARNING: The constant `DEF\_XML\_PARSE\_OPTIONS` will be deprecated. Use `XML\_DEF\_PARSE\_OPTIONS` instead.
-
-### **DEF\_XML\_ROOT\_ETAG_NAME** or **XML\_DEF\_ROOT\_ETAG_NAME**
+### **XML\_DEF\_ROOT\_ETAG_NAME**
 
 This constant defines a default value for naming the root element for XML-document. Its value is `root`.
 
-> WARNING: The constant `DEF\_XML\_ROOT\_ETAG_NAME` is deprecate. Use `XML\_DEF\_ROOT\_ETAG_NAME` instead.
-
 ## Module classes
 
 ### **TXmlContentParseOptions**
@@ -82,26 +78,32 @@ This class implements a proxy interface for handling attributes of an element.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|---|---|a host object that holds an attributes|
 |`options`|`object`|---|an options settings|
 
+> NOTE: if `object` parameter is not a plain object the `TypeError` thrown.
+
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
 |:---|---|---:|:---|
 |`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (*see description for `XML_DEF_PARSE_OPTIONS`*)|
 
-> NOTE: if `object` parameter is not a plain object the `TypeError` thrown.
-
 #### class properties
 
-|name|read only|description|
-|:---|---|:---|
-|`entries`|yes|returns array of entries for all existing attributes|
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|`entries`|`array`|yes|returns an array of entries for all existing attributes|
 
 
 #### class methods
@@ -132,13 +134,19 @@ This class implements a proxy interface for an element.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives an arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|---|---|a host object|
 |`options`|`object`|---|an options settings|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -148,11 +156,11 @@ The `options` structure is listed below:
 
 #### class properties
 
-|property name|read only|description|
-|:---|---|:---|
-|`attributes`|yes|returns an attributes of the element|
-|`name`|yes|returns a tag name of the element|
-|`textValue`|no|represents a value of the element|
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|`attributes`|`TXmlAttributesMapper`|yes|returns an attributes of the element|
+|`name`||yes|\<*reserved*>|
+|`textValue`|`string`|no|represents a value of the element|
 
 #### class methods
 
@@ -181,6 +189,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> ]`.
@@ -237,13 +246,19 @@ This class implements a proxy interface for a list of elements.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|---|---|a host object of an array type.|
 |`options`|`object`|---|an options settings.|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -255,7 +270,7 @@ The `options` structure is listed below:
 #### class properties
 
 |property name|property type|read only|description|
-|:---|---|:---|
+|:---|---|---|:---|
 |`count`|`number`|yes|returns a quantity of the elements|
 |`size`|`number`|yes|returns a quantity of the elements|
 |`maxIndex`|`index`|yes|returns a last possible index of the elements|
@@ -337,13 +352,19 @@ This class implements a proxy interface for a document declaration element.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|`object`|---|a host object for the document content.|
 |`options`|`object`|---|an options settings.|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -353,7 +374,7 @@ The `options` structure is listed below:
 #### class properties
 
 |property name|property type|read only|description|
-|:---|---|:---|
+|:---|---|---|:---|
 |`version`|`string`|no|returns a version of a XML|
 |`encoding`|`string`|no|returns an encodings used by a document|
 
@@ -361,21 +382,27 @@ The `options` structure is listed below:
 
 ##### **init()**
 
-This method initializes element with a default values.
+This method initializes an element with a default values.
 
 ### **TXmlContentRootElement**
 
-This class extends functionality of a `TXmlElementController` class.
+This class extends a functionality of a `TXmlElementController` class.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives an arguments listed below:
+
+|parameter name|value type|default value|description|
 |:---|---|---:|:---|
 |`object`|`object`|---|a host object for the document content|
 |`options`|`object`|---|an options settings|
 
+##### `options` parameter
+
 The `options` structure is listed below:
 
 |option name|value type|default value|description|
@@ -388,9 +415,9 @@ The `options` structure is listed below:
 
 #### class properties
 
-|name|read only|description|
-|:---|---|:---|
-|tagName|no||
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|tagName|`string`|no||
 
 #### class methods (*static*)
 
@@ -408,7 +435,13 @@ This class implements a proxy interface for manipulate a content of a document.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives an `options` parameter as its argument.
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives an `options` parameter as its argument.
+
+##### `options` parameter
 
 The `options` structure is listed below:
 
@@ -422,9 +455,9 @@ The `options` structure is listed below:
 
 #### class properties
 
-|property name|read only|description|
-|:---|---|:---|
-|rootElement|yes|returns a document root element|
+|property name|value type|read only|description|
+|:---|---|---|:---|
+|rootElement||yes|returns a document root element|
 
 #### class methods
 
@@ -436,12 +469,6 @@ This method clears a document content.
 
 This method returns a document content as a string.
 
-##### **saveToFile(src)**
-
-This method saves a document content into a file addressed by `src`.
-
-> This is `async` method.
-
 ##### **saveToFileSync(src)**
 
 This method saves a document content into a file addressed by `src`.
@@ -450,13 +477,17 @@ This method saves a document content into a file addressed by `src`.
 
 This method loads a document content from a string given by `str`.
 
-##### **loadFromFile(src)**
+##### **loadFromFileSync(src)**
 
 This method loads a document content from a file addressed by `src`.
 
-> This is `async` method.
+#### class methods (*async*)
 
-##### **loadFromFileSync(src)**
+##### **saveToFile(src)**
+
+This method saves a document content into a file addressed by `src`.
+
+##### **loadFromFile(src)**
 
 This method loads a document content from a file addressed by `src`.
 
@@ -470,4 +501,28 @@ 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 constractor description.
+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.

package/index.js

@@ -1,9 +1,10 @@
-// [v0.1.010-20230731]
+// [v0.1.012-20240626]
 
 // === 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,21 +12,17 @@ const xmldoc = require('./lib/xmldoc-lib.js');
 
 // === module exports block ===
 
-exports.xObj = xObj;
+module.exports.xObj = xObj;
+module.exports.xmlHelper = xmlHelper;
 
-// will deprecate
-exports.DEF_XML_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
-// will deprecate
-exports.DEF_XML_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;
 
-exports.XML_DEF_PARSE_OPTIONS = xmldoc.XML_DEF_PARSE_OPTIONS;
-exports.XML_DEF_ROOT_ETAG_NAME = xmldoc.XML_DEF_ROOT_ETAG_NAME;
+module.exports.TXmlContentParseOptions = xmldoc.TXmlContentParseOptions;
 
-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,88 @@
+// [v0.0.001-20240626]
+
+// === module init block ===
+
+const {
+  valueToArray,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  TXmlElementController,
+} = 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 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;
+};
+
+/***
+ * (* class definitions *)
+ */
+
+// === module exports block ===
+
+module.exports.getChildByPath = getChildByPath;
+module.exports.addChildByPath = addChildByPath;