@cntwg/xml-lib-js 0.0.29 → 0.0.31

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+#### *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.
+
+> - `xmldoc-lib.md` updated;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.2.0;
+> - (`TXmlAttributesMapper`) add method: `renameAttribute`;
+> - (`TXmlElementController`) add method: `renameAttribute`;
+> - (`TXmlElementController`) add method: `loadFromXMLString`;
+> - (`TXmlElementController`) add method: `create` (static);
+> - (`TXmlElementController`) change class constructor behavior (*see docs for details*).
+
 #### *v0.0.29*
 
 Pre-release version.

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.27|
+>|***rev.*:**|0.1.31|
 >|:---|---:|
->|date:|2024-08-01|
+>|date:|2024-09-29|
 
 ## Introduction
 
@@ -51,21 +51,21 @@ This constant defines a default value for naming the language attribute for XML-
 
 > 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.
 
-#### **readAsTagName(value)**
+#### **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)**
+#### **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.
 
@@ -117,9 +117,7 @@ The class constructor receives an arguments listed below:
 |`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
+###### `options` parameter
 
 The `options` structure is listed below:
 
@@ -127,6 +125,10 @@ The `options` structure is listed below:
 |:---|---|---:|:---|
 |`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (*see description for `XML_DEF_PARSE_OPTIONS`*)|
 
+##### exceptions
+
+If `object` parameter is not a type of `object` or not given a `TypeError` thrown.
+
 #### class properties
 
 |property name|value type|read only|description|
@@ -136,23 +138,29 @@ The `options` structure is listed below:
 
 #### class methods
 
-##### **hasAttribute(name)**
+##### **hasAttribute(name)** => `boolean`
 
 This method checks whether or not an attribute addressed by a `name` exists. If attribute exists, 'true' is returned.
 
-##### **getAttribute(name)**
+##### **getAttribute(name)** => `string`
 
 This method returns an attribute value addressed by a `name`. If attribute is not exists the empty string is returned.
 
-##### **setAttribute(name, value)**
+##### **setAttribute(name, value)** => `boolean`
 
 This method sets an attribute value addressed by a `name` and return `true` if succeed.
 
-##### **delAttribute(name)**
+##### **delAttribute(name)** => `boolean`
 
 This method clears an attribute value addressed by a `name`.
 
-##### **clear()**
+##### **renameAttribute(name, value)** => `boolean`
+
+> since: \[`v0.0.30`]
+
+This method renames an attribute addressed by a `name` to its new name given by a `value` parameter.
+
+##### **clear()** => `void`
 
 This method clears all attributes.
 
@@ -170,10 +178,10 @@ The class constructor receives an arguments listed below:
 
 |parameter name|value type|default value|description|
 |:---|---|---:|:---|
-|`object`|---|---|a host object|
+|`object`|`object`|---|a host object|
 |`options`|`object`|---|an options settings|
 
-##### `options` parameter
+###### `options` parameter
 
 The `options` structure is listed below:
 
@@ -182,6 +190,10 @@ The `options` structure is listed below:
 |`proxyModeEnable`|`boolean`|`false`|<*reserved*>|
 |`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`)|
 
+##### exceptions
+
+If `object` parameter is not a type of `object` or not given a `TypeError` thrown.
+
 #### class properties
 
 |property name|value type|read only|description|
@@ -192,27 +204,33 @@ The `options` structure is listed below:
 
 #### class methods
 
-##### **hasAttribute(name)**
+##### **hasAttribute(name)** => `boolean`
 
 This method checks whether or not an attribute addressed by a `name` exists. If attribute exists, 'true' is returned.
 
-##### **getAttribute(name)**
+##### **getAttribute(name)** => `string`
 
 This method returns an attribute value addressed by a `name`. If attribute is not exists the empty string is returned.
 
-##### **setAttribute(name, value)**
+##### **setAttribute(name, value)** => `boolean`
 
 This method sets an attribute value addressed by a `name` and return `true` if succeed.
 
-##### **delAttribute(name)**
+##### **delAttribute(name)** => `boolean`
 
-This method clears an attribute value addressed by a `name`.
+This method clears an attribute value addressed by a `name` parameter.
+
+##### **renameAttribute(name, value)** => `boolean`
 
-##### **getTextValue()**
+> since: \[`v0.0.30`]
+
+This method renames an attribute addressed by a `name` to its new name given by a `value` parameter.
+
+##### **getTextValue()** => `array`
 
 This method returns an array witch contain a value of a `textValue` property and a value of a `lang` attribute in format: `[ <lang>, <textValue> ]`. If element has no `lang` attribute, it replaced by an empty string in the result.
 
-##### **setTextValue(value)**
+##### **setTextValue(value)** => `boolean`
 
 This method sets the value of a `textValue` property and its `lang` attribute and if succeed returns `true`.
 
@@ -222,51 +240,87 @@ The method received value that can be a string or an array. If value is an array
 or
 `[ <lang>, <textValue> ]`.
 
-##### **hasChild(name)**
+##### **hasChild(name)** => `boolean`
 
 This method checks whether or not a child element addressed by `name` is exists.
 
-##### **getChild(name)**
+##### **getChild(name)** => `?(TXmlElementController|TXmlElementsListController)`
 
 This method returns a child element addressed by `name`. If failed `null` is returned.
 
