@ygracs/xepg-lib-js 0.0.15

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,39 @@
+|***rev.*:**|0.0.5|
+|:---|---:|
+|***date***:|2022-12-06|
+
+## Introduction
+
+This module provide a base functionality for handling an EPG-sources based on XEPG-format.
+
+> For more information about a XEPG-format see `xepgdoc-spec.md`in the project `doc` directory.
+
+## Use cases
+
+This module was make for use as a library in a development of a Web-apps based on [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)) as main target.
+
+## Description
+
+This module contains the following components:
+
+### 1. a set of XEPG-document constants and components
+
+- constants:
+
+- classes:
+
+	+ `TXEpgSchedulesList`;
+	+ `TXepgDTSProvider`;
+	+ `TXEpgProviderContainer`;
+	+ `TXEpgHeaderContainer`;
+	+ `TXEpgContentContainer`.
+
+For more read the `xepgdoc-lib.md` in the project `doc` directory.
+
+### 2. a set of other constants and components
+
+- constants:
+
+- classes:
+
+	+ `TXmlContentParseOptions`;

package/doc/xepgdoc-example.xepg

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<epgdoc xmlns:tvp="urn:e-doc:epg-doc:xepg">
+  <tvp:info>
+    <tvp:provider>
+      <name>EPG_Provider_Name</name>
+      <version>0.0.1</version>
+      <tvp:schema>0.2</tvp:schema>
+      <tvp:doctype>xepg</tvp:doctype>
+    </tvp:provider>
+    <tvp:chnid>Channel_ID</tvp:chnid>
+    <tvp:chngid>Group_ID</tvp:chngid>
+    <tvp:chname>Channel_Name</tvp:chname>
+    <tvp:srcurl>http://example.com/channel-page.html</tvp:srcurl>
+    <tvp:time>2022.03.11 10:32:31</tvp:time>
+    <tvp:expire>2022.03.14 23:00:00</tvp:expire>
+    <tvp:timezone>+0100</tvp:timezone>
+    <tvp:dtstype>
+      <value>0</value>
+      <name>default</name>
+    </tvp:dtstype>
+  </tvp:info>
+  <tvp:list>
+    <tvp:item>
+      <tvp:time>2022.03.11 03:00:00</tvp:time>
+      <tvp:title>Schedule_title</tvp:title>
+      <tvp:pcmark>0</tvp:pcmark>
+      <tvp:cat>Films, Comedy</tvp:cat>
+      <tvp:desc>Some_words_about_schedule</tvp:desc>
+    </tvp:item>
+  </tvp:list>
+</epgdoc>

package/doc/xepgdoc-lib.md

