@ygracs/xepg-lib-js 0.0.21 → 0.0.23

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+#### *v0.0.23*
+
+Pre-release version.
+
+> - update `xepgdoc-lib.md`;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.2.3;
+> - update dependency on `@ygracs/dtf-lib-js` module to v0.0.28;
+> - update dependency on `@ygracs/xobj-lib-js` module to v0.2.2;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.0.5-b;
+> - add dependency on `@cntwg/file-helper` module;
+> - remove `$module/lib/file-helper.js`;
+> - improve behavior for a getter of a `rating` property of a `TXEpgScheduleItem`-class;
+> - add functions: readAsTagName, `readAsAttrName`, valueToElementID;
+> - other fixes.
+
+#### *v0.0.22*
+
+Pre-release version.
+
+> - update `xepgdoc-lib.md`;
+> - add new `TXEpgScheduleItem` class;
+> - add new `TXEpgChannelContainer` class;
+> - add new `schedule` method to a `TXEpgSchedulesList` class;
+> - add new `channel` method to a `TXEpgHeaderContainer` class;
+> - add new `channel` method to a `TXEpgHeaderContainer` class;
+> - add new `setType` method to a `TXEpgDTSProvider` class;
+> - deprecate a `setChannelInfo` method of a `TXEpgHeaderContainer` class;
+> - change name for a property `Provider` of a `TXEpgHeaderContainer` class into `provider`;
+> - change name for a property `Header` of a `TXEpgContentProvider` class into `header`;
+> - change name for a property `Provider` of a `TXEpgContentProvider` class into `provider`;
+> - other fixes.
+
 #### *v0.0.21*
 
 Pre-release version.

package/README.md

@@ -1,6 +1,6 @@
-|***rev.*:**|0.0.7|
+|***rev.*:**|0.0.9|
 |:---|---:|
-|***date***:|2025-02-28|
+|***date***:|2025-03-06|
 
 ## Introduction
 
@@ -18,9 +18,11 @@ This module contains the following components:
 
 - classes:
 
+	+ `TXEpgScheduleItem`;
 	+ `TXEpgSchedulesList`;
 	+ `TXEpgDTSProvider`;
 	+ `TXEpgProviderContainer`;
+	+ `TXEpgChannelContainer`;
 	+ `TXEpgHeaderContainer`;
 	+ `TXEpgContentContainer`.
 

package/doc/xepgdoc-lib.md

@@ -1,12 +1,12 @@
-|***rev.*:**|0.1.18|
+|***rev.*:**|0.1.28|
 |:---|---:|
-|***date***:|2025-02-27|
+|***date***:|2025-04-24|
 
 ## Introduction
 
 This paper describes a constants and an object classes provided by `xepgdoc-lib.js` module.
 
-### Base type definitions
+## 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 or a class method descriptions.
 
@@ -55,16 +55,183 @@ This descriptor is an `object` that describes a content provider.
 
 | property name | value type | optional | description |
 |:---|---|---:|:---|
-| `time` | `number` | a schedule start time |
-| `title` | `string` | a schedule title |
-| `cat` | `string` | a schedule category |
-| `pcmark` | `number` | a schedule rating |
-| `descr` | `string` | a schedule description |
+| `time` | `number` | no | a schedule start time |
+| `title` | `string` | no | a schedule title |
+| `cat` | `string` | yes | a schedule category |
+| `pcmark` | `number` | yes | a schedule rating |
+| `descr` | `string` | yes | a schedule description |
 
 ## Module constants
 
+## Module functions
+
+### 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="readAsTagName"></a>
+#### **readAsTagName(value)** => `string`
+
+> since: \[`v0.0.23`]
+
+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.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value to read |
+
+<a name="readAsAttrName"></a>
+#### **readAsAttrName(value)** => `string`
+
+> since: \[`v0.0.23`]
+
+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.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value to read |
+
+<a name="valueToElementID"></a>
+#### **valueToElementID(value)**
+
+> since: \[`v0.0.23`]
+
+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.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value to read |
+
 ## Module classes
 
