@ygracs/xepg-lib-js 0.0.19 → 0.0.21

package/doc/xepgdoc-lib.md

@@ -1,57 +1,151 @@
-|***rev.*:**|0.0.14|
+|***rev.*:**|0.1.18|
 |:---|---:|
-|***date***:|2024-07-17|
+|***date***:|2025-02-27|
 
 ## Introduction
 
 This paper describes a constants and an object classes provided by `xepgdoc-lib.js` module.
 
+### 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.
+
+<a name="typedef+fsoDescr"></a>
+#### `fsoDescr` - descriptor
+
+This descriptor is an `object` that describes a status for an operation with some FS-object (*e.g. object such as a file*).
+
+| property name | value type | optional | description |
+|:---|---|---:|:---|
+| `isERR` | `boolean` | no | a flag which indicates whether an error was happen |
+| `errCode` | `number` | yes | an error code |
+| `errEvent` | `string` | no | an error event identifier |
+| `errMsg` | `string` | no | an error message |
+| `source` | `string` | no | path to a file |
+| `content` | `any` | no | content |
+
+<a name="typedef+xepgProvInfoDesc"></a>
+#### `xepgProvInfoDesc` - descriptor
+
+This descriptor is an `object` that describes a content provider.
+
+| property name | value type | optional | description |
+|:---|---|---:|:---|
+| `name` | `string` | yes | a provider name |
+| `version` | `string` | yes | a provider version |
+| `schema` | `string` | no | a document schema version |
+| `doctype` | `string` | no | a document type |
+
+<a name="typedef+xepgChnInfoDesc"></a>
+#### `xepgChnInfoDesc` - descriptor
+
+This descriptor is an `object` that describes a channel info.
+
+| property name | value type | optional | description |
+|:---|---|---:|:---|
+| `chnid` | `srting` | no | a channel ID |
+| `chname` | `string` | no | a name of the channel |
+| `chngid` | `string` | yes | a channel 'Group ID' |
+| `srcurl` | `string` | yes | a link to source |
+
+<a name="typedef+xepgShedInfoDesc"></a>
+#### `xepgShedInfoDesc` - descriptor
+
+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 |
+
 ## Module constants
 
 ## Module classes
 
+<a name="TXEpgSchedulesList"></a>
 ### **TXEpgSchedulesList**
 
 This class provides a functionality for handle an EPG-schedules list.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
 
-|name|type|default value|description|
+##### constructor parameters
+
+The class constructor receives arguments listed below:
+
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`object`|---|---|a host object|
+|`object`|`array`|---|a host object|
 |`options`|`object`|---|an options settings|
 
 #### class properties
 
 The table below describes a properties of a `TXEpgSchedulesList` class:
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`schedQty`|`number`|yes|returns a quantity of the elements|
-|`dtstype`|`index`|yes|returns a "dtstype"-value|
-|`curDocTZ`|`number`|yes|returns a current TimeZone|
+<a name="TXEpgSchedulesList+schedQty"></a>
+##### **schedQty**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a quantity of the elements the container holds |
+
+<a name="TXEpgSchedulesList+dtstype"></a>
+##### **dtstype**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a "dtstype"-value |
+
+<a name="TXEpgSchedulesList+curDocTZ"></a>
+##### **curDocTZ**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a current TimeZone |
 
 #### class methods
 
-##### **hasNoSchedules()**
+<a name="TXEpgSchedulesList+hasNoSchedules"></a>
+##### **hasNoSchedules()** => `boolean`
 
 This method returns `true` if a document contains no schedules.
 
-##### **hasSchedules()**
+<a name="TXEpgSchedulesList+hasSchedules"></a>
+##### **hasSchedules()** => `boolean`
 
 This method returns `true` if a document contains at least one schedule.
 
-##### **chkScheduleIndex(value)**
+##### **chkScheduleIndex(value)** => `boolean`
+
+> WARNING: This method deprecated (*since `v0.0.20`*). Use `chkIndex` instead.
+
+<a name="TXEpgSchedulesList+chkIndex"></a>
+##### **chkIndex(value)** => `boolean`
+
+> since: `v0.0.20`
 
 This method checks if a given `value` represents a valid schedule index and if so returns `true`.
 
