extwee 2.2.1 → 2.2.3

package/src/Twine2ArchiveHTML/compile.js

@@ -2,8 +2,16 @@ import { Story } from '../Story.js';
 
 /**
  * Write array of Story objects into Twine 2 Archive HTML.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md Twine 2 Archive Specification}
+ * @function compile
  * @param {Array} stories - Array of Story objects.
  * @returns {string} Twine 2 Archive HTML.
+ * @example
+ * const story1 = new Story();
+ * const story2 = new Story();
+ * const stories = [story1, story2];
+ * console.log(compile(stories));
+ * // => '<tw-storydata name="Untitled" startnode="1" creator="Twine" creator-version="2.3.9" ifid="A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6" zoom="1" format="Harlowe" format-version="3.1.0" options="" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="Untitled Passage" tags="" position="0,0" size="100,100"></tw-passagedata></tw-storydata>\n\n<tw-storydata name="Untitled" startnode="1" creator="Twine" creator-version="2.3.9" ifid="A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6" zoom="1" format="Harlowe" format-version="3.1.0" options="" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="Untitled Passage" tags="" position="0,0" size="100,100"></tw-passagedata></tw-storydata>\n\n'
  */
 function compile (stories) {
   // Can only accept array.

package/src/Twine2ArchiveHTML/parse.js

@@ -2,9 +2,39 @@ import { parse as HtmlParser } from 'node-html-parser';
 import { parse as parseTwine2HTML } from '../Twine2HTML/parse.js';
 
 /**
- * Parse HTML for one or more Twine 2 HTML elements and return array of story objects.
+ * Parse Twine 2 Archive HTML and returns an array of story objects.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md Twine 2 Archive Specification}
+ * @function parse
  * @param {string} content - Content to parse for Twine 2 HTML elements.
+ * @throws {TypeError} - Content is not a string!
  * @returns {Array} Array of stories found in content.
+ * @example
+ * const content = '<tw-storydata name="Untitled" startnode="1" creator="Twine" creator-version="2.3.9" ifid="A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6" zoom="1" format="Harlowe" format-version="3.1.0" options="" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="Untitled Passage" tags="" position="0,0" size="100,100"></tw-passagedata></tw-storydata>';
+ * console.log(parse(content));
+ * // => [
+ * //     Story {
+ * //      name: 'Untitled',
+ * //      startnode: '1',
+ * //      creator: 'Twine',
+ * //      creatorVersion: '2.3.9',
+ * //      ifid: 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6',
+ * //      zoom: '1',
+ * //      format: 'Harlowe',
+ * //      formatVersion: '3.1.0',
+ * //      options: '',
+ * //      hidden: '',
+ * //      passages: [
+ * //        Passage {
+ * //          pid: '1',
+ * //          name: 'Untitled Passage',
+ * //          tags: '',
+ * //          position: '0,0',
+ * //          size: '100,100',
+ * //          text: ''
+ * //        }
+ * //      ]
+ * //    }
+ * //   ]
  */
 function parse (content) {
   // Can only parse string values.
@@ -32,8 +62,8 @@ function parse (content) {
 
   // Did we find any elements?
   if (storyDataElements.length === 0) {
-    // If there is not a single `<tw-storydata>` element, this is not a Twine 2 story!
-    throw new Error('Not Twine 2 HTML content!');
+    // Produce a warning if no Twine 2 HTML content is found.
+    console.warn('Warning: No Twine 2 HTML content found!');
   }
 
   // Iterate through all `<tw-storydata>` elements.

package/src/Twine2HTML/compile.js

@@ -3,20 +3,48 @@ import StoryFormat from '../StoryFormat.js';
 
 /**
  * Write a combination of Story + StoryFormat into Twine 2 HTML file.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md Twine 2 HTML Output Specification}
+ * @function compile
  * @param {Story} story - Story object to write.
  * @param {StoryFormat} storyFormat - StoryFormat to write.
- * @returns {string} Twine 2 HTML.
+ * @returns {string} Twine 2 HTML based on StoryFormat and Story.
+ * @throws {Error} If story is not instance of Story.
+ * @throws {Error} If storyFormat is not instance of StoryFormat.
+ * @throws {Error} If storyFormat.source is empty string.
  */
 function compile (story, storyFormat) {
+  // Check if story is instanceof Story.
   if (!(story instanceof Story)) {
     throw new Error('Error: story must be a Story object!');
   }
 
+  // Check if storyFormat is instanceof StoryFormat.
   if (!(storyFormat instanceof StoryFormat)) {
     throw new Error('storyFormat must be a StoryFormat object!');
   }
 
-  let outputContents = '';
+  // Check if storyFormat.source is empty string.
+  if (storyFormat.source === '') {
+    throw new Error('StoryFormat source empty string!');
+  }
+
+  /**
+   * There are two required attributes:
+   * - story.IFID: UUIDv4
+   * - story.name: string (non-empty)
+   */
+
+  // Check if story.IFID is UUIDv4 formatted.
+  if (story.IFID.match(/^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[89ABab][0-9A-F]{3}-[0-9A-F]{12}$/) === null) {
+    throw new Error('Story IFID is invalid!');
+  }
+
+  // Check if story.name is empty string.
+  if (story.name === '') {
+    throw new Error('Story name empty string!');
+  }
+
+  // Translate story to Twine 2 HTML.
   const storyData = story.toTwine2HTML();
 
   // Replace the story name in the source file.
@@ -25,11 +53,8 @@ function compile (story, storyFormat) {
   // Replace the story data.
   storyFormat.source = storyFormat.source.replaceAll(/{{STORY_DATA}}/gm, storyData);
 
-  // Combine everything together.
-  outputContents += storyFormat.source;
-
   // Return content.
-  return outputContents;
+  return storyFormat.source;
 }
 
 export { compile };

package/src/Twine2HTML/parse.js

@@ -8,8 +8,18 @@ import { decode } from 'html-entities';
  *
  * See: Twine 2 HTML Output Specification
  * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md)
+ *
+ * Produces warnings for:
+ * - Missing name attribute on `<tw-storydata>` element.
+ * - Missing IFID attribute on `<tw-storydata>` element.
+ * - Malformed IFID attribute on `<tw-storydata>` element.
+ * @function parse
  * @param {string} content - Twine 2 HTML content to parse.
- * @returns {Story} Story
+ * @returns {Story} Story object based on Twine 2 HTML content.
+ * @throws {TypeError} Content is not a string.
+ * @throws {Error} Not Twine 2 HTML content!
+ * @throws {Error} Cannot parse passage data without name!
+ * @throws {Error} Passages are required to have PID!
  */
 function parse (content) {
   // Create new story.
@@ -17,7 +27,7 @@ function parse (content) {
 
   // Can only parse string values.
   if (typeof content !== 'string') {
-    throw new TypeError('Content is not a string!');
+    throw new TypeError('TypeError: Content is not a string!');
   }
 
   // Set default start node.
@@ -41,7 +51,7 @@ function parse (content) {
   // Did we find any elements?
   if (storyDataElements.length === 0) {
     // If there is not a single `<tw-storydata>` element, this is not a Twine 2 story!
-    throw new Error('Not Twine 2 HTML content!');
+    throw new TypeError('TypeError: Not Twine 2 HTML content!');
   }
 
   // We only parse the first element found.
@@ -56,7 +66,7 @@ function parse (content) {
     story.name = storyData.attributes.name;
   } else {
     // Name is a required field. Warn user.
-    console.warn('Twine 2 HTML must have a name!');
+    console.warn('Warning: The name attribute is missing from tw-storydata!');
   }
 
   /**
@@ -70,7 +80,13 @@ function parse (content) {
     story.IFID = storyData.attributes.ifid;
   } else {
     // Name is a required filed. Warn user.
-    console.warn('Twine 2 HTML must have an IFID!');
+    console.warn('Warning: The ifid attribute is missing from tw-storydata!');
+  }
+
+  // Check if the IFID has valid formatting.
+  if (story.IFID.match(/^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/) === null) {
+    // IFID is not valid.
+    console.warn('Warning: The IFID is not in valid UUIDv4 formatting on tw-storydata!');
   }
 
   /**
@@ -125,9 +141,6 @@ function parse (content) {
   if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'startnode')) {
     // Take string value and convert to Int
     startNode = Number.parseInt(storyData.attributes.startnode, 10);
-  } else {
-    // Throw error without start node.
-    throw new Error('Missing startnode in <tw-storydata>!');
   }
 
   // Pull out the `<tw-passagedata>` element.
@@ -173,15 +186,21 @@ function parse (content) {
      *   https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md#passages
      */
     // Create a default value
-    let name = null;
+    let name = 'Untitled Passage';
     // Does name exist?
     if (Object.prototype.hasOwnProperty.call(attr, 'name')) {
       // Escape the name
-      name = escapeMetacharacters(attr.name);
+      name = attr.name;
     } else {
-      throw new Error('Cannot parse passage data without name!');
+      console.warn('Warning: name attribute is missing! Default passage name will be used.');
     }
 
+    /**
+     * tags: (string) Optional.
+     *  A space-separated list of tags for the passage.
+     *
+     *  https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md#passages
+     */
     // Create empty tag array.
     let tags = [];
     // Does the tags attribute exist?
@@ -190,7 +209,7 @@ function parse (content) {
       // (Attributes can, themselves, be empty strings.)
       if (attr.tags.length > 0 && attr.tags !== '""') {
         // Escape the tags
-        tags = escapeMetacharacters(attr.tags);
+        tags = attr.tags;
         // Split by spaces into an array
         tags = tags.split(' ');
       }
@@ -199,6 +218,12 @@ function parse (content) {
       tags = tags.filter(tag => tag !== '');
     }
 
+    /**
+     * metadata: (object) Optional.
+     *  An object containing additional metadata about the passage.
+     *
+     * Twine 2 HTML does not support metadata, but other formats do.
+     */
     // Create metadata for passage.
     const metadata = {};
 
@@ -222,14 +247,14 @@ function parse (content) {
      *   https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md#passages
      */
     // Create a default PID
-    let pid = -1;
+    let pid = 1;
     // Does pid exist?
     if (Object.prototype.hasOwnProperty.call(attr, 'pid')) {
       // Parse string into int
       // Update PID
       pid = Number.parseInt(attr.pid, 10);
     } else {
-      console.warn('Passages are required to have PID. Will not add!');
+      console.warn('Warning: pid attribute is missing! Default PID will be used.');
     }
 
     // Check the current PID against startNode number.
@@ -239,24 +264,15 @@ function parse (content) {
       story.start = name;
     }
 
-    // If passage is missing name and PID (required attributes),
-    //  they are not added.
-    if (name !== null && pid !== -1) {
-      // Add a new Passage into an array
-      story.addPassage(
-        new Passage(
-          decode(name),
-          decode(text),
-          tags.map(tag => decode(tag)),
-          metadata
-        )
-      );
-    }
-  }
-
-  // There was an invalid startNode.
-  if (story.start === '') {
-    throw new Error('startNode does not exist within passages!');
+    // Add a new Passage into an array
+    story.addPassage(
+      new Passage(
+        decode(name),
+        decode(text),
+        tags.map(tag => decode(tag)),
+        metadata
+      )
+    );
   }
 
   // Look for the style element
@@ -325,25 +341,4 @@ function parse (content) {
   return story;
 }
 
-/**
- * Try to escape Twine 2 meta-characters.
- * @param {string} result - Text to parse.
- * @returns {string} Escaped characters.
- */
-function escapeMetacharacters (result) {
-  // Replace any single backslash, \, with two of them, \\.
-  result = result.replace(/\\/g, '\\');
-  // Double-escape escaped {
-  result = result.replace(/\\\{/g, '\\\\{');
-  // Double-escape escaped }
-  result = result.replace(/\\\}/g, '\\\\}');
-  // Double-escape escaped [
-  result = result.replace(/\\\[/g, '\\\\[');
-  // Double-escape escaped ]
-  result = result.replace(/\\\]/g, '\\\\]');
-
-  return result;
-}
-
-export { parse, escapeMetacharacters };
-export default parse;
+export { parse };

package/test/IFID/IFID.Generate.test.js

@@ -0,0 +1,10 @@
+import { generate } from '../../src/IFID/generate.js';
+
+describe('src/IFID/generate.js', () => {
+  describe('generate()', () => {
+    it('should generate a valid IFID', () => {
+      const ifid = generate();
+      expect(ifid).toMatch(/^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/);
+    });
+  });
+});

package/test/JSON/JSON.Parse.test.js

@@ -16,7 +16,7 @@ describe('JSON', () => {
       const s = parseJSON(r.toJSON());
 
       // Check all properties.
-      expect(s.name).toBe('');
+      expect(s.name).toBe('Untitled Story');
       expect(Object.keys(s.tagColors).length).toBe(0);
       expect(s.IFID).toBe('');
       expect(s.start).toBe('');
@@ -24,7 +24,7 @@ describe('JSON', () => {
       expect(s.format).toBe('');
       expect(s.creator).toBe(creatorName);
       expect(s.creatorVersion).toBe(creatorVersion);
-      expect(s.zoom).toBe(0);
+      expect(s.zoom).toBe(1);
       expect(Object.keys(s.metadata).length).toBe(0);
     });
 
@@ -52,7 +52,7 @@ describe('JSON', () => {
       it('Should parse everything but name', function () {
         const s = '{"tagColors":{"r":"red"},"ifid":"dd","start":"Start","formatVersion":"1.0","metadata":{"some":"thing"},"format":"Snowman","creator":"extwee","creatorVersion":"2.2.0","zoom":1,"passages":[{"name":"Start","tags":["tag1"],"metadata":{},"text":"Word"}]}';
         const r = parseJSON(s);
-        expect(r.name).toBe('');
+        expect(r.name).toBe('Untitled Story');
         expect(Object.keys(r.tagColors).length).toBe(1);
         expect(r.IFID).toBe('DD');
         expect(r.start).toBe('Start');
@@ -189,7 +189,7 @@ describe('JSON', () => {
         expect(r.format).toBe('Snowman');
         expect(r.creator).toBe(creatorName);
         expect(r.creatorVersion).toBe('2.2.0');
-        expect(r.zoom).toBe(0);
+        expect(r.zoom).toBe(1);
         expect(r.size()).toBe(1);
       });
 

package/test/{Passage.test.js → Objects/Passage.test.js}

@@ -1,4 +1,4 @@
-import Passage from '../src/Passage.js';
+import Passage from '../../src/Passage.js';
 import { parse as HTMLParser } from 'node-html-parser';
 
 describe('Passage', () => {
@@ -218,8 +218,8 @@ describe('Passage', () => {
     });
 
     it('Should escape meta-characters safely in Twee header', function () {
-      const p = new Passage('Where do tags begin? [well',  '', ['hmm']);
-      expect(p.toTwee().includes('Where do tags begin? \[well [hmm]')).toBe(true);
+      const p = new Passage('Where do tags begin? [well', '', ['hmm']);
+      expect(p.toTwee().includes('Where do tags begin? [well [hmm]')).toBe(true);
     });
 
     it('Should produce valid HTML attributes', function () {
@@ -232,7 +232,7 @@ describe('Passage', () => {
       expect(d.querySelector('tw-passagedata').getAttribute('tags')).toBe('&tag "bad"');
       expect(d.querySelector('tw-passagedata').getAttribute('position')).toBe('100,100');
       // Use Twine 2 result.
-      const s = `<tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="100,100" size="100,100"></tw-passagedata>`;
+      const s = '<tw-passagedata pid="1" name="&quot;Test&quot;" tags="&amp;tag &quot;bad&quot;" position="100,100" size="100,100"></tw-passagedata>';
       // Parse HTML.
       const t = new HTMLParser(s);
       // Test Twine 2 attributes.