@cntwg/xml-lib-js 0.0.16

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+#### *v0.0.16*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - removed method `init()` from `TXmlContentRootElement` class;
+> - some fixes in `xmldoc-lib.js` module.
+
+#### *v0.0.15*
+
+Pre-release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.2;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.0.13;
+
+#### *v0.0.14*
+
+Pre-release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.1;
+> - updated dependency on `@ygracs/xobj-lib-js` module to v0.0.12;
+
+#### *v0.0.13*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - added method `hasAttribute()` to `TXmlAttributesMapper` class;
+> - added method `hasAttribute()` to `TXmlElementController` class;
+> - added method `delChild()` to `TXmlElementController` class;
+> - some fixes in `xmldoc-lib.js` module.
+
+#### *v0.0.12*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - some fixes in `xmldoc-lib.js` module.
+
+#### *v0.0.11*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - some fixes in `xmldoc-lib.js` module;
+> - added method `clear()` to `TXmlAttributesMapper` class;
+> - added method `getTextValue()` to `TXmlElementController` class;
+> - added method `setTextValue()` to `TXmlElementController` class;
+> - added property `maxIndex` to `TXmlElementsListController` class;
+> - change to `TXmlContentRootElement` constructor: `name` param was excluded.
+
+#### *v0.0.10*
+
+Pre-release version.
+
+> - switch dependency from `@cntwg/bsfoc-lib-js` module to `@ygracs/bsfoc-lib-js` module;
+> - updated dependency on `@ygracs/xml-js6` module to v0.0.3b;
+> - added dependency on `@ygracs/xobj-lib-js` module;
+> - deprecate `$module/lib/xObj-lib.js` module;
+> - `xObj-lib.md` deprecated.
+
+#### *v0.0.9*
+
+Pre-release version.
+
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.11;
+> - some fixes in `xmldoc-lib.js` module;
+> - some fixes in `xObj-lib.js` module.
+
+#### *v0.0.8*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - `xObj-lib.md` updated;
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.8;
+> - some fixes in `xmldoc-lib.js` module;
+> - added special static method `__unwrap()` to `TXmlContentRootElement` class.
+
+#### *v0.0.7*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated;
+> - `xObj-lib.md` updated;
+> - added function `getXObjAttributes()` in `xObj-lib.js` module;
+> - fixed some errors in `xmldoc-lib.js` module;
+> - added method `addChild()` to `TXmlElementController` class;
+> - added special method `_addChildRaw()` to `TXmlElementController` class;
+> - add tests of 'TXmlElementController' class for `xmldoc-lib.js` module;
+> - add tests of 'TXmlElementsListController' class for `xmldoc-lib.js` module;
+> - add tests of 'TXmlContentContainer' class for `xmldoc-lib.js` module.
+
+#### *v0.0.6*
+
+Pre-release version.
+
+> - `xObj-lib.md` updated;
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.7;
+> - updated dependency on `@ygracs/xml-js6` module to v0.0.3;
+> - fixed some errors in `xObj-lib.js` module;
+> - added function `writeXObjParamEx()` in `xObj-lib.js` module;
+> - removed function `writeXObjParamAsStr()` from `xObj-lib.js` module;
+> - added function `writeXObjAttrEx()` in `xObj-lib.js` module;
+> - removed function `writeXObjAttrAsStr()` from `xObj-lib.js` module;
+> - added function `addXObjElement()` in `xObj-lib.js` module;
+> - added function `deleteXObjElement()` in `xObj-lib.js` module;
+> - added function `deleteXObjElementEx()` in `xObj-lib.js` module;
+> - added function `renameXObjElement()` in `xObj-lib.js` module;
+> - add tests for `xObj-lib.js` module.
+
+#### *v0.0.5*
+
+Pre-release version.
+
+> - `README.md` updated;
+> - `xmldoc-lib.md` updated;
+> - removed method `_unwrap()` from class `TXmlElementController`;
+> - added method `saveToFileSync()` to class `TXmlContentContainer`;
+> - added method `loadFromFileSync()` to class `TXmlContentContainer`.
+
+#### *v0.0.4*
+
+Pre-release version.
+
+> - `xmldoc-lib.md` updated.
+
+#### *v0.0.3*
+
+Pre-release version.
+
+> - `README.md` updated;
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.6;
+> - added dependency on `@ygracs/xml-js6` module;
+> - include `$module/lib/xmldoc-lib.js` module;
+> - license included.
+
+#### *v0.0.1-v0.0.2*
+
+Pre-release version.

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2019-2022 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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+|***rev.*:**|0.1.2|
+|:---|---:|
+|***date***:|2022-09-06|
+
+## Introduction
+
+This module provide a base functionality for handling an XML-documents.
+
+### 1. xObj-manipulator
+
+xObj-manipulator is a set of functions (see docs for [`@ygracs/xobj-lib-js` module](https://gitlab.com/ygracs/xobj-lib-js)).
+
+### 2. a set of XML-document constants and components
+
+- constants:
+
+	+ `XML_DEF_ROOT_ETAG_NAME`;
+	+ `XML_DEF_PARSE_OPTIONS`;
+	+ `DEF_XML_ROOT_ETAG_NAME` (*will deprecate*);
+	+ `DEF_XML_PARSE_OPTIONS` (*will deprecate*).
+
+- classes:
+
+	+ `TXmlAttributesMapper`;
+	+ `TXmlElementController`;
+	+ `TXmlElementsListController`;
+	+ `TXmlContentParseOptions`;
+	+ `TXmlContentDeclaration`;
+	+ `TXmlContentRootElement`;
+	+ `TXmlContentContainer`.
+
+For more read the `xmldoc-lib.md` in the project `doc` directory.

package/doc/xmldoc-lib.md

@@ -0,0 +1,455 @@
+>|***rev.*:**|0.1.18|
+>|:---|---:|
+>|date:|2022-09-06|
+
+## Intoduction
+
+This paper describes a constants and an object classes provided by `xmldoc-lib.js` module.
+
+## Module constants
+
+### **DEF\_XML\_PARSE_OPTIONS** or **XML\_DEF\_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`|
+
+### **DEF\_XML\_ROOT\_ETAG_NAME** or **XML\_DEF\_ROOT\_ETAG_NAME**
+
+This constant defines a default value for naming the root element for XML-document. Its value is `root`.
+
+## Module classes
+
+### **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.
+
+### **TXmlAttributesMapper**
+
+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:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|---|---|a host object that holds an attributes|
+|`options`|`object`|---|an options settings|
+
+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`*)|
+
+#### class properties
+
+|name|read only|description|
+|:---|---|:---|
+|`entries`|yes|returns array of entries for all existing attributes|
+
+
+#### class methods
+
+##### **hasAttribute(name)**
+
+This method checks whether or not an attribute addressed by a `name` exists. If attribute exists, 'true' is returned.
+
+##### **getAttribute(name)**
+
+This method returns an attribute value addressed by a `name`. If attribute is not exists the empty string is returned.
+
+##### **setAttribute(name, value)**
+
+This method sets an attribute value addressed by a `name` and return `true` if succeed.
+
+##### **delAttribute(name)**
+
+This method clears an attribute value addressed by a `name`.
+
+##### **clear()**
+
+This method clears all attributes.
+
+### **TXmlElementController**
+
+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:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|---|---|a host object|
+|`options`|`object`|---|an options settings|
+
+The `options` structure is listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`proxyModeEnable`|`boolean`|`false`|<*reserved*>|
+|`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`)|
+
+#### 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|
+
+#### class methods
+
+##### **hasAttribute(name)**
+
+This method checks whether or not an attribute addressed by a `name` exists. If attribute exists, 'true' is returned.
+
+##### **getAttribute(name)**
+
+This method returns an attribute value addressed by a `name`. If attribute is not exists the empty string is returned.
+
+##### **setAttribute(name, value)**
+
+This method sets an attribute value addressed by a `name` and return `true` if succeed.
+
+##### **delAttribute(name)**
+
+This method clears an attribute value addressed by a `name`.
+
+##### **getTextValue()**
+
+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)**
+
+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> ]`.
+
+##### **getChild(name)**
+
+This method returns a child element addressed by `name`.
+
+##### **addChild(name)**
+
+This method adds an element as a child element addressed by a `name`.
+
+##### **delChild(name)**
+
+This method deletes a child element addressed by a `name`.
+
+> Warning: method not fully implemented. not used for list like elements.
+
+##### **clear()**
+
+This method clears an element content.
+
+#### class methods (*special*)
+
+##### **_getChildRaw(name)**
+
+This method returns a child element addressed by `name` as object.
+
+##### **_addChildRaw(name)**
+
+This method adds an element as a child element addressed by `name`.
+
+##### **_setChildRaw(name, obj)**
+
+This method inserts a given object as a child element addressed by `name`.
+
+#### class methods (*static*)
+
+##### **__unwrap(item)**
+
+This method returns a host for an element as an object. If failed `null` is returned.
+
+##### **clear(item)**
+
+This method clears an `item` content.
+
+### **TXmlElementsListController**
+
+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:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|---|---|a host object of an array type.|
+|`options`|`object`|---|an options settings.|
+
+The `options` structure is listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`proxyModeEnable`|`boolean`|`false`|<*reserved*>|
+|`isNullItemsAllowed`|`boolean`|`false`|<*reserved*>|
+|`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`)|
+
+#### 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|
+|`isNullItemsAllowed`|`boolean`|yes|indicates whether a list may be filled  with the null-elements or not|
+
+#### class methods
+
+##### **clear()**
+
+This method clears a list.
+
+##### **isEmpty()**
+
+This method returns `true` if a list has no elements and `false` otherwise.
+
+##### **isNotEmpty()**
+
+This method returns `true` if a list contains at least one element and `false` otherwise.
+
+##### **chkIndex(index)**
+
+This method checks if a given index fits a range of elements within the list. If so `true` is returned.
+
+##### **isValidItem(obj)**
+
+This method checks whether or not a given element is valid.
+
+##### **getItem(index)**
+
+This method returns an element addressed by `index`. If failed `null` is returned.
+
+##### **addItem(obj)**
+
+This method adds an element to a list members. If succeed an index of the element is returned.
+
+##### **setItem(index, obj)**
+
+This method replaces an element addressed by `index` with a new element. If succeed `true` is returned.
+
+##### **insItem(index, obj)**
+
+This method inserts an element in the position addressed by `index`. If succeed `true` is returned.
+
+##### **delItem(index)**
+
+This method deletes an element addressed by `index`. If succeed `true` is returned.
+
+##### **loadItems(items, options)**
+
+This method loaded a list of elements listed by `items` and returns a quantity of a successfuly added elements.
+
+#### class methods (*special*)
+
+##### **_getItemRaw(name)**
+
+This method returns an element addressed by `index` as object. If failed `null` is returned.
+
+##### **_addItemRaw(obj)**
+
+This method adds an element to a list members as object. If succeed an index of the element is returned.
+
+##### **_setItemRaw(index, obj)**
+
+This method replaces an element addressed by `index` with a new element which is saved as raw object. If succeed `true` is returned.
+
+##### **_insItemRaw(index, obj)**
+
+This method inserts an element as a raw object in the position addressed by `index`. If succeed `true` is returned.
+
+### **TXmlContentDeclaration**
+
+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:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|`object`|---|a host object for the document content.|
+|`options`|`object`|---|an options settings.|
+
+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`)|
+
+#### 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|
+
+#### class methods (*special*)
+
+##### **init()**
+
+This method initializes element with a default values.
+
+### **TXmlContentRootElement**
+
+This class extends functionality of a `TXmlElementController` class.
+
+#### class constructor
+
+The class constructor creates a new instance of the class. It receives arguments listed below:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|`object`|---|a host object for the document content|
+|`options`|`object`|---|an options settings|
+
+The `options` structure is listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`rootETagName`|`string`|`root`|contains a the name of a tag that represents a root element|
+|`autoBindRoot`|`boolean`|`true`|<*reserved*>|
+|`proxyModeEnable`|`boolean`|`false`|<*reserved*>|
+|`isNullItemsAllowed`|`boolean`|`false`|<*reserved*>|
+|`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`)|
+
+#### class properties
+
+|name|read only|description|
+|:---|---|:---|
+|tagName|no||
+
+#### class methods (*static*)
+
+##### **__unwrap(item\[, options])**
+
+This method returns a host for an element as an object. If failed `null` is returned.
+
+The `options` parameter, if given, change a behavoir for the method. If set to 'true' the given instance checks aganst inheritance from a `TXmlContentRootElement`, if else, from a `TXmlElementController` class.
+
+#### class methods (*special*)
+
+### **TXmlContentContainer**
+
+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 `options` structure is listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`rootETagName`|`string`|`root`|contains a the name of a tag that represents a root element|
+|`autoBindRoot`|`boolean`|`true`|<*reserved*>|
+|`proxyModeEnable`|`boolean`|`false`|<*reserved*>|
+|`isNullItemsAllowed`|`boolean`|`false`|<*reserved*>|
+|`parseOptions`|`object`|`EMPTY_OBJECT`|contains a XML-parse options (see description for `XML_DEF_PARSE_OPTIONS`)|
+
+#### class properties
+
+|property name|read only|description|
+|:---|---|:---|
+|rootElement|yes|returns a document root element|
+
+#### class methods
+
+##### **clear()**
+
+This method clears a document content.
+
+##### **saveToXMLString()**
+
+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`.
+
+##### **loadFromXMLString(str)**
+
+This method loads a document content from a string given by `str`.
+
+##### **loadFromFile(src)**
+
+This method loads a document content from a file addressed by `src`.
+
+> This is `async` method.
+
+##### **loadFromFileSync(src)**
+
+This method loads a document content from a file addressed by `src`.
+
+#### class methods (*special*)
+
+##### **asJSON()**
+
+This method returns a document content as a string in the JSON-format.
+
+##### **_bindContent(obj\[, options])**
+
+This method binds a given object as a document content.

package/index.js

@@ -0,0 +1,31 @@
+// [v0.1.007-20220722]
+
+// === module init block ===
+
+const xObj = require('@ygracs/xobj-lib-js');
+const xmldoc = require('./lib/xmldoc-lib.js');
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+// === module exports block ===
+
+exports.xObj = xObj;
+
+// will deprecate
+exports.DEF_XML_PARSE_OPTIONS = xmldoc.DEF_XML_PARSE_OPTIONS;
+// will deprecate
+exports.DEF_XML_ROOT_ETAG_NAME = xmldoc.DEF_XML_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;
+
+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;