-##### **getScheduleInfo(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `number`, `string` | --- | a value to be verified |
+
+<a name="TXEpgSchedulesList+getScheduleInfo"></a>
+##### **getScheduleInfo(index)** => `xepgShedInfoDesc`
 
 This method returns an object that contains a schedule information.
 
-##### **getAllSchedulesInfo()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="TXEpgSchedulesList+getAllSchedulesInfo"></a>
+##### **getAllSchedulesInfo()** => `xepgShedInfoDesc[]`
 
 This method returns an array that contains an information for all available schedules.
 
@@ -59,18 +153,23 @@ This method returns an array that contains an information for all available sche
 
 ##### **asJSON()**
 
+<a name="TXEpgProviderContainer"></a>
 ### **TXEpgProviderContainer**
 
 This class implements a structure that holds an information about a program provider within which the content of the document was written.
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
-|`object`|---|---|a host object|
-|`options`|---|---|an option settings|
+|`object`|`object`|---|a host object|
+|`options`|`object`|---|an option settings|
 
 The `options` structure is listed below:
 
@@ -80,38 +179,87 @@ The `options` structure is listed below:
 
 #### class properties
 
-The table below describes a properties of a `TXEpgProviderContainer` class:
+<a name="TXEpgProviderContainer+name"></a>
+##### **name**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | contains a provider name |
+
+<a name="TXEpgProviderContainer+version"></a>
+##### **version**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | contains a provider version string |
+
+<a name="TXEpgProviderContainer+schema"></a>
+##### **schema**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | contains a document schema version |
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`name`|`string`|no|defines a provider name|
-|`version`|`string`|no|defines a provider version string|
-|`schema`|`string`|no|defines a document schema version|
-|`doctype`|`string`|no|defines a document type|
+<a name="TXEpgProviderContainer+doctype"></a>
+##### **doctype**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | contains a document type |
 
 #### class methods
 
-##### **setName(value)**
+<a name="TXEpgProviderContainer+setName"></a>
+##### **setName(value)** => `boolean`
 
 This method sets a name of a provider to a given `value`.
 
-##### **getInfo()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | provider name |
+
+<a name="TXEpgProviderContainer+getInfo"></a>
+##### **getInfo()** => `xepgProvInfoDesc`
 
-This method returns an `object` that contains information about content provider.
+This method returns an `object` that contains information about content provider. An object contains a field listed in the table below:
 
-##### **setInfo(obj)**
+|property name|value type|description|
+|:---|---|:---|
+|`name`|`string`|a provider name|
+|`version`|`string`|a provider version|
+|`schema`|`string`|a document schema version|
+|`doctype`|`string`|a document type|
+
+<a name="TXEpgProviderContainer+setInfo"></a>
+##### **setInfo(obj)** => `void`
 
 This method loads information about content provider.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `xepgProvInfoDesc` | --- | provider info descriptor |
+
+<a name="TXEpgProviderContainer+saveToXMLString"></a>
+##### **saveToXMLString()** => `string`
+
+> since: `v0.0.20`
+
+This method saves an element content to a string.
+
 #### class methods (*special*)
 
 ##### **init()**
 
+<a name="TXEpgDTSProvider"></a>
 ### **TXEpgDTSProvider**
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
@@ -126,18 +274,30 @@ The `options` structure is listed below:
 
 #### class properties
 
-The table below describes a properties of a `TXEpgDTSProvider` class:
+<a name="TXEpgDTSProvider+dtstype"></a>
+##### **dtstype**
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`dtstype`|`index`|no|defines a "dtstype"-value|
-|`curDocTZ`|`number`|no|defines a current TimeZone|
+| property type | read only | description |
+|---|---|:---|
+| `number` | no | defines a "dtstype"-value |
 
+<a name="TXEpgDTSProvider+curDocTZ"></a>
+##### **curDocTZ**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | no | defines a current TimeZone |
+
+<a name="TXEpgHeaderContainer"></a>
 ### **TXEpgHeaderContainer**
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
@@ -152,50 +312,85 @@ The `options` structure is listed below:
 
 #### class properties
 
-The table below describes a properties of a `TXEpgHeaderContainer` class:
+<a name="TXEpgHeaderContainer+dts"></a>
+##### **dts**
 