+<a name="TXEpgScheduleItem"></a>
+### **TXEpgScheduleItem**
+
+> since: `v0.0.22`
+
+This class provides a functionality for handle an EPG-schedule element.
+
+#### class constructor
+
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+|`object`|`object`|---|a host object|
+|`options`|`object`|---|an options settings|
+
+#### class properties
+
+<a name="TXEpgScheduleItem+time"></a>
+##### **time**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a schedule start time value as a timestamp |
+
+<a name="TXEpgScheduleItem+title"></a>
+##### **title**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | yes | contains a schedule title |
+
+<a name="TXEpgScheduleItem+category"></a>
+##### **category**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | yes | contains a schedule category |
+
+<a name="TXEpgScheduleItem+rating"></a>
+##### **rating**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a schedule rating value (*aka pcmark*) |
+
+<a name="TXEpgScheduleItem+descr"></a>
+##### **descr**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | yes | contains a schedule description |
+
+<a name="TXEpgScheduleItem+dtstype"></a>
+##### **dtstype**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a "dtstype"-value |
+
+<a name="TXEpgScheduleItem+curDocTZ"></a>
+##### **curDocTZ**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a current TimeZone |
+
+#### class methods
+
+<a name="TXEpgScheduleItem+getInfo"></a>
+##### **getInfo()** => `xepgShedInfoDesc`
+
+This method returns an object that contains a schedule information.
+
+<a name="TXEpgScheduleItem+setTime"></a>
+##### **setTime(value)** => `boolean`
+
+This method tries to set a schedule start time. If succeed `true` returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `number`, `string`, `Date` | --- | some value |
+
+<a name="TXEpgScheduleItem+setTitle"></a>
+##### **setTitle(value)** => `boolean`
+
+This method tries to set a schedule title. If succeed `true` returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | some value |
+
+<a name="TXEpgScheduleItem+setCategory"></a>
+##### **setCategory(value)** => `boolean`
+
+This method tries to set a schedule category. If succeed `true` returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | some value |
+
+<a name="TXEpgScheduleItem+setRating"></a>
+##### **setRating(value)** => `boolean`
+
+This method tries to set a schedule rating. If succeed `true` returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `number`, `string` | --- | some rating value |
+
+<a name="TXEpgScheduleItem+setDescr"></a>
+##### **setDescr(value)** => `boolean`
+
+This method tries to set a schedule description. If succeed `true` returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | some value |
+
+<a name="TXEpgScheduleItem+saveToXMLString"></a>
+##### **saveToXMLString()** => `string`
+
+This method saves an element content to a string in an XML-format.
+
 <a name="TXEpgSchedulesList"></a>
 ### **TXEpgSchedulesList**
 
@@ -85,8 +252,6 @@ The class constructor receives arguments listed below:
 
 #### class properties
 
-The table below describes a properties of a `TXEpgSchedulesList` class:
-
 <a name="TXEpgSchedulesList+schedQty"></a>
 ##### **schedQty**
 
@@ -135,6 +300,17 @@ This method checks if a given `value` represents a valid schedule index and if s
 |:---|---|---:|:---|
 | `value` | `number`, `string` | --- | a value to be verified |
 
+<a name="TXEpgSchedulesList+schedule"></a>
+##### **schedule(index)** => `TXEpgScheduleItem`
+
+> since: `v0.0.22`
+
+This method returns an object that contains a schedule element.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
 <a name="TXEpgSchedulesList+getScheduleInfo"></a>
 ##### **getScheduleInfo(index)** => `xepgShedInfoDesc`
 
@@ -250,9 +426,86 @@ This method saves an element content to a string.
 
 ##### **init()**
 
