npm - @ygracs/xobj-lib-js - Versions diffs - 0.2.0 → 0.2.2 - Mend

@ygracs/xobj-lib-js 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/doc/xObj.md CHANGED Viewed

@@ -1,790 +1,1191 @@
->|***rev.*:**|0.1.36|
->|:---|---:|
->|date:|2024-09-15|
-## Intoduction
-This paper describes a functions provided by `xObj.js` module.
-> Note: This module was primarily written to deal with a XML-parse provided by a [`xml-js`](https://www.npmjs.com/package/xml-js) module for 'Node.js' running in "compact" mode.
-## Content
-### Base constants
-|name|type|value|
-|:---|---|---:|
-|XOBJ_DEF_PARAM_TNAME|`string`|`__text`|
-|XOBJ_DEF_ATTR_TNAME|`string`|`__attr`|
-|DEF_XML_PARSE_OPTIONS|`object`|---|
-#### **DEF\_XML\_PARSE_OPTIONS**
-This constant object provided by the module contains a default settings of options for XML-parser module used within.
-The settings listed in the table below:
-|name|type|value|
-|:---|---|:---|
-|compact|`boolean`|`true`|
-|declarationKey|`string`|`__decl`|
-|attributesKey|`string`|`__attr`|
-|textKey|`string`|`__text`|
-|commentKey|`string`|`__note`|
-|cdataKey|`string`|`__cdata`|
-|nameKey|`string`|`__name`|
-|typeKey|`string`|`__type`|
-|parentKey|`string`|`parent`|
-|elementsKey|`string`|`items`|
-|ignoreDeclaration|`boolean`|`false`|
-|ignoreDocType|`boolean`|`false`|
-|ignoreInstractions|`boolean`|`false`|
-|ignoreText|`boolean`|`false`|
-|ignoreComments|`boolean`|`false`|
-|ignoreCData|`boolean`|`false`|
-|fullTagEmptyElement|`boolean`|`true`|
-|addParent|`boolean`|`false`|
-|trim|`boolean`|`true`|
-|spaces|`number`|`2`|
-### Base functions for read an object parameter value
-> Note:
-> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
-#### **readXObjParam(object\[, key])** => `string`
-This function returns a value of an object parameter. The value is of a `string` type.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjParamAsBool(object\[, defValue \[, key]])** => `boolean`
-This function reads a value of an object parameter and returns it as a `boolean`.
-The `defValue` must be of a `boolean` type, if else the `false` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjParamAsNum(object\[, defValue \[, key])** => `number`
-This function reads a value of an object parameter and returns it as a `number`.
-The `defValue` must be of a `number` type, if else the `0` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjParamAsIndex(object\[, key])** => `index`
-This function reads a value of an object parameter and try to convert it to a valid index value. If function failed, `-1` is returned.
-> Note: *for use in this case, index is validated as a non-negative integer number.*
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjParamAsStr(object\[, defValue \[, key])** => `string`
-> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjParam`](#readxobjparamobject-key--string) or [`readXObjParamEx`](#readxobjparamexobject-opt-key--string) instead.*
-This function reads a value of an object parameter and returns it as a `string`.
-The `defValue` must be of a `string` type, if else the empty string is used.
-#### **readXObjParamEx(object\[, opt \[, key])** => `string`
-> since: \[v0.2.0]
-This function reads a value of an object parameter and returns it as a `string`.
-##### ***parameters***
-The `opt` parameter must be:
-- a `string` - defines a default value;
-- an `object` - defines a set of options to transform a value.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-### Base functions for write an object parameter value
-> Note:
-> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
-#### **writeXObjParam(object, value\[, key])** => `boolean`
-This function sets object parameter to a given value and if succeed returns `true`.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjParamAsBool(object, value\[, defValue\[, key]])** => `boolean`
-This function writes a given `boolean` value of an object parameter.
-The `defValue` must be of a `boolean` type, if else the `false` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjParamAsNum(object, value\[, defValue\[, key]])** => `boolean`
-This function writes a given `number` value of an object parameter.
-The `defValue` must be of a `number` type, if else the `0` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjParamAsIndex(object, value\[, key])** => `boolean`
-This function try to interpret a given value as a valid index value and, if succeed, writes it into an object parameter.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjParamEx(object, value\[, opt\[, key]])** => `boolean`
-This function sets object parameter to a given value and if succeed returns `true`.
-##### ***parameters***
-The `opt` parameter must be:
-- a `string` - defines a default value;
-- an `object` - defines a set of options to transform a value.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-### Base functions for read an object attributes value
-> Note:
-> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
-#### **readXObjAttr(object, attr\[, key])** => `string`
-This function returns a value of an object attribute. The value is of a `string` type.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjAttrAsBool(object, attr\[, defValue\[, key]])** => `boolean`
-This function reads a value of an object attribute and returns it as a `boolean`.
-The `defValue` must be of a `boolean` type, if else the `false` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjAttrAsNum(object, attr\[, defValue\[, key]])** => `number`
-This function reads a value of an object attribute and returns it as a `number`.
-The `defValue` must be of a `number` type, if else the `0` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjAttrAsIndex(object, attr\[,  key])** => `index`
-This function reads a value of an object attribute and try to convert it to a valid index value. If function failed, `-1` is returned.
-> Note: *for use in this case, index is validated as a non-negative integer number.*
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **readXObjAttrAsStr(object, attr\[, defValue\[, key]])** => `string`
-> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjAttr`](#readxobjattrobject-attr-key--string) or [`readXObjAttrEx`](#readxobjattrexobject-attr-opt-key--string) instead.*
-This function returns a value of an object attribute. The value is of a `string` type.
-The `defValue` must be of a `string` type, if else the empty string is used.
-#### **readXObjAttrEx(object, attr\[, opt\[, key]])** => `string`
-> since: \[v0.2.0]
-This function returns a value of an object attribute. The value is of a `string` type.
-##### ***parameters***
-The `opt` parameter must be:
-- a `string` - defines a default value;
-- an `object` - defines a set of options to transform a value.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-### Base functions for write an object attributes value
-> Note:
-> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
-#### **writeXObjAttr(object, attr, value\[, key])** => `boolean`
-This function sets object attribute to a given value and if succeed returns `true`.
->Note: a value must be of a `string` type or can be converted to a string
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjAttrAsBool(object, attr, value\[, defValue\[, key]])** => `boolean`
-This function writes a given `boolean` value of an object attribute.
-The `defValue` must be of a `boolean` type, if else the `false` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjAttrAsNum(object, attr, value\[, defValue\[, key]])** => `boolean`
-This function writes a given `number` value of an object attribute.
-The `defValue` must be of a `number` type, if else the `0` is used.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjAttrAsIndex(object, attr, value\[, key])** => `boolean`
-This function try to interpret a given value as a valid index value and, if succeed, writes it into an object attribute.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **writeXObjAttrEx(object, attr, value\[, opt\[, key]])** => `boolean`
-This function sets object attribute to a given value and if succeed returns `true`.
-##### ***parameters***
-The `opt` parameter must be:
-- a `string` - defines a default value;
-- an `object` - defines a set of options to transform a value.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-### Special functions for read and write an object parameter value
-#### **readXObjParamRaw(object\[, key])** => `any`
-This is a special function that returns a value of an object parameter as "IT IS".
-> NOTE:
-> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `key` parameter given and is not a type of a `string`.
-#### **writeXObjParamRaw(object, value\[, key])** => `boolean`
-This is a special function that writes a given value of an object parameter as "IT IS".
-> NOTE:
-> - If `value` parameter not given, the function failed.
-> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `key` parameter given and is not a type of a `string`.
-### Special functions for read or write object attributes value
-#### **readXObjAttrRaw(object, attr\[, key])** => `any`
-This is a special function that returns a value of an object attribute as "IT IS".
-> NOTE:
-> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `attr` parameter given and is not a type of a `string`;
-  + if `key` parameter given and is not a type of a `string`.
-#### **writeXObjAttrRaw(object, attr, value\[, key])** => `boolean`
-This is a special function that writes a given value of an object attribute as "IT IS".
-> NOTE:
-> - If `value` parameter not given, the function failed.
-> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `attr` parameter given and is not a type of a `string`;
-  + if `key` parameter given and is not a type of a `string`.
-### Other functions for deal with an object attributes
-> Note:
-> If a `key` parameter given not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
-#### **getXObjAttributes(object\[, key])** => `?object`
-This function returns an object which represents a set of the element attributes for a given object or `null` if failed.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **checkXObjAttribute(object, attr\[, key])** => `boolean`
-This function tries to check whether or not an attribute with a name given by `attr` parameter exists for the element given by `object` parameter. If attribute exists `true` is returned.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `attr` parameter given and is not a type of a `string`;
-  + if `key` parameter given and is not a type of a `string`.
-#### **deleteXObjAttribute(object, attr\[, key])** => `boolean`
-This function tries to delete  an attribute with a name given by `attr` parameter. If succeed `true` is returned.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `attr` parameter given and is not a type of a `string`;
-  + if `key` parameter given and is not a type of a `string`.
-#### **renameXObjAttribute(object, attr, newName\[, key])** => `boolean`
-> since: \[v0.2.0]
-This function tries to rename an attribute with a name given by `attr` parameter to its new name. If succeed `true` is returned.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `attr` parameter given and is not a type of a `string`;
-  + if `newName` parameter given and is not a type of a `string`;
-  + if `key` parameter given and is not a type of a `string`.
-### Other functions
-#### **getXObjElement(object, name)** => `?any`
-This function returns an element from a given object by its name or `null` if that element not found.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `name` parameter given and is not a type of a `string`;
-- code: `ERR_XOBJ_INVARG_KEY`
-  + if `name` parameter given and is an empty string.
-#### **addXObjElement(object, name)** => `object`
-This function adds an element given by `name` parameter to a members of the given object and returns an `object` that represents a status of the operation.
-##### ***result***
-The status of an operation contains 2 fields:
-- `isSucceed` - `boolean` value;
-- `item` - an item which was added or a `null`.
-> <!> The function will fail if a target element exists and it is not an object or an array or not a `null`.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `name` parameter given and is not a type of a `string`;
-- code: `ERR_XOBJ_INVARG_KEY`
-  + if `name` parameter given and is an empty string.
-#### **insertXObjElement(object, name\[, options])** => `?(object|Array)`
-This function inserts an empty element named by a `name` parameter into a given object. If succeed the element will be returned or `null` in opposite.
-##### ***parameters***
-For details of an `options` parameter read the appropriate section in the description of the [`insertXObjElementEx`](#insertxobjelementexobject-name-options--object) function.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **insertXObjElementEx(object, name\[, options])** => `object`
-> since: \[v0.2.0]
-This function inserts an empty element named by a `name` parameter into a given object and returns an `object` that represents a status of the operation.
-##### ***parameters***
-An `options` parameter contains the following parameters:
-|option name|value type|default value|description|
-|:---|---|---:|:---|
-|`force`|`boolean`|`false`|modifies the functions behavior|
-|`ripOldies`|`boolean`|`false`|it prevents a replacement of an element which exists and is an object or an array. Applied only if `force` option is set to `true`|
-|`acceptIfList`|`boolean`|`false`|it defines whether a list elements is treated as a type of an `object`|
-An `options.force` parameter modifies the functions behavior as follows:
-- when set to `true`, the addressed element will be replaced with an empty element.
-- when set to `false`, if the target element exists and is not an object or an array, the function will failed.
-##### ***result***
-The status of an operation contains 2 fields:
-- `isSucceed` - `boolean` value;
-- `item` - an item which was inserted or a `null`.
-> <!> If a target element exists and it is not a `null`, the function behavior defined by the given options. When a required conditions not met, the function failed.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `name` parameter given and is not a type of a `string`;
-- code: `ERR_XOBJ_INVARG_KEY`
-  + if `name` parameter given and is an empty string.
-#### **deleteXObjElement(object, name)** => `boolean`
-This function deletes an element addressed by `name` parameter from a given object. If succeed `true` is returned.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **deleteXObjElementEx(object, name)** => `object`
-This function deletes an element addressed by `name` parameter from a given object and returns an `object` that represents a status of the operation.
-##### ***result***
-The status of an operation contains 2 fields:
-- `isSucceed` - `boolean` value;
-- `item` - an item which was deleted or a `null`.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `name` parameter given and is not a type of a `string`;
-- code: `ERR_XOBJ_INVARG_KEY`
-  + if `name` parameter given and is an empty string.
-#### **renameXObjElement(object, oldName, newName)** => `boolean`
-This function renames an element with a name `oldName` to a name `newName` for the given object. If succeed `true` is returned.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `oldName` parameter given and is not a type of a `string`;
-  + id `newName` parameter given and is not a type of a `string`.
-### Other special functions
-#### **evalXObjEName(name)**
-This function evaluated a value given by a `name` parameter and return a result. The dependencies of a resulted value returned by the function given in the following table:
-|given value|value of result|
-|:---|---|
-|value is an integer positive number or a string that can be converted to a such number|value of a `number`|
-|any other string that can\'t be converted to a number|value of a string|
-|any other cases|value of `null`|
-#### **insertXObjEList(object, name\[, options])** => `?Array`
-This function inserts an elements list named by a `name` parameter into a given object. If succeed the list will be returned or `null` in opposite.
-##### ***parameters***
-For details of an `options` parameter read the appropriate section in the description of the [`insertXObjEListEx`](#insertxobjelistexobject-name-options--object) function.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **insertXObjEListEx(object, name\[, options])** => `object`
-> since: \[v0.2.0]
-This function inserts an elements list named by a `name` parameter into a given object and returns an `object` that represents a status of the operation.
-##### ***parameters***
-An `options` parameter contains the following parameters:
-|option name|value type|default value|description|
-|:---|---|---:|:---|
-|`force`|`boolean`|`false`|modifies the functions behavior|
-|`ripOldies`|`boolean`|`false`|it prevents a replacement of an element which exists and has a type of an `array`. Applied only if `force` option is set to `true`|
-An `options.force` parameter modifies the functions behavior as follows:
-- when set to `true`, the addressed element will be replaced with an empty elements list.
-- when set to `false`, if the target element type is an `object`, the function will wraps it in the list.
-- when set to `false`, if the target element exists and is not an object or an array, the function will failed.
-##### ***result***
-The status of an operation contains 2 fields:
-- `isSucceed` - `boolean` value;
-- `item` - an item which was inserted or a `null`.
-> <!> If a target element exists and it is not a `null`, the function behavior defined by the given options. When a required conditions not met, the function failed.
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance;
-- code: `ERR_XOBJ_NSTR`
-  + if `name` parameter given and is not a type of a `string`;
-- code: `ERR_XOBJ_INVARG_KEY`
-  + if `name` parameter given and is an empty string.
-### 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.
-#### **genXObjENameDescr(name)**
-This function creates a object that contains description of the value given by a `name` parameter.
-A value of the `name` parameter must have some of the following formats:
-1. `<name>`;
-2. `<name>[<child>]`;
-3. `<name>[<child>=<value>]`;
-4. `<name>[@<attribute>]`;
-5. `<name>[@<attribute>=<value>]`;
-> Note: the `<value>` must be quoted if it contains characters like a spaces or square brackets.
-The returned object has following attributes:
-|attribute|value type|description|
-|:---|---|---|
-|`isERR`|`boolean`|set to `true` if error happend|
-|`name`|`string`|contains a name of the element|
-|`conditions`|`object`|contains conditions applied to that element|
-The object `conditions` property (*if present*) contains following attributes:
-|attribute|value type|description|
-|:---|---|---|
-|`type`|`string`||
-|`name`|`string`||
-|`value`|`any`||
-#### **insertXObjElements(object, name\[...name_N\[, options]])** => `number`
-This function inserts an elements given by the list of names and returns a quantity of the inserted elements.
-##### ***parameters***
-The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertxobjelementobject-name-options--objectarray).
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-#### **insertXObjEChain(object, name\[, ...name_N\[, options])**
-This function inserts a chain of the elements listed as a function arguments. If succeed the last inserted element will be returned or `null` if failed.
-> The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertxobjelementobject-name-options--objectarray).
-##### ***exceptions***
-The function throws a `TypeError` exception in case:
-- code: `ERR_XOBJ_NPOBJ`
-  + if `object` parameter is not an `Object` instance.
-### Base class
-#### **TXmlContentParseOptions**
-This class implements an interface for handling XML-parse options.
-##### class constructor
-The class constructor creates a new instance of the class. It receives arguments listed below:
-|name|type|default value|description|
-|:---|---|---:|:---|
-|`object`|---|---|a host object.|
-|`options`|`object`|---|an options settings.|
-##### class properties
-The table below describes a properties of a `TXmlContentParseOptions` class:
-|name|read only|description|
-|:---|---|:---|
-|settings|yes|presents a current options|
-|xml2js|yes|returns an options for an XML-to-JS converter|
-|js2xml|yes|returns an options for an JS-to-XML converter|
-##### class methods (*static*)
-###### **createNewOptionsSet(obj)**
-This method transforms a given object to a set of accepted parser options.
+>|***rev.*:**|0.1.43|
+>|:---|---:|
+>|date:|2025-01-28|
+## Introduction
+This paper describes a functions provided by `xObj.js` module.
+> Note: This module was primarily written to deal with a XML-parse provided by a [`xml-js`](https://www.npmjs.com/package/xml-js) module for 'Node.js' running in "compact" mode.
+## Content
+### Base type definitions
+This section contains some definitions for a general types of the objects (e.g. options set) that frequently used in a function descriptions.
+<a name="typedef+OPT_valtostr"></a>
+#### `OPT_valtostr` - options set
+This options set is an `object` which defines how a value transforms to a 'string' type.
+| option name | option type | default value | description |
+|:---|---|---:|:---|
+| `useTrim` | `boolean` | `false` | defines whether or not the resulting string must to be trimmed |
+| `letterCase` | `string` | --- | if given defines a function behavior on the resulting string |
+| `numberToString` | `boolean` | `false` | if set a values of `number` types will be converted to a string |
+| `boolToString` | `boolean` | `false` | if set a values of `boolean` types will be converted to a string |
+| `boolToUpperCase` | `boolean` | `false` | if set a values of `boolean` types when converted to a string will be present in upper case |
+| `defValue` | `string` | `EMPTY_STRING` | if given represents a value which will be returned in case the function failed |
+The behavior for `letterCase` settings defined in the table below:
+| option value | description |
+|:---|:---|
+| `upper` | the resulting string must to be present in upper case |
+| `lower` | the resulting string must to be present in lower case |
+| any other values | the resulting string will be not transformed |
+### Base constants
+|name|type|value|
+|:---|---|---:|
+|XOBJ_DEF_PARAM_TNAME|`string`|`__text`|
+|XOBJ_DEF_ATTR_TNAME|`string`|`__attr`|
+|DEF_XML_PARSE_OPTIONS|`object`|---|
+#### **DEF\_XML\_PARSE_OPTIONS**
+This constant object provided by the module contains a default settings of options for XML-parser module used within.
+The settings listed in the table below:
+|name|type|value|
+|:---|---|:---|
+|compact|`boolean`|`true`|
+|declarationKey|`string`|`__decl`|
+|attributesKey|`string`|`__attr`|
+|textKey|`string`|`__text`|
+|commentKey|`string`|`__note`|
+|cdataKey|`string`|`__cdata`|
+|nameKey|`string`|`__name`|
+|typeKey|`string`|`__type`|
+|parentKey|`string`|`parent`|
+|elementsKey|`string`|`items`|
+|ignoreDeclaration|`boolean`|`false`|
+|ignoreDocType|`boolean`|`false`|
+|ignoreInstractions|`boolean`|`false`|
+|ignoreText|`boolean`|`false`|
+|ignoreComments|`boolean`|`false`|
+|ignoreCData|`boolean`|`false`|
+|fullTagEmptyElement|`boolean`|`true`|
+|addParent|`boolean`|`false`|
+|trim|`boolean`|`true`|
+|spaces|`number`|`2`|
+### Base functions for read an object parameter value
+> Note:
+> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
+<a name="readXObjParam"></a>
+#### **readXObjParam(object\[, key])** => `string`
+This function returns a value of an object parameter as a string.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="readXObjParamAsBool"></a>
+#### **readXObjParamAsBool(object\[, defValue \[, key]])** => `boolean`
+This function reads a value of an object parameter and returns it as a `boolean`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `defValue` | `boolean` | `false` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="readXObjParamAsNum"></a>
+#### **readXObjParamAsNum(object\[, defValue \[, key])** => `number`
+This function reads a value of an object parameter and returns it as a `number`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `defValue` | `number` | `0` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="readXObjParamAsIndex"></a>
+#### **readXObjParamAsIndex(object\[, key])** => `number`
+This function reads a value of an object parameter and try to convert it to a valid index value. If function failed, `-1` is returned.
+> Note: *for use in this case, index is validated as a non-negative integer number.*
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+#### **readXObjParamAsStr(object\[, defValue \[, key])** => `string`
+> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjParam`](#readxobjparamobject-key--string) or [`readXObjParamEx`](#readxobjparamexobject-opt-key--string) instead.*
+This function reads a value of an object parameter and returns it as a `string`.
+The `defValue` must be of a `string` type, if else the empty string is used.
+<a name="readXObjParamEx"></a>
+#### **readXObjParamEx(object\[, options \[, key])** => `string`
+> since: \[v0.2.0]
+This function reads a value of an object parameter and returns it as a `string`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
+| `key` | `string` | --- | some key |
+An `options` parameter must be a `string` or an `object`.
+> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
+If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
+If `options` is of a `string` type the function treats it as a value of `options.defValue`.
+If `options` is not given the settings listed in table below are used by default:
+| option name | option type | value |
+|:---|---|---:|
+| `useTrim` | `boolean` | `false` |
+| `numberToString` | `boolean` | `true` |
+| `boolToString` | `boolean` | `true` |
+| `defValue` | `string` | `EMPTY_STRING` |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+### Base functions for write an object parameter value
+> Note:
+> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
+<a name="writeXObjParam"></a>
+#### **writeXObjParam(object, value\[, key])** => `boolean`
+This function sets object parameter to a given value and if succeed returns `true`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `value` | `any` | --- | some value to write |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjParamAsBool"></a>
+#### **writeXObjParamAsBool(object, value\[, defValue\[, key]])** => `boolean`
+This function writes a given `boolean` value of an object parameter.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `value` | `any` | --- | some value to write |
+| `defValue` | `boolean` | `false` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjParamAsNum"></a>
+#### **writeXObjParamAsNum(object, value\[, defValue\[, key]])** => `boolean`
+This function writes a given `number` value of an object parameter.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `value` | `any` | --- | some value to write |
+| `defValue` | `number` | `0` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjParamAsIndex"></a>
+#### **writeXObjParamAsIndex(object, value\[, key])** => `boolean`
+This function try to interpret a given value as a valid index value and, if succeed, writes it into an object parameter.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `value` | `any` | --- | some value to write |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjParamEx"></a>
+#### **writeXObjParamEx(object, value\[, options\[, key]])** => `boolean`
+This function sets object parameter to a given value and if succeed returns `true`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `value` | `any` | --- | some value to write |
+| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
+| `key` | `string` | --- | some key |
+An `options` parameter must be a `string` or an `object`.
+> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
+If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
+If `options` is of a `string` type the function treats it as a value of `options.defValue`.
+If `options` is not given the settings listed in table below are used by default:
+| option name | option type | value |
+|:---|---|---:|
+| `useTrim` | `boolean` | `false` |
+| `numberToString` | `boolean` | `true` |
+| `boolToString` | `boolean` | `true` |
+| `defValue` | `string` | `EMPTY_STRING` |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+### Base functions for read an object attributes value
+> Note:
+> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
+<a name="readXObjAttr"></a>
+#### **readXObjAttr(object, attr\[, key])** => `string`
+This function returns a value of an object attribute. The value is of a `string` type.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="readXObjAttrAsBool"></a>
+#### **readXObjAttrAsBool(object, attr\[, defValue\[, key]])** => `boolean`
+This function reads a value of an object attribute and returns it as a `boolean`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `defValue` | `boolean` | `false` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="readXObjAttrAsNum"></a>
+#### **readXObjAttrAsNum(object, attr\[, defValue\[, key]])** => `number`
+This function reads a value of an object attribute and returns it as a `number`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `defValue` | `number` | `0` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="readXObjAttrAsIndex"></a>
+#### **readXObjAttrAsIndex(object, attr\[,  key])** => `number`
+This function reads a value of an object attribute and try to convert it to a valid index value. If function failed, `-1` is returned.
+> Note: *for use in this case, index is validated as a non-negative integer number.*
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+#### **readXObjAttrAsStr(object, attr\[, defValue\[, key]])** => `string`
+> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjAttr`](#readxobjattrobject-attr-key--string) or [`readXObjAttrEx`](#readxobjattrexobject-attr-opt-key--string) instead.*
+This function returns a value of an object attribute. The value is of a `string` type.
+The `defValue` must be of a `string` type, if else the empty string is used.
+<a name="readXObjAttrEx"></a>
+#### **readXObjAttrEx(object, attr\[, options\[, key]])** => `string`
+> since: \[v0.2.0]
+This function returns a value of an object attribute. The value is of a `string` type.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
+| `key` | `string` | --- | some key |
+An `options` parameter must be a `string` or an `object`.
+> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
+If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
+If `options` is of a `string` type the function treats it as a value of `options.defValue`.
+If `options` is not given the settings listed in table below are used by default:
+| option name | option type | value |
+|:---|---|---:|
+| `useTrim` | `boolean` | `true` |
+| `numberToString` | `boolean` | `true` |
+| `boolToString` | `boolean` | `true` |
+| `defValue` | `string` | `EMPTY_STRING` |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+### Base functions for write an object attributes value
+> Note:
+> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
+<a name="writeXObjAttr"></a>
+#### **writeXObjAttr(object, attr, value\[, key])** => `boolean`
+This function sets object attribute to a given value and if succeed returns `true`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `value` | `any` | --- | some value |
+| `key` | `string` | --- | some key |
+> Note: a value must be of a `string` type or can be converted to a string
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjAttrAsBool"></a>
+#### **writeXObjAttrAsBool(object, attr, value\[, defValue\[, key]])** => `boolean`
+This function writes a given `boolean` value of an object attribute.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `value` | `any` | --- | some value |
+| `defValue` | `boolean` | `false` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjAttrAsNum"></a>
+#### **writeXObjAttrAsNum(object, attr, value\[, defValue\[, key]])** => `boolean`
+This function writes a given `number` value of an object attribute.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `value` | `any` | --- | some value |
+| `defValue` | `number` | `0` | default value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjAttrAsIndex"></a>
+#### **writeXObjAttrAsIndex(object, attr, value\[, key])** => `boolean`
+This function try to interpret a given value as a valid index value and, if succeed, writes it into an object attribute.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `value` | `any` | --- | some value |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="writeXObjAttrEx"></a>
+#### **writeXObjAttrEx(object, attr, value\[, options\[, key]])** => `boolean`
+This function sets object attribute to a given value and if succeed returns `true`.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `value` | `any` | --- | some value |
+| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
+| `key` | `string` | --- | some key |
+An `options` parameter must be a `string` or an `object`.
+> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
+If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
+If `options` is of a `string` type the function treats it as a value of `options.defValue`.
+If `options` is not given the settings listed in table below are used by default:
+| option name | option type | value |
+|:---|---|---:|
+| `useTrim` | `boolean` | `true` |
+| `numberToString` | `boolean` | `true` |
+| `boolToString` | `boolean` | `true` |
+| `defValue` | `string` | `EMPTY_STRING` |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+### Special functions for read and write an object parameter value
+<a name="readXObjParamRaw"></a>
+#### **readXObjParamRaw(object\[, key])** => `any`
+This is a special function that returns a value of an object parameter as "IT IS".
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `key` | `string` | --- | some key |
+> NOTE:
+> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `key` parameter given and is not a type of a `string`.
+<a name="writeXObjParamRaw"></a>
+#### **writeXObjParamRaw(object, value\[, key])** => `boolean`
+This is a special function that writes a given value of an object parameter as "IT IS".
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `value` | `any` | --- | some value |
+| `key` | `string` | --- | some key |
+> NOTE:
+> - If `value` parameter not given, the function failed.
+> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `key` parameter given and is not a type of a `string`.
+### Special functions for read or write object attributes value
+<a name="readXObjAttrRaw"></a>
+#### **readXObjAttrRaw(object, attr\[, key])** => `any`
+This is a special function that returns a value of an object attribute as "IT IS".
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `key` | `string` | --- | some key |
+> NOTE:
+> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `attr` parameter given and is not a type of a `string`;
+  + if `key` parameter given and is not a type of a `string`.
+<a name="writeXObjAttrRaw"></a>
+#### **writeXObjAttrRaw(object, attr, value\[, key])** => `boolean`
+This is a special function that writes a given value of an object attribute as "IT IS".
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `value` | `any` | --- | some value |
+| `key` | `string` | --- | some key |
+> NOTE:
+> - If `value` parameter not given, the function failed.
+> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `attr` parameter given and is not a type of a `string`;
+  + if `key` parameter given and is not a type of a `string`.
+### Other functions for deal with an object attributes
+> Note:
+> If a `key` parameter given not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
+<a name="getXObjAttributes"></a>
+#### **getXObjAttributes(object\[, key])** => `?object`
+This function returns an object which represents a set of the element attributes for a given object or `null` if failed.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="checkXObjAttribute"></a>
+#### **checkXObjAttribute(object, attr\[, key])** => `boolean`
+This function tries to check whether or not an attribute with a name given by `attr` parameter exists for the element given by `object` parameter. If attribute exists `true` is returned.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `attr` parameter given and is not a type of a `string`;
+  + if `key` parameter given and is not a type of a `string`.
+<a name="deleteXObjAttribute"></a>
+#### **deleteXObjAttribute(object, attr\[, key])** => `boolean`
+This function tries to delete  an attribute with a name given by `attr` parameter. If succeed `true` is returned.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `attr` parameter given and is not a type of a `string`;
+  + if `key` parameter given and is not a type of a `string`.
+<a name="renameXObjElement"></a>
+#### **renameXObjAttribute(object, attr, value\[, key])** => `boolean`
+> since: \[v0.2.0]
+This function tries to rename an attribute with a name given by `attr` parameter to its new name. If succeed `true` is returned.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `attr` | `string` | --- | some attribute |
+| `value` | `string` | --- | new attribute ID |
+| `key` | `string` | --- | some key |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `attr` parameter given and is not a type of a `string`;
+  + if `value` parameter given and is not a type of a `string`;
+  + if `key` parameter given and is not a type of a `string`.
+### Other functions
+<a name="getXObjElement"></a>
+#### **getXObjElement(object, name)** => `?any`
+This function returns an element from a given object by its name or `null` if that element not found.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `name` parameter given and is not a type of a `string`;
+- code: `ERR_XOBJ_INVARG_KEY`
+  + if `name` parameter given and is an empty string.
+<a name="addXObjElement"></a>
+#### **addXObjElement(object, name)** => `object`
+This function adds an element given by `name` parameter to a members of the given object and returns an `object` that represents a status of the operation.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+##### ***result***
+The status of an operation contains 2 fields:
+- `isSucceed` - `boolean` value;
+- `item` - an item which was added or a `null`.
+> <!> The function will fail if a target element exists and it is not an object or an array or not a `null`.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `name` parameter given and is not a type of a `string`;
+- code: `ERR_XOBJ_INVARG_KEY`
+  + if `name` parameter given and is an empty string.
+<a name="insertXObjElement"></a>
+#### **insertXObjElement(object, name\[, options])** => `null`\|`object`\|`object[]`
+This function inserts an empty element named by a `name` parameter into a given object. If succeed the element will be returned or `null` in opposite.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+| `options` | `object` | --- | options |
+For details of an `options` parameter read the appropriate section in the description of the [`insertXObjElementEx`](#insertXObjElementEx) function.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="insertXObjElementEx"></a>
+#### **insertXObjElementEx(object, name\[, options])** => `object`
+> since: \[v0.2.0]
+This function inserts an empty element named by a `name` parameter into a given object and returns an `object` that represents a status of the operation.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+| `options` | `object` | --- | options |
+An `options` parameter contains the following parameters:
+| option name | value type | default value | description |
+|:---|---|---:|:---|
+| `force` | `boolean` | `false` | modifies the functions behavior |
+| `ripOldies` | `boolean` | `false` | it prevents a replacement of an element which exists and is an object or an array. Applied only if `force` option is set to `true` |
+| `acceptIfList` | `boolean` | `false` | it defines whether a list elements is treated as a type of an `object` |
+An `options.force` parameter modifies the functions behavior as follows:
+- when set to `true`, the addressed element will be replaced with an empty element.
+- when set to `false`, if the target element exists and is not an object or an array, the function will failed.
+##### ***result***
+The status of an operation contains 2 fields:
+- `isSucceed` - `boolean` value;
+- `item` - an item which was inserted or a `null`.
+> <!> If a target element exists and it is not a `null`, the function behavior defined by the given options. When a required conditions not met, the function failed.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `name` parameter given and is not a type of a `string`;
+- code: `ERR_XOBJ_INVARG_KEY`
+  + if `name` parameter given and is an empty string.
+<a name="deleteXObjElement"></a>
+#### **deleteXObjElement(object, name)** => `boolean`
+This function deletes an element addressed by `name` parameter from a given object. If succeed `true` is returned.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="deleteXObjElementEx"></a>
+#### **deleteXObjElementEx(object, name)** => `object`
+This function deletes an element addressed by `name` parameter from a given object and returns an `object` that represents a status of the operation.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+##### ***result***
+The status of an operation contains 2 fields:
+- `isSucceed` - `boolean` value;
+- `item` - an item which was deleted or a `null`.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `name` parameter given and is not a type of a `string`;
+- code: `ERR_XOBJ_INVARG_KEY`
+  + if `name` parameter given and is an empty string.
+<a name="renameXObjElement"></a>
+#### **renameXObjElement(object, name, value)** => `boolean`
+This function renames an element addressed by `name` for the given object. If succeed `true` is returned.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+| `value` | `string` | --- | new element ID |
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `name` parameter given and is not a type of a `string`;
+  + id `value` parameter given and is not a type of a `string`.
+### Other special functions
+<a name="evalXObjEName"></a>
+#### **evalXObjEName(value)** => `null`\|`number`\|`string`
+This function evaluates a given value whether it can be accepted as a valid element ID and returns a result.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value to evaluate |
+##### ***result***
+The dependencies of a resulted value returned by the function given in the following table:
+| given value | value type of the result |
+|:---|---|
+| value is an integer positive number or a string that can be converted to a such number | `number` |
+| any other string that can\'t be converted to a number | `string` |
+| any other cases | `null` |
+<a name="insertXObjEList"></a>
+#### **insertXObjEList(object, name\[, options])** => `null`\|`object[]`
+This function inserts an elements list named by a `name` parameter into a given object. If succeed the list will be returned or `null` in opposite.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+| `options` | `object` | --- | options |
+For details of an `options` parameter read the appropriate section in the description of the [`insertXObjEListEx`](#insertXObjEListEx) function.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="insertXObjEListEx"></a>
+#### **insertXObjEListEx(object, name\[, options])** => `object`
+> since: \[v0.2.0]
+This function inserts an elements list named by a `name` parameter into a given object and returns an `object` that represents a status of the operation.
+##### ***parameters***
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `object` | `object` | --- | some object |
+| `name` | `string` | --- | some child element ID |
+| `options` | `object` | --- | options |
+An `options` parameter contains the following parameters:
+| option name|value type|default value|description|
+|:---|---|---:|:---|
+| `force` | `boolean` | `false` | modifies the functions behavior |
+| `ripOldies` | `boolean` | `false` | it prevents a replacement of an element which exists and has a type of an `array`. Applied only if `force` option is set to `true` |
+An `options.force` parameter modifies the functions behavior as follows:
+- when set to `true`, the addressed element will be replaced with an empty elements list.
+- when set to `false`, if the target element type is an `object`, the function will wraps it in the list.
+- when set to `false`, if the target element exists and is not an object or an array, the function will failed.
+##### ***result***
+The status of an operation contains 2 fields:
+- `isSucceed` - `boolean` value;
+- `item` - an item which was inserted or a `null`.
+> <!> If a target element exists and it is not a `null`, the function behavior defined by the given options. When a required conditions not met, the function failed.
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance;
+- code: `ERR_XOBJ_NSTR`
+  + if `name` parameter given and is not a type of a `string`;
+- code: `ERR_XOBJ_INVARG_KEY`
+  + if `name` parameter given and is an empty string.
+### 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.
+<a name="genXObjENameDescr"></a>
+#### **genXObjENameDescr(name)**
+This function creates a object that contains description of the value given by a `name` parameter.
+A value of the `name` parameter must have some of the following formats:
+1. `<name>`;
+2. `<name>[<child>]`;
+3. `<name>[<child>=<value>]`;
+4. `<name>[@<attribute>]`;
+5. `<name>[@<attribute>=<value>]`;
+> Note: the `<value>` must be quoted if it contains characters like a spaces or square brackets.
+The returned object has following attributes:
+|attribute|value type|description|
+|:---|---|---|
+|`isERR`|`boolean`|set to `true` if error happend|
+|`name`|`string`|contains a name of the element|
+|`conditions`|`object`|contains conditions applied to that element|
+The object `conditions` property (*if present*) contains following attributes:
+|attribute|value type|description|
+|:---|---|---|
+|`type`|`string`||
+|`name`|`string`||
+|`value`|`any`||
+<a name="insertXObjElements"></a>
+#### **insertXObjElements(object, name\[...name_N\[, options]])** => `number`
+This function inserts an elements given by the list of names and returns a quantity of the inserted elements.
+##### ***parameters***
+The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertXObjElement).
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+<a name="insertXObjEChain"></a>
+#### **insertXObjEChain(object, name\[, ...name_N\[, options])**
+This function inserts a chain of the elements listed as a function arguments. If succeed the last inserted element will be returned or `null` if failed.
+> The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertxobjelementobject-name-options--objectarray).
+##### ***exceptions***
+The function throws a `TypeError` exception in case:
+- code: `ERR_XOBJ_NPOBJ`
+  + if `object` parameter is not an `Object` instance.
+### Base class
+#### **TXmlContentParseOptions**
+This class implements an interface for handling XML-parse options.
+##### class constructor
+The class constructor creates a new instance of the class. It receives arguments listed below:
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|---|---|a host object.|
+|`options`|`object`|---|an options settings.|
+##### class properties
+The table below describes a properties of a `TXmlContentParseOptions` class:
+|name|read only|description|
+|:---|---|:---|
+|settings|yes|presents a current options|
+|xml2js|yes|returns an options for an XML-to-JS converter|
+|js2xml|yes|returns an options for an JS-to-XML converter|
+##### class methods (*static*)
+###### **createNewOptionsSet(obj)**
+This method transforms a given object to a set of accepted parser options.