-##### **addChild(name)**
+##### **addChild(name)** => `?TXmlElementController`
 
-This method adds an element as a child element addressed by a `name`.
+This method adds a new element as a child element addressed by a `name` parameter.
 
-##### **delChild(name)**
+##### **delChild(name)** => `boolean`
 
 This method deletes a child element addressed by a `name`.
 
 > 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()**
+##### **clear()** => `void`
 
 This method clears an element content.
 
+#### class methods (*experimental*)
+
+> Note: Purpose of those methods will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+##### **loadFromXMLString(str)** => `boolean`
+
+This method loads an element content from a string given by a `str` parameter.
+
+###### *exceptions*
+
+This methods trows `Error` if something goes wrong through a parsing process of a string.
+
 #### 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)**
+##### **__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**
 
@@ -282,10 +336,10 @@ The class constructor receives an arguments listed below:
 
 |parameter name|value type|default value|description|
 |:---|---|---:|:---|
-|`object`|---|---|a host object of an array type.|
+|`object`|`array`|---|a host object of an array type.|
 |`options`|`object`|---|an options settings.|
 
-##### `options` parameter
+###### `options` parameter
 
 The `options` structure is listed below:
 
@@ -295,6 +349,10 @@ The `options` structure is listed below:
 |`isNullItemsAllowed`|`boolean`|`false`|<*reserved*>|
 |`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`)|
 
+##### exceptions
+
+If `object` parameter is not a type of `array` or not given a `TypeError` may be thrown in case if a `proxyModeEnable` options is set.
+
 #### class properties
 
 |property name|property type|read only|description|
@@ -306,47 +364,47 @@ The `options` structure is listed below:
 
 #### class methods
 
-##### **clear()**
+##### **clear()** => `void`
 
 This method clears a list.
 
-##### **isEmpty()**
+##### **isEmpty()** => `boolean`
 
 This method returns `true` if a list has no elements and `false` otherwise.
 
-##### **isNotEmpty()**
+##### **isNotEmpty()** => `boolean`
 
 This method returns `true` if a list contains at least one element and `false` otherwise.
 
-##### **chkIndex(index)**
+##### **chkIndex(index)** => `boolean`
 
 This method checks if a given index fits a range of elements within the list. If so `true` is returned.
 
-##### **isValidItem(obj)**
+##### **isValidItem(obj)** => `boolean`
 
 This method checks whether or not a given element is valid.
 
-##### **getItem(index)**
+##### **getItem(index)** => `?TXmlElementController`
 
 This method returns an element addressed by `index`. If failed `null` is returned.
 
-##### **addItem(obj)**
+##### **addItem(obj)** => `index`
 
 This method adds an element to a list members. If succeed an index of the element is returned.
 
-##### **setItem(index, obj)**
+##### **setItem(index, obj)** => `boolean`
 
 This method replaces an element addressed by `index` with a new element. If succeed `true` is returned.
 
-##### **insItem(index, obj)**
+##### **insItem(index, obj)** => `boolean`
 
 This method inserts an element in the position addressed by `index`. If succeed `true` is returned.
 
-##### **delItem(index)**
+##### **delItem(index)** => `boolean`
 
 This method deletes an element addressed by `index`. If succeed `true` is returned.
 
-##### **loadItems(items, options)**
+##### **loadItems(items, options)** => `number`
 
 This method loaded a list of elements listed by `items` and returns a quantity of a successfully added elements.
 
@@ -391,7 +449,7 @@ The class constructor receives an arguments listed below:
 |`object`|`object`|---|a host object for the document content.|
 |`options`|`object`|---|an options settings.|
 
-##### `options` parameter
+###### `options` parameter
 
 The `options` structure is listed below:
 
@@ -399,6 +457,10 @@ The `options` structure is listed below:
 |:---|---|---:|:---|
 |`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`)|
 
+##### exceptions
+
+If `object` parameter is not a type of `object` or not given a `TypeError` thrown.
+
 #### class properties
 
 |property name|property type|read only|description|
@@ -408,7 +470,7 @@ The `options` structure is listed below:
 
 #### class methods (*special*)
 
-##### **init()**
+##### **init()** => `boolean`
 
 This method initializes an element with a default values.
 
@@ -429,7 +491,7 @@ The class constructor receives an arguments listed below:
 |`object`|`object`|---|a host object for the document content|
 |`options`|`object`|---|an options settings|
 
-##### `options` parameter
+###### `options` parameter
 
 The `options` structure is listed below:
 
@@ -469,7 +531,7 @@ The class constructor creates a new instance of the class.
 
 The class constructor receives an `options` parameter as its argument.
 
-##### `options` parameter
+###### `options` parameter
 
 The `options` structure is listed below:
 
@@ -489,11 +551,11 @@ The `options` structure is listed below:
 
 #### class methods
 
-##### **clear()**
+##### **clear()** => `void`
 
 This method clears a document content.
 
-##### **saveToXMLString()**
+##### **saveToXMLString()** => `string`
 
 This method returns a document content as a string.
 
@@ -501,7 +563,7 @@ This method returns a document content as a string.
 
 This method saves a document content into a file addressed by `src`.
 
-##### **loadFromXMLString(str)**
+##### **loadFromXMLString(str)** => `boolean`
 
 This method loads a document content from a string given by `str`.