-|property name|property type|read only|description|
-|:---|---|---:|:---|
-|`dtstype`|`index`|no|defines a "dtstype"-value|
-|`curDocTZ`|`number`|no|defines a current TimeZone|
-|`Provider`|`TXEpgProviderContainer`|yes|returns a `TXEpgProviderContainer`|
-|`dts`|`TXepgDTSProvider`|yes|returns a `TXEpgDTSProvider`|
+| property type | read only | description |
+|---|---|:---|
+| `TXEpgDTSProvider` | yes | returns a `TXEpgDTSProvider` |
+
+<a name="TXEpgHeaderContainer+dtstype"></a>
+##### **dtstype**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | no | defines a "dtstype"-value |
+
+<a name="TXEpgHeaderContainer+curDocTZ"></a>
+##### **curDocTZ**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | no | defines a current TimeZone |
+
+<a name="TXEpgHeaderContainer+Provider"></a>
+##### **Provider**
+
+| property type | read only | description |
+|---|---|:---|
+| `TXEpgProviderContainer` | yes | returns a `TXEpgProviderContainer` |
 
 #### class methods
 
-##### **getDocumentDT()**
+<a name="TXEpgHeaderContainer+getDocumentDT"></a>
+##### **getDocumentDT()** => `number`
 
-This method returns a time value of a document creation.
+This method returns a time value of a document creation as a timestamp.
 
-##### **setDocumentDT()**
+<a name="TXEpgHeaderContainer+setDocumentDT"></a>
+##### **setDocumentDT()** => `void`
 
 This method sets a time value of a document creation.
 
-##### **getDocumentEDT()**
+<a name="TXEpgHeaderContainer+getDocumentEDT"></a>
+##### **getDocumentEDT()** => `number`
 
-This method returns a time value from which a document is expired.
+This method returns a time value from which a document is expired as a timestamp.
 
-##### **setDocumentEDT(value)**
+<a name="TXEpgHeaderContainer+setDocumentEDT"></a>
+##### **setDocumentEDT(value)** => `void`
 
 This method sets a time value at which a document will be expired.
 
-##### **getChannelInfo()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `number`, `string`, `Date` | --- | document expire time |
+
+<a name="TXEpgHeaderContainer+getChannelInfo"></a>
+##### **getChannelInfo()** => `xepgChnInfoDesc`
 
-This method returns an object which contains a channel information.
+This method returns an `object` which contains a channel information.
 
 An object contains the following fields:
 
 |field name|field type|description|
 |:---|---|:---|
-|`chnid`|`ID_STRING`|a channel ID|
+|`chnid`|`srting`|a channel ID|
+|`chngid`|`string`|a channel 'Group ID'|
 |`chname`|`string`|a name of the channel|
-|`chngid`|`ID_STRING`|a channel group|
 |`srcurl`|`string`|a link to source|
 
-##### **setChannelInfo(obj)**
+<a name="TXEpgHeaderContainer+setChannelInfo"></a>
+##### **setChannelInfo(obj)** => `void`
 
 This method fills a channel information with a given data.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `xepgChnInfoDesc` | --- | channel info descriptor |
+
+> \[!] NOTE: `[since v0.0.21]` a use of a `string` or `array` types a as values of an `obj` are deprecated and will be dropped soon.
+
 The `obj` parameter can be a string or an array or an object.
 
 If a string is given it mean to contains the `chnid` value.
@@ -208,22 +403,35 @@ If an object is given it contains the following fields:
 
 |field name|field type|description|
 |:---|---|:---|
-|`chnid`|`ID_STRING`|a channel ID|
+|`chnid`|`string`|a channel ID|
 |`chname`|`string`|a name of the channel|
-|`chngid`|`ID_STRING`|a channel group|
+|`chngid`|`string`|a channel group|
 |`srcurl`|`string`|a link to source|
 
-##### **getProviderInfo()**
+<a name="TXEpgHeaderContainer+getProviderInfo"></a>
+##### **getProviderInfo()** => `xepgProvInfoDesc`
 
 This method returns an object which contains an information about document provider.
 
 ##### **setProviderInfo(obj)**
 
+<a name="TXEpgHeaderContainer+saveToXMLString"></a>
+##### **saveToXMLString()** => `string`
+
+> since: `v0.0.20`
+
+This method saves an element content to a string.
+
+<a name="TXEpgContentProvider"></a>
 ### **TXEpgContentProvider**
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives arguments listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives arguments listed below:
 
 |name|type|default value|description|
 |:---|---|---:|:---|