@@ -0,0 +1,286 @@
+|***rev.*:**|0.0.13|
+|:---|---:|
+|***date***:|2022-12-06|
+
+## Introduction
+
+This paper describes a constants and an object classes provided by `xepgdoc-lib.js` module.
+
+## Module constants
+
+## Module classes
+
+### **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:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|---|---|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|
+
+#### class methods
+
+##### **hasNoSchedules()**
+
+This method returns `true` if a document contains no schedules.
+
+##### **hasSchedules()**
+
+This method returns `true` if a document contains at least one schedule.
+
+##### **chkScheduleIndex(value)**
+
+This method checks if a given `value` represents a valid schedule index and if so returns `true`.
+
+##### **getScheduleInfo(index)**
+
+This method returns an object that contains a schedule information.
+
+##### **getAllSchedulesInfo()**
+
+This method returns an array that contains an information for all available schedules.
+
+#### class methods (*special*)
+
+##### **asJSON()**
+
+### **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:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`object`|---|---|a host object|
+|`options`|---|---|an option 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
+
+The table below describes a properties of a `TXEpgProviderContainer` class:
+
+|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|
+
+#### class methods
+
+##### **setName(value)**
+
+This method sets a name of a provider to a given `value`.
+
+##### **getInfo()**
+
+This method returns an `object` that contains information about content provider.
+
+##### **setInfo(obj)**
+
+This method loads information about content provider.
+
+#### class methods (*special*)
+
+##### **init()**
+
+### **TXEpgDTSProvider**
+
+#### 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`|---|---|an option 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
+
+The table below describes a properties of a `TXEpgDTSProvider` class:
+
+|property name|property type|read only|description|
+|:---|---|---|:---|
+|`dtstype`|`index`|no|defines a "dtstype"-value|
+|`curDocTZ`|`number`|no|defines a current TimeZone|
+
+### **TXEpgHeaderContainer**
+
+#### 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`|---|---|an option 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
+
+The table below describes a properties of a `TXEpgHeaderContainer` class:
+
+|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`|
+
+#### class methods
+
+##### **getDocumentDT()**
+
+This method returns a time value of a document creation.
+
+##### **setDocumentDT()**
+
+This method sets a time value of a document creation.
+
+##### **getDocumentEDT()**
+
+This method returns a time value from which a document is expired.
+
+##### **setDocumentEDT(value)**
+
+This method sets a time value at which a document will be expired.
+
+##### **getChannelInfo()**
+
+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|
+|`chname`|`string`|a name of the channel|
+|`chngid`|`ID_STRING`|a channel group|
+|`srcurl`|`string`|a link to source|
+
+##### **setChannelInfo(obj)**
+
+This method fills a channel information with a given data.
+
+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.
+
+If an array is given it contains the following fields:
+
+`[ <chnid>, <chname>, <chngid>, <srcurl> ]`
+
+If an object is given it contains the following fields:
+
+|field name|field type|description|
+|:---|---|:---|
+|`chnid`|`ID_STRING`|a channel ID|
+|`chname`|`string`|a name of the channel|
+|`chngid`|`ID_STRING`|a channel group|
+|`srcurl`|`string`|a link to source|
+
+##### **getProviderInfo()**
+
+This method returns an object which contains an information about document provider.
+
+##### **setProviderInfo(obj)**
+
+### **TXEpgContentProvider**
+
+#### class constructor
+
+The class constructor creates a new instance of the class. It receives arguments listed below:
+
+|name|type|default value|description|
+|:---|---|---:|:---|
+|`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`)|
+|`autoBindRoot`|`boolean`|`false`|<*reserved*>|
+
+#### class properties
+
+The table below describes a properties of a `TXEpgContentProvider` class:
+
+|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`|
+
+#### class methods
+
+##### **loadFromString(xmlString, options)**
+
+This method loads a document content from string containing text in XML format.
+
+##### **loadFromFile(src)**
+
+This method loads a document content from a file. A `src` provided a string that is a path to the file.
+
+##### **loadFromFileSync(src)**
+
+This method loads a document content from a file. A `src` provided a string that is a path to the file.
+
+##### **saveToXMLString()**
+
+This method saves a document content to a string.
+
+##### **saveToFile(src)**
+
+This method saves a document content to a file. A `src` provided a string that is a path to the file.
+
+##### **saveToFileSync(src)**
+
+This method saves a document content to a file. A `src` provided a string that is a path to the file.
+
+##### **asXML(options)**
+
+This method saves a document content to a string.
+
+> Note: will deprecate.
+
+#### class methods (*special*)
+
+##### **init()**
+
+##### **asJSON()**

package/doc/xepgdoc-spec.md