+<a name="TXEpgChannelContainer"></a>
+### **TXEpgChannelContainer**
+
+> since: `v0.0.22`
+
+This class provides a functionality for handle an EPG-channel element.
+
+#### class constructor
+
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+|`object`|`object`|---|a host object|
+|`options`|`object`|---|an options settings|
+
+#### class properties
+
+<a name="TXEpgChannelContainer+id"></a>
+##### **id**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | yes | contains a channel ID |
+
+<a name="TXEpgChannelContainer+name"></a>
+##### **name**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | contains a channel name |
+
+<a name="TXEpgChannelContainer+gid"></a>
+##### **gid**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | contains a channel group ID |
+
+<a name="TXEpgChannelContainer+url"></a>
+##### **url**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | contains a channel URL |
+
+#### class methods
+
+<a name="TXEpgChannelContainer+setID"></a>
+##### **setID(value)** => `boolean`
+
+This method tries to set a channel ID. If succeed `true` returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | some value |
+
+<a name="TXEpgChannelContainer+getInfo"></a>
+##### **getInfo()** => `xepgChnInfoDesc`
+
+This method returns a channel info descriptor.
+
+<a name="TXEpgChannelContainer+setInfo"></a>
+##### **setInfo(value)** => `void`
+
+This method tries to load a channel info.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string`, `xepgChnInfoDesc` | --- | some value |
+
 <a name="TXEpgDTSProvider"></a>
 ### **TXEpgDTSProvider**
 
+This class provides a functionality for handle a DTS-provider element.
+
 #### class constructor
 
 The class constructor creates a new instance of the class.
@@ -288,9 +541,24 @@ The `options` structure is listed below:
 |---|---|:---|
 | `number` | no | defines a current TimeZone |
 
+#### class methods
+
+<a name="TXEpgDTSProvider+setType"></a>
+##### **setType(value)** => `boolean`
+
+> since: `v0.0.22`
+
+This method tries to set a provider type.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `number`, `string` | --- | a "dtstype"-value |
+
 <a name="TXEpgHeaderContainer"></a>
 ### **TXEpgHeaderContainer**
 
+This class provides a functionality for handle a EPG-header element.
+
 #### class constructor
 
 The class constructor creates a new instance of the class.
@@ -336,9 +604,25 @@ The `options` structure is listed below:
 <a name="TXEpgHeaderContainer+Provider"></a>
 ##### **Provider**
 
+> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`provider` property](#TXEpgHeaderContainer+provider) instead.
+
+<a name="TXEpgHeaderContainer+provider"></a>
+##### **provider**
+
+> since: `v0.0.22`
+
 | property type | read only | description |
 |---|---|:---|
-| `TXEpgProviderContainer` | yes | returns a `TXEpgProviderContainer` |
+| `TXEpgProviderContainer` | yes | returns a `TXEpgProviderContainer` instance |
+
+<a name="TXEpgHeaderContainer+channel"></a>
+##### **channel**
+
+> since: `v0.0.22`
+
+| property type | read only | description |
+|---|---|:---|
+| `TXEpgChannelContainer` | yes | returns a `TXEpgChannelContainer` instance |
 
 #### class methods
 
@@ -383,6 +667,8 @@ An object contains the following fields:
 <a name="TXEpgHeaderContainer+setChannelInfo"></a>
 ##### **setChannelInfo(obj)** => `void`
 
+> \[!] WARNING: `[since v0.0.22]` deprecated.
+
 This method fills a channel information with a given data.
 
 | parameter name | value type | default value | description |
@@ -449,30 +735,44 @@ The `options` structure is listed below:
 <a name="TXEpgContentProvider+Header"></a>
 ##### **Header**
 
+> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`header` property](#TXEpgContentProvider+header) instead.
+
+<a name="TXEpgContentProvider+header"></a>
+##### **header**
+
+> since: `v0.0.22`
+
 | property type | read only | description |
 |---|---|:---|
-| `TXEpgHeaderContainer` | yes | returns a `TXEpgHeaderContainer` |
+| `TXEpgHeaderContainer` | yes | returns a `TXEpgHeaderContainer` instance |
 
 <a name="TXEpgContentProvider+Provider"></a>
 ##### **Provider**
 
+> \[!] NOTE: `[since v0.0.22]` deprecated. Use [`provider` property](#TXEpgContentProvider+provider) instead.
+
+<a name="TXEpgContentProvider+provider"></a>
+##### **provider**
+
+> since: `v0.0.22`
+
 | property type | read only | description |
 |---|---|:---|
-| `TXEpgProviderContainer` | yes | returns a `TXEpgProviderContainer` |
+| `TXEpgProviderContainer` | yes | returns a `TXEpgProviderContainer` instance |
 
 <a name="TXEpgContentProvider+dts"></a>
 ##### **dts**
 
 | property type | read only | description |
 |---|---|:---|
-| `TXEpgDTSProvider` | yes | returns a `TXEpgDTSProvider` |
+| `TXEpgDTSProvider` | yes | returns a `TXEpgDTSProvider` instance |
 
 <a name="TXEpgContentProvider+SchedulesList"></a>
 ##### **SchedulesList**
 
 | property type | read only | description |
 |---|---|:---|
-| `TXEpgSchedulesList` | yes | returns a `TXEpgSchedulesList` |
+| `TXEpgSchedulesList` | yes | returns a `TXEpgSchedulesList` instance |
 
 #### class methods
 

package/index.js

@@ -1,8 +1,8 @@
-// [v0.0.009-20250225]
+// [v0.0.010-20250228]
 
 // === module init block ===
 
-const xepg_doc = require('./lib/xepgdoc-lib.js');
+const xepgdoc = require('./lib/xepgdoc-lib.js');
 
 const xObj = require('@ygracs/xobj-lib-js');
 
@@ -13,14 +13,15 @@ const xObj = require('@ygracs/xobj-lib-js');
 // === module exports block ===
 
 /**/// v1 branch
-exports.TXEpgContentProvider = xepg_doc.TXEpgContentProvider;
-exports.TXEpgSchedulesList = xepg_doc.TXEpgSchedulesList;
-exports.TXEpgDTSProvider = xepg_doc.TXEpgDTSProvider;
-exports.TXEpgProviderContainer = xepg_doc.TXEpgProviderContainer;
-exports.TXEpgHeaderContainer = xepg_doc.TXEpgHeaderContainer;
+module.exports.TXEpgContentProvider = xepgdoc.TXEpgContentProvider;
+module.exports.TXEpgScheduleItem = xepgdoc.TXEpgScheduleItem;
+module.exports.TXEpgSchedulesList = xepgdoc.TXEpgSchedulesList;
+module.exports.TXEpgDTSProvider = xepgdoc.TXEpgDTSProvider;
+module.exports.TXEpgProviderContainer = xepgdoc.TXEpgProviderContainer;
+module.exports.TXEpgHeaderContainer = xepgdoc.TXEpgHeaderContainer;
 
 // re-export stuff from `@ygracs/xobj-lib-js` module
-exports.TXmlContentParseOptions = xObj.TXmlContentParseOptions;
+module.exports.TXmlContentParseOptions = xObj.TXmlContentParseOptions;
 
 /**/// will deprecate
-exports.TXepgDTSProvider = xepg_doc.TXepgDTSProvider;
+module.exports.TXepgDTSProvider = xepgdoc.TXepgDTSProvider;