@@ -238,52 +446,93 @@ The `options` structure is listed below:
 
 #### class properties
 
-The table below describes a properties of a `TXEpgContentProvider` class:
+<a name="TXEpgContentProvider+Header"></a>
+##### **Header**
+
+| property type | read only | description |
+|---|---|:---|
+| `TXEpgHeaderContainer` | yes | returns a `TXEpgHeaderContainer` |
+
+<a name="TXEpgContentProvider+Provider"></a>
+##### **Provider**
+
+| property type | read only | description |
+|---|---|:---|
+| `TXEpgProviderContainer` | yes | returns a `TXEpgProviderContainer` |
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`Header`|`TXEpgHeaderContainer`|yes|returns a `TXEpgHeaderContainer`|
-|`Provider`|`TXEpgProviderContainer`|yes|returns a `TXEpgProviderContainer`|
-|`SchedulesList`|`TXEpgSchedulesList`|yes|returns a `TXEpgSchedulesList`|
-|`dts`|`TXEpgDTSProvider`|yes|returns a `TXEpgDTSProvider`|
+<a name="TXEpgContentProvider+dts"></a>
+##### **dts**
+
+| property type | read only | description |
+|---|---|:---|
+| `TXEpgDTSProvider` | yes | returns a `TXEpgDTSProvider` |
+
+<a name="TXEpgContentProvider+SchedulesList"></a>
+##### **SchedulesList**
+
+| property type | read only | description |
+|---|---|:---|
+| `TXEpgSchedulesList` | yes | returns a `TXEpgSchedulesList` |
 
 #### class methods
 
-##### **loadFromString(xmlString, options)**
+<a name="TXEpgContentProvider+saveToXMLString"></a>
+##### **saveToXMLString()** => `string`
 
-> WARNING: This method deprecated (*since `v0.0.18`*). Use `loadFromXMLString` instead.
+This method saves a document content to a string.
 
-##### **loadFromXMLString(xmlString, options)**
+<a name="TXEpgContentProvider+saveToFileSync"></a>
+##### **saveToFileSync(src)** => `fsoDescr`
 
-> since: `v0.0.18`
+This method saves a document content into a file addressed by `src`.
 
-This method loads a document content from string containing text in XML format.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `src` | `string` | --- | path to a file |
+
+##### **loadFromString(xmlString, options)** => `boolean`
 
-##### **loadFromFile(src)**
+> WARNING: This method deprecated (*since `v0.0.18`*). Use `loadFromXMLString` instead.
 
-This method loads a document content from a file. A `src` provided a string that is a path to the file.
+<a name="TXEpgContentProvider+loadFromXMLString"></a>
+##### **loadFromXMLString(str)** => `boolean`
 
-##### **loadFromFileSync(src)**
+> since: `v0.0.18`
 
-This method loads a document content from a file. A `src` provided a string that is a path to the file.
+This method loads a document content from a string given by `str`.
 
-##### **saveToXMLString()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `str` | `string` | --- | some content |
 
-This method saves a document content to a string.
+<a name="TXEpgContentProvider+loadFromFileSync"></a>
+##### **loadFromFileSync(src)** => `fsoDescr`
 
-##### **saveToFile(src)**
+This method loads a document content from a file addressed by `src`.
 
-This method saves a document content to a file. A `src` provided a string that is a path to the file.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `src` | `string` | --- | path to a file |
 
-##### **saveToFileSync(src)**
+#### class methods (*async*)
 
-This method saves a document content to a file. A `src` provided a string that is a path to the file.
+<a name="TXEpgContentProvider+saveToFile"></a>
+##### **saveToFile(src)** => `Promise<fsoDescr, Error>`
 
-##### **asXML(options)**
+This method saves a document content into a file addressed by `src`.
 
-This method saves a document content to a string.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `src` | `string` | --- | path to a file |
 
-> Note: will deprecate. Use `saveToXMLString` instead.
+<a name="TXEpgContentProvider+loadFromFile"></a>
+##### **loadFromFile(src)** => `Promise<fsoDescr, Error>`
+
+This method loads a document content from a file addressed by `src`.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `src` | `string` | --- | path to a file |
 
 #### class methods (*special*)
 

