@cntwg/xml-lib-js 0.0.30 → 0.0.31

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+#### *v0.0.31*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - (`TXmlElementController`) fix issue in method: `__setChildRaw`;
+> - (`TXmlElementController`) add special static method: `__getChildRaw`;
+> - (`TXmlElementController`) add special static method: `__addChildRaw`;
+> - (`TXmlElementController`) deprecate methods: `_getChildRaw`, `_addChildRaw`< `_setChildRaw`;
+> - some fixes in `xmldoc-lib.js` module.
+
 #### *v0.0.30*
 
 Pre-release version.

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.30|
+>|***rev.*:**|0.1.31|
 >|:---|---:|
->|date:|2024-09-23|
+>|date:|2024-09-29|
 
 ## Introduction
 
@@ -53,19 +53,19 @@ This constant defines a default value for naming the language attribute for XML-
 
 #### **readAsTagName(value)** => `string`
 
-> since: `v0.0.28`
+> 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)** => `string`
 
-> since: `v0.0.28`
+> 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`
+> 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.
 
@@ -156,7 +156,7 @@ This method clears an attribute value addressed by a `name`.
 
 ##### **renameAttribute(name, value)** => `boolean`
 
-> since: `v0.0.30`
+> since: \[`v0.0.30`]
 
 This method renames an attribute addressed by a `name` to its new name given by a `value` parameter.
 
@@ -222,7 +222,7 @@ This method clears an attribute value addressed by a `name` parameter.
 
 ##### **renameAttribute(name, value)** => `boolean`
 
-> since: `v0.0.30`
+> since: \[`v0.0.30`]
 
 This method renames an attribute addressed by a `name` to its new name given by a `value` parameter.
 
@@ -276,27 +276,51 @@ This methods trows `Error` if something goes wrong through a parsing process of
 
 #### class methods (*special*)
 
-##### **_getChildRaw(name)**
+##### **_getChildRaw(name)** => `?any`
 
-This method returns a child element addressed by `name` as object.
+> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__getChildRaw` method of the class*).
 
-##### **_addChildRaw(name)**
+##### **_addChildRaw(name)** => `?object`
 