@@ -0,0 +1,124 @@
+|***rev.*:**|0.0.5|
+|:---|---:|
+|***date***:|2022-12-01|
+
+## Introduction
+
+This paper describes the purpose and use of XEPG-document and also the structure of it.
+
+> Note: the following content which is described below applied to document that structure follow the rule of a document schema with "`v0.2`".
+
+## Content
+
+## XEPG-document structure
+
+### XEPG-document format
+
+The XEPG-document format is base on XML and stored in file with `xepg` or `xml` extension.
+
+> Note: You can see what it is look like in the file example (*see `xepgdoc-example.xepg`*) which include in the docs module directory.
+
+### Root element
+
+The root element of the document starts by XML-tag named `epgdoc`. It contains two parts: the header and the body elements.
+
+The root element sets XML namespace `tvp` for entire document.
+
+### Header element
+
+The header element starts by a tag named `tvp:info`. It consists of the following parts:
+
+- document provider information;
+- channel information;
+- document time attributes.
+
+#### Provider info element
+
+The provider info element starts by a tag named `tvp:provider`. Its elements contains information about software agent which generated document and also defines a document type and document schema.
+
+##### **provider name**
+
+The provider name attribute represented by a tag named `name`.
+
+##### **provider version**
+
+The provider version attribute represented by a tag named `version`.
+
+##### **document schema attribute**
+
+The document schema attribute represented by a tag named `tvp:schema`.
+
+##### **document type attribute**
+
+The document type attribute represented by a tag named `tvp:doctype`.
+
+#### Channel information fields
+
+##### **channel ID**
+
+The channel ID field represented by a tag named `tvp:chnid`.
+
+##### **channel group ID**
+
+The channel group ID field represented by a tag named `tvp:chngid`.
+
+##### **channel name**
+
+The channel name field represented by a tag named `tvp:chname`.
+
+##### **channel source URL**
+
+The channel source URL field represented by a tag named `tvp:srcurl`.
+
+#### Document time attributes
+
+##### **document creation time**
+
+The document creation time attribute represented by a tag named `tvp:time`.
+
+##### **document expiration time**
+
+The document expiration time attribute represented by a tag named `tvp:expire`.
+
+##### **timezone attribute**
+
+The document timezone attribute represented by a tag named `tvp:timezone`.
+
+##### **DateTime system type element**
+
+The DateTime system type (*dtstype*) element starts by tag named `tvp:dtstype` and consists of the two elements:
+
+- `value` - the first element defines an index of dtstype which is used for date and time representation along with a document;
+- `name` - the second element is a string which represent a name of dtstype given by `value` element.
+
+### Body element
+
+The body element starts by a tag named `tvp:list` and holds all the schedule elements associated with the channel.
+
+### Schedule element
+
+The schedule element starts by a tag named `tvp:item`.
+
+##### **schedule time attribute**
+
+The schedule time attribute represented by a tag named `tvp:time`. Its value is a string that represents date and time of the schedule. The format of a such string is based on the rules defined by the used dtstype value.
+
+##### **schedule title**
+
+The schedule title attribute represented by a tag named `tvp:title`.
+
+##### **schedule subtitle**
+
+##### **schedule categories**
+
+The schedule categories attribute represented by a tag named `tvp:cat`.
+
+##### **schedule description**
+
+The schedule description attribute represented by a tag named `tvp:desc`.
+
+##### **schedule rating**
+
+The schedule rating attribute represented by a tag named `tvp:pcmark`.
+
+##### **schedule star-rating**

package/index.js

@@ -0,0 +1,23 @@
+// [v0.0.007-20220908]
+
+// === module init block ===
+
+const xepg_doc = require('./lib/xepgdoc-lib.js');
+
+const xObj = require('@ygracs/xobj-lib-js');
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+// === 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;
+
+// re-export stuff from `@ygracs/xobj-lib-js` module
+exports.TXmlContentParseOptions = xObj.TXmlContentParseOptions;

package/lib/dts-helper.js