package/doc/xepgdoc-spec-draft.dtd

@@ -0,0 +1,65 @@
+<!-- DTD for TV-listings
+     ======================
+     * [rev.0.2.002-20241016]
+     * [schema 0.2]         -->
+
+<!ELEMENT epgdoc (tvp:info, tvp:list)>
+<!ATTLIST epgdoc xmlns:tvp CDATA #REQUIRED >
+
+<!ELEMENT tvp:info (tvp:provider,
+                    (tvp:channel?|(tvp:chnid, tvp:chngid?, tvp:chname)),
+                    tvp:srcurl?,
+                    tvp:time?, tvp:expire?, tvp:timezone, tvp:dtstype)>
+
+<!ELEMENT tvp:provider (name, version?, tvp:schema, tvp:doctype)>
+
+<!ELEMENT name (#PCDATA)>
+<!ATTLIST name lang CDATA #IMPLIED >
+
+<!ELEMENT version (#PCDATA)>
+
+<!ELEMENT tvp:schema (#PCDATA)>
+
+<!ELEMENT tvp:doctype (#PCDATA)>
+
+<!-- NOTE: tag <tvp:channel> reserved for schema 0.3+ -->
+<!ELEMENT tvp:channel (tvp:chnid, tvp:chngid?, tvp:chname*)>
+
+<!ELEMENT tvp:chnid (#PCDATA)>
+
+<!ELEMENT tvp:chngid (#PCDATA)>
+
+<!ELEMENT tvp:chname (#PCDATA)>
+<!ATTLIST tvp:chname lang CDATA #IMPLIED >
+
+<!ELEMENT tvp:srcurl (#PCDATA)>
+
+<!ELEMENT tvp:time (#PCDATA)>
+
+<!ELEMENT tvp:expire (#PCDATA)>
+
+<!ELEMENT tvp:timezone (#PCDATA)>
+
+<!ELEMENT tvp:dtstype (value, name)>
+
+<!ELEMENT value (#PCDATA)>
+
+<!ELEMENT tvp:list ((tvp:item|tvp:schedule)*)>
+
+<!ELEMENT tvp:item (tvp:time, tvp:title+, tvp:pcmark?, tvp:cat*, tvp:desc*)>
+
+<!ELEMENT tvp:title (#PCDATA)>
+<!ATTLIST tvp:chname lang CDATA #IMPLIED >
+
+<!ELEMENT tvp:pcmark (#PCDATA)>
+
+<!ELEMENT tvp:cat (#PCDATA)>
+<!ATTLIST tvp:cat lang CDATA #IMPLIED >
+
+<!ELEMENT tvp:desc (#PCDATA)>
+<!ATTLIST tvp:desc lang CDATA #IMPLIED >
+
+<!-- NOTE: tag <tvp:channel> reserved for schema 0.3+ -->
+<!ELEMENT tvp:schedule (tvp:title+, tvp:pcmark?, tvp:cat*, tvp:desc*)>
+<!ATTLIST tvp:schedule start CDATA #REQUIRED
+                       stop CDATA #IMPLIED >

package/index.js

@@ -1,4 +1,4 @@
-// [v0.0.008-20230326]
+// [v0.0.009-20250225]
 
 // === module init block ===
 
@@ -15,9 +15,12 @@ const xObj = require('@ygracs/xobj-lib-js');
 /**/// v1 branch
 exports.TXEpgContentProvider = xepg_doc.TXEpgContentProvider;
 exports.TXEpgSchedulesList = xepg_doc.TXEpgSchedulesList;
-exports.TXepgDTSProvider = xepg_doc.TXepgDTSProvider;
+exports.TXEpgDTSProvider = xepg_doc.TXEpgDTSProvider;
 exports.TXEpgProviderContainer = xepg_doc.TXEpgProviderContainer;
 exports.TXEpgHeaderContainer = xepg_doc.TXEpgHeaderContainer;
 
 // re-export stuff from `@ygracs/xobj-lib-js` module
 exports.TXmlContentParseOptions = xObj.TXmlContentParseOptions;
+
+/**/// will deprecate
+exports.TXepgDTSProvider = xepg_doc.TXepgDTSProvider;