-This method adds an element as a child element addressed by `name`.
+> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__addChildRaw` method of the class*).
 
-##### **_setChildRaw(name, obj)**
+##### **_setChildRaw(name, obj)** => `boolean`
 
-This method inserts a given object as a child element addressed by `name`.
+> WARNING: **\[since `v0.0.31`]** this method deprecated (*use static `__setChildRaw` method of the class*).
 
 #### class methods (*static*)
 
-##### **__unwrap(item)**
+##### **clear(item)** => `void`
+
+This method clears an `item` content.
+
+##### **create(obj, opt)** => `?(TXmlElementController|TXmlElementsListController)`
+
+> since: \[`v0.0.30`]
+
+This method creates an instance from a given object.
+
+#### class methods (*static, special*)
+
+##### **__unwrap(node)** => `?object`
 
 This method returns a host for an element as an object. If failed `null` is returned.
 
-##### **clear(item)** => `void`
+##### **__getChildRaw(node, name)** => `?any`
 
-This method clears an `item` content.
+> since: \[`v0.0.31`]
+
+This method returns a child element addressed by `name` as object. If failed `null` is returned.
+
+##### **__addChildRaw(node, name)** => `?object`
+
+> since: \[`v0.0.31`]
+
+This method adds an element addressed by `name` as a child element.
+
+##### **__setChildRaw(node, name, obj)** => `boolean`
+
+This method inserts a given object as a child element addressed by `name`.
 
 ### **TXmlElementsListController**
 

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.092-20240922]
+// [v0.2.096-20240929]
 
 // === module init block ===
 
@@ -554,20 +554,15 @@ class TXmlElementController {
 
   /**
    * @param {string} name
-   * @returns {object}
+   * @returns {?any}
    * @protected
+   * @deprecated
    * @description Returns a child element.
+   * @see TXmlElementController.__getChildRaw
    */
   _getChildRaw(name) {
     //console.log('CHECK: TXmlElementController._getChildRaw() => was called...');
-    //console.log('CHECK: TXmlElementController._getChildRaw() => _host => '+JSON.stringify(this.#_host, null, 2));
-    let item = xObj.getXObjElement(this.#_host, name);
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item => '+item);
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item.name() => ['+name+']');
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item.typeof() => '+typeof item);
-    //console.log('CHECK: TXmlElementController._getChildRaw() => item => '+JSON.stringify(item, null, 2));
-    //console.log('CHECK: TXmlElementController._getChildRaw() => was left...');
-    return item !== undefined ? item : null;
+    return TXmlElementController.__getChildRaw(this, name);
   }
 
   /**
@@ -575,6 +570,7 @@ class TXmlElementController {
    * @param {object} obj
    * @returns {boolean}
    * @protected
+   * @deprecated
    * @description Sets a child element.
    * @see TXmlElementController.__setChildRaw
    */
@@ -585,20 +581,15 @@ class TXmlElementController {
 
   /**
    * @param {string} name
-   * @returns {?object}
+   * @returns {?Object}
    * @protected
+   * @deprecated
    * @description Adds a new child element.
+   * @see TXmlElementController.__addChildRaw
    */
   _addChildRaw(name) {
     //console.log('CHECK: TXmlElementController._addChild() => was called...');
-    //console.log('CHECK: TXmlElementController._addChildRaw() => _host => '+JSON.stringify(this.#_host, null, 2));
-    let result = xObj.addXObjElement(this.#_host, name);
-    //console.log('CHECK: TXmlElementController._addChildRaw() => result => '+result);
-    //console.log('CHECK: TXmlElementController._addChildRaw() => item.name() => ['+name+']');
-    //console.log('CHECK: TXmlElementController._addChildRaw() => item.typeof() => '+typeof result.item);
-    //console.log('CHECK: TXmlElementController._addChildRaw() => item => '+JSON.stringify(result.item, null, 2));
-    //console.log('CHECK: TXmlElementController._addChildRaw() => was left...');
-    return result.isSucceed ? result.item : null;
+    return TXmlElementController.__addChildRaw(this, name);
   }
 
   /**
@@ -667,6 +658,7 @@ class TXmlElementController {
    * @returns {boolean}
    * @throws {Error}
    * @experimental
+   * @since v0.0.30
    * @description Loads a element content from a string.
    */
   loadFromXMLString(xmlString) {
@@ -722,6 +714,57 @@ class TXmlElementController {
     return (item instanceof TXmlElementController) ? item.#_host : null;
   }
 
+  /**
+   * @param {TXmlElementController} node
+   * @param {string} name
+   * @returns {?any}
+   * @protected
+   * @static
+   * @since v0.0.31
+   * @description Returns a child element.
+   */
+  static __getChildRaw(node, name) {
+    let item = null;
+    if (node instanceof TXmlElementController) {
+      try {
+        const obj = node.#_host;
+        item = xObj.getXObjElement(obj, name);
+        if (item === undefined) item = null;
+      } catch (err) {
+        // // TODO: [?] check what kind of error thrown
+        item = null;
+      };
+    };
+    return item;
+  }
+
+  /**
+   * @param {TXmlElementController} node
+   * @param {string} name
+   * @returns {?Object}
+   * @protected
+   * @static
+   * @since v0.0.31
+   * @description Adds a new child element.
+   */
+  static __addChildRaw(node, name) {
+    const childName = readAsTagName(name);
+    let item = null;
+    if (
+      node instanceof TXmlElementController
+      && childName !== ''
+    ) {
+      try {
+        const obj = node.#_host;
+        ({ item } = xObj.addXObjElement(obj, childName));
+      } catch (err) {
+        // // TODO: [?] check what kind of error thrown
+        item = null;
+      };
+    };
+    return item;
+  }
+
   /**
    * @param {TXmlElementController} node
    * @param {string} name
@@ -732,25 +775,17 @@ class TXmlElementController {
    * @description Sets a child element.
    */
   static __setChildRaw(node, name, obj) {
-    //console.log('CHECK: TXmlElementController.__setChildRaw() => was called...');
-    let isSUCCEED = false;
-    if (node instanceof TXmlElementController) {
-      let item = null;
-      if (isArray(obj)) {
-        //console.log('CHECK: TXmlElementController.__setChildRaw() => <obj> is array...');
-        item = xObj.insertXObjEList(node.#_host, name, { force: true });
-        // load elements
-        for (let element of obj) {
-          if (isPlainObject(element)) item.push(element);
-        };
-      } else if (isObject(obj)) {
-        //console.log('CHECK: TXmlElementController.__setChildRaw() => <obj> is object...');
-        item = xObj.insertXObjElement(node.#_host, name, { force: true });
-        // // TODO: set element
-      };
-      if (item) isSUCCEED = true;
+    const childName = readAsTagName(name);
+    let isSucceed = false;
+    if (
+      node instanceof TXmlElementController
+      && childName !== ''
+      && isObject(obj)
+    ) {
+      node.#_host[childName] = obj;
+      isSucceed = true;
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
@@ -774,6 +809,7 @@ class TXmlElementController {
    * @param {object} [opt]
    * @returns {(null|TXmlElementController|TXmlElementsListController)}
    * @static
+   * @since v0.0.30
    * @description Creates new controller element.
    */
   static create(obj, opt) {

package/package.json

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