@@ -0,0 +1,141 @@
+// [v0.1.040-20221126]
+
+// === module init block ===
+
+const {
+  valueToIndex, readAsString, readAsNumberEx,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  convDTValueToISO8601,
+  convDTValueToXMLTV, convXMLTVToDTValue,
+  convDTValueToDateString,
+} = require('@ygracs/dtf-lib-js');
+
+const def_dts_param = [
+  'default', 'iso8601', 'xmltv', 'timestamp', 'utc',
+];
+
+// === module extra block (helper functions) ===
+
+// === module main block (function definitions) ===
+
+function chkDTSysID(value){
+  const _value = valueToIndex(value);
+  return _value !== -1 && def_dts_param[_value] ? true : false;
+};
+
+function getDTSysName(value){
+  let result = 'undefined';
+  if (chkDTSysID(value)) {
+    result = def_dts_param[Number(value)];
+  };
+  return result;
+};
+
+function convStringToDTValue(value, dts_id, tz){
+  let result = 0;
+  let dtstype = valueToIndex(dts_id);
+  let dt_str = typeof value === 'string' ? value : '';
+  if (chkDTSysID(dtstype)) {
+    switch (getDTSysName(dtstype)) {
+      case 'default':
+        // TODO: check TZ
+        //console.log('convStringToDTValue => dtstype:[default]');
+        result = (new Date(dt_str)).getTime();
+        //console.log('convStringToDTValue => value:['+value+']');
+        //console.log('convStringToDTValue => result:['+result+']');
+        break;
+      case 'iso8601':
+        // TODO: check TZ
+        //console.log('convStringToDTValue => dtstype:[iso8601]');
+        result = (new Date(dt_str)).getTime();
+        //console.log('convStringToDTValue => value:['+value+']');
+        //console.log('convStringToDTValue => result:['+result+']');
+        break;
+      case 'xmltv':
+        // TODO: check TZ
+        //console.log('convStringToDTValue => dtstype:[xmltv]');
+        result = (new Date(convXMLTVToDTValue(dt_str))).getTime();
+        //console.log('convStringToDTValue => value:['+value+']');
+        //console.log('convStringToDTValue => result:['+result+']');
+        break;
+      case 'timestamp':
+        // TODO: check TZ
+        //console.log('convStringToDTValue => dtstype:[timestamp]');
+        result = Number(dt_str);
+        //console.log('convStringToDTValue => value:['+value+']');
+        //console.log('convStringToDTValue => result:['+result+']');
+        break;
+      case 'utc':
+        // TODO: check TZ
+        //console.log('convStringToDTValue => dtstype:[utc]');
+        result = (new Date(Date.UTC(dt_str))).getTime();
+        //console.log('convStringToDTValue => value:['+value+']');
+        //console.log('convStringToDTValue => result:['+result+']');
+        break;
+      default:
+        break;
+    };
+    if (Number.isNaN(result)) result = 0;
+  };
+  return result;
+};
+
+function convDTValueToString(value, dts_id, tz){
+  let result = '';
+  let dtstype = valueToIndex(dts_id);
+  let dt_val = (new Date(readAsNumberEx(value, 0))).getTime();
+  if (Number.isNaN(dt_val)) dt_val = new Date(0);
+  if (!chkDTSysID(dtstype)) dtstype = 0;
+  switch (getDTSysName(dtstype)) {
+    case 'default':
+      // TODO: check TZ
+      //console.log('convDTValueToString => dtstype:[default]');
+      result = convDTValueToDateString(dt_val, {
+        src_in_utc: false,
+      });
+      //console.log('convDTValueToString => value:['+value+']');
+      //console.log('convDTValueToString => result:['+result+']');
+      break;
+    case 'iso8601':
+      // TODO: check TZ
+      //console.log('convDTValueToString => dtstype:[iso8601]');
+      result = convDTValueToISO8601(dt_val, {
+        use_bs_format: false,
+        src_in_utc: false,
+      });
+      //console.log('convDTValueToString => value:['+value+']');
+      //console.log('convDTValueToString => result:['+result+']');
+      break;
+    case 'xmltv':
+      // TODO: check TZ
+      //console.log('convDTValueToString => dtstype:[xmltv]');
+      result = convDTValueToXMLTV(dt_val, {
+        src_in_utc: false,
+      });
+      //console.log('convDTValueToString => value:['+value+']');
+      //console.log('convDTValueToString => result:['+result+']');
+      break;
+    case 'timestamp':
+      // TODO: check TZ
+      //console.log('convDTValueToString => dtstype:[timestamp]');
+      result = dt_val.toString();
+      //console.log('convDTValueToString => value:['+value+']');
+      //console.log('convDTValueToString => result:['+result+']');
+      break;
+    default:
+      break;
+  };
+  return result;
+};
+
+// === module main block (class definitions) ===
+
+// === module exports block ===
+
+exports.chkDTSysID = chkDTSysID;
+exports.checkDTSysID = chkDTSysID;
+exports.getDTSysName = getDTSysName;
+exports.convStringToDTValue = convStringToDTValue;
+exports.convDTValueToString = convDTValueToString;