extwee 1.5.3 → 2.0.0

package/package.json

@@ -1,39 +1,60 @@
-{
-  "name": "extwee",
-  "version": "1.5.3",
-  "description": "A Twee 3 compiler written in JS.",
-  "author": "Dan Cox",
-  "main": "index.js",
-  "scripts": {
-    "start": "node main.js",
-    "test": "nyc mocha test/test.js"
-  },
-  "keywords": [
-    "twine",
-    "twee",
-    "parser",
-    "compiler"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "@babel/core": "^7.6.0",
-    "@babel/preset-env": "^7.6.0",
-    "chokidar": "^3.0.2",
-    "clean-css": "^4.2.1",
-    "mocha": "^6.2.0",
-    "node-html-parser": "^1.1.16",
-    "shelljs": "^0.8.3",
-    "uglify-js": "^3.6.0",
-    "yargs": "^13.3.0"
-  },
-  "devDependencies": {
-    "nyc": "^14.1.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/videlais/extwee"
-  },
-  "bugs": {
-    "url": "https://github.com/videlais/extwee/issues"
-  }
-}
+{
+  "name": "extwee",
+  "version": "2.0.0",
+  "description": "A Twee 3 compiler written in JS.",
+  "author": "Dan Cox",
+  "main": "index.js",
+  "bin": {
+    "extwee": "bin/extwee.js"
+  },
+  "scripts": {
+    "test": "jest --silent --runInBand --coverage --colors",
+    "test:watch": "jest --watch",
+    "lint": "eslint ./src/**/*.js --fix",
+    "lint:test": "eslint ./test/*.test.js --fix",
+    "all": "npm run lint && npm run lint:test && npm run test"
+  },
+  "keywords": [
+    "twine",
+    "twee",
+    "parser",
+    "compiler"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^4.1.1",
+    "node-html-parser": "^1.2.16",
+    "uuid": "^8.3.2"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.12.10",
+    "@babel/core": "^7.12.10",
+    "@babel/eslint-parser": "^7.12.1",
+    "@babel/eslint-plugin": "^7.12.1",
+    "@babel/plugin-proposal-class-properties": "^7.12.1",
+    "@babel/plugin-transform-runtime": "^7.12.10",
+    "@babel/polyfill": "^7.12.1",
+    "@babel/preset-env": "^7.12.11",
+    "babel-loader": "^8.2.2",
+    "core-js": "^3.8.1",
+    "eslint": "^7.7.0",
+    "eslint-config-standard": "^14.1.0",
+    "eslint-plugin-import": "^2.20.1",
+    "eslint-plugin-jest": "^24.1.3",
+    "eslint-plugin-jsdoc": "^30.2.1",
+    "eslint-plugin-node": "^11.0.0",
+    "eslint-plugin-promise": "^4.2.1",
+    "eslint-plugin-standard": "^4.0.1",
+    "jest": "^27.3.1",
+    "semver": "^5.7.1",
+    "shelljs": "^0.8.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/videlais/extwee"
+  },
+  "bugs": {
+    "url": "https://github.com/videlais/extwee/issues"
+  },
+  "type": "module"
+}

package/src/FileReader.js

@@ -0,0 +1,33 @@
+import fs from 'fs';
+/**
+ * @class FileReader
+ * @module FileReader
+ */
+export default class FileReader {
+  /**
+   * Read a text file
+   *
+   * @static
+   * @public
+   * @function readFile
+   * @memberof FileReader
+   * @param {string} file - Path of file to read
+   * @returns {string} Content of file
+   */
+  static read (file) {
+    // Setup default value
+    let contents = '';
+
+    // Attempt to find the file
+    if (fs.existsSync(file)) {
+      // The file exists.
+      contents = fs.readFileSync(file, 'utf8');
+    } else {
+      // Throw error if file does not exist
+      throw new Error('Error: File not found!');
+    }
+
+    // Return default or updated values
+    return contents;
+  }
+}

package/src/HTMLParser.js

@@ -0,0 +1,343 @@
+/**
+ * @external HTML
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML|HTML}
+ */
+
+import { parse as HtmlParser } from 'node-html-parser';
+import Story from './Story.js';
+import Passage from './Passage.js';
+/**
+ * @class HTMLParser
+ * @module HTMLParser
+ */
+export default class HTMLParser {
+  /**
+   * Parse HTML text into a JS DOM-like object
+   *
+   * @public
+   * @static
+   * @function parse
+   * @param {string} content - Content to parse
+   * @returns {Story} story
+   */
+  static parse (content) {
+    let story = null;
+    let startNode = null;
+
+    // Send to node-html-parser
+    // Enable getting the content of 'script', 'style', and 'pre' elements
+    // Get back a DOM
+    const dom = new HtmlParser(
+      content,
+      {
+        lowerCaseTagName: false,
+        script: true,
+        style: true,
+        pre: true
+      });
+
+    // Pull out the tw-storydata element
+    const storyData = dom.querySelector('tw-storydata');
+
+    // Does the <tw-storydata> element exist?
+    if (storyData !== null) {
+      // Create a Story.
+      story = new Story();
+
+      /**
+       * name: (string) Required.
+       *   The name of the story.
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'name')) {
+        // Create StoryTitle passage based on name
+        story.addPassage(new Passage('StoryTitle', storyData.attributes.name));
+      } else {
+        // Name is a required filed. Warn user.
+        console.warn('Twine 2 HTML must have a name!');
+        // Set a default name
+        story.addPassage(new Passage('StoryTitle', 'Untitled'));
+      }
+
+      /**
+       * ifid: (string) Required.
+       *   An IFID is a sequence of between 8 and 63 characters,
+       *   each of which shall be a digit, a capital letter or a
+       *   hyphen that uniquely identify a story (see Treaty of Babel).
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'ifid')) {
+        // Update story IFID
+        story.IFID = storyData.attributes.ifid;
+      } else {
+        // Name is a required filed. Warn user.
+        console.warn('Twine 2 HTML must have an IFID!');
+      }
+
+      /**
+       * creator: (string) Optional.
+       *   The name of program used to create the file.
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'creator')) {
+        // Update story creator
+        story.creator = storyData.attributes.creator;
+      }
+
+      /**
+       * creator-version: (string) Optional.
+       *   The version of the program used to create the file.
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'creator-version')) {
+        // Update story creator version
+        story.creatorVersion = storyData.attributes['creator-version'];
+      }
+
+      /**
+       * format: (string) Optional.
+       *   The story format used to create the story.
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'format')) {
+        // Update story format
+        story.format = storyData.attributes.format;
+      }
+
+      /**
+       * format-version: (string) Optional.
+       *   The version of the story format used to create the story.
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'format-version')) {
+        // Update story format version
+        story.formatVersion = storyData.attributes['format-version'];
+      }
+
+      /**
+       * zoom: (string) Optional.
+       *   The decimal level of zoom (i.e. 1.0 is 100% and 1.2 would be 120% zoom level).
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'zoom')) {
+        // Update story zoom
+        story.zoom = Number(Number.parseFloat(storyData.attributes.zoom).toFixed(2));
+      }
+
+      /**
+       * startnode: (string) Optional.
+       *   The PID matching a <tw-passagedata> element whose content should be displayed first.
+       */
+      if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'startnode')) {
+        // Take string value and convert to Int
+        startNode = Number.parseInt(storyData.attributes.startnode, 10);
+      }
+    } else {
+      // If there is not a <tw-storydata> element, this is not a Twine 2 story!
+      throw new Error('Not a Twine 2-style file!');
+    }
+
+    // Pull out the tw-passagedata elements
+    const storyPassages = dom.querySelectorAll('tw-passagedata');
+
+    // Move through the passages
+    for (const passage in storyPassages) {
+      // Get the passage attributes
+      const attr = storyPassages[passage].attributes;
+      // Get the passage text
+      const text = storyPassages[passage].rawText;
+
+      // Set a default position.
+      let position = null;
+      // Does position exist?
+      if (Object.prototype.hasOwnProperty.call(attr, 'position')) {
+        // Update position.
+        position = attr.position;
+      }
+
+      // Set a default size.
+      let size = null;
+      // Does size exist?
+      if (Object.prototype.hasOwnProperty.call(attr, 'size')) {
+        // Update size.
+        size = attr.size;
+      }
+
+      /**
+       * name: (string) Required.
+       *   The name of the passage.
+       *
+       *   https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md#passages
+       */
+      // Create a default value
+      let name = null;
+      // Does name exist?
+      if (Object.prototype.hasOwnProperty.call(attr, 'name')) {
+        // Escape the name
+        name = HTMLParser.escapeMetacharacters(attr.name);
+      } else {
+        console.warn('Encountered passage without a name! Will not add.');
+      }
+
+      // Create empty tag array.
+      let tags = [];
+      // Does the tags attribute exist?
+      if (Object.prototype.hasOwnProperty.call(attr, 'tags')) {
+        // Escape any tags
+        // (Attributes can, themselves, be empty strings.)
+        if (attr.tags.length > 0 && attr.tags !== '""') {
+          // Escape the tags
+          tags = HTMLParser.escapeMetacharacters(attr.tags);
+          // Split by spaces into an array
+          tags = tags.split(' ');
+        }
+
+        // Remove any empty strings.
+        tags = tags.filter(tag => tag !== '');
+      }
+
+      // Create metadata for passage.
+      const metadata = {};
+
+      // Does position exist?
+      if (position !== null) {
+        // Add the property to metadata
+        metadata.position = position;
+      }
+
+      // Does size exist?
+      if (size !== null) {
+        // Add the property to metadata
+        metadata.size = size;
+      }
+
+      /**
+       * pid: (string) Required.
+       *   The Passage ID (PID).
+       *   (Note: This is subject to change during editing with Twine 2.)
+       *
+       *   https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md#passages
+       */
+      // Create a default PID
+      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!');
+      }
+
+      // 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(
+            name,
+            text,
+            tags,
+            metadata,
+            pid
+          )
+        );
+      }
+    }
+
+    // Look for the style element
+    const styleElement = dom.querySelector('#twine-user-stylesheet');
+
+    // Does the style element exist?
+    if (styleElement !== null) {
+      // Check if there is any content.
+      if (styleElement.rawText.length > 0) {
+        // Update stylesheet passage
+        story.addPassage(new Passage(
+          'UserStylesheet',
+          styleElement.rawText,
+          ['stylesheet'])
+        );
+      }
+    }
+
+    // Look for the script element
+    const scriptElement = dom.querySelector('#twine-user-script');
+
+    // Does the script element exist?
+    if (scriptElement !== null) {
+      // Check if there is any content.
+      if (scriptElement.rawText.length > 0) {
+        story.addPassage(new Passage(
+          'UserScript',
+          scriptElement.rawText,
+          ['script'])
+        );
+      }
+    }
+
+    // Was there a startNode?
+    if (startNode !== null) {
+      // Try to find starting passage by PID.
+      const startingPassage = story.getPassageByPID(startNode);
+      // Does the passage exist (yet)?
+      if (startingPassage !== null) {
+        // If so, update property to name of passage.
+        story.start = startingPassage.name;
+      } else {
+        throw new Error('Invalid startnode detected in <tw-storydata>!');
+      }
+    }
+
+    // Look for all <tw-tag> elements
+    const twTags = dom.querySelectorAll('tw-tag');
+
+    // Parse through the entries
+    twTags.forEach((tags) => {
+      // Parse each tag element
+      const attributes = tags.attributes;
+
+      // Create default value for name
+      let name = '';
+
+      // Create default value for color
+      let color = '';
+
+      // Check for name
+      if (Object.prototype.hasOwnProperty.call(attributes, 'name')) {
+        name = attributes.name;
+      }
+
+      // Check for color
+      if (Object.prototype.hasOwnProperty.call(attributes, 'color')) {
+        color = attributes.color;
+      }
+
+      // If both are not empty strings, use them.
+      if (name !== '' && color !== '') {
+        // Add name and color to the object
+        story.tagColors[name] = color;
+      }
+    });
+
+    // Return the parsed story
+    return story;
+  }
+
+  /**
+   * Try to escape meta-characters
+   *
+   * @public
+   * @static
+   * @function escapeMetacharacters
+   * @param {string} result - Text to parse
+   * @returns {string} Escaped characters
+   */
+  static 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;
+  }
+}

package/src/HTMLWriter.js

@@ -0,0 +1,196 @@
+/**
+ * @external Story
+ * @see Story.js
+ * @external StoryFormat
+ * @see StoryFormat.js
+ */
+
+import fs from 'fs';
+import Story from './Story.js';
+import StoryFormat from './StoryFormat.js';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * @class HTMLWriter
+ * @module HTMLWriter
+ */
+export default class HTMLWriter {
+  /**
+   * Write story to file using story format and adding any CSS and JS
+   *
+   * @public
+   * @static
+   * @function writeFile
+   * @param {string} file - File to write
+   * @param {Story} story - Story object to write
+   * @param {StoryFormat} storyFormat - StoryFormat to write
+   */
+  static write (file, story, storyFormat) {
+    if (!(story instanceof Story)) {
+      throw new Error('Error: story must be a Story object!');
+    }
+
+    if (!(storyFormat instanceof StoryFormat)) {
+      throw new Error('storyFormat must be a StoryFormat object!');
+    }
+
+    let outputContents = '';
+    let storyData = '';
+
+    // Look for StoryTitle
+    const storyTitle = story.getPassageByName('StoryTitle');
+
+    if (storyTitle != null) {
+      // Use StoryTitle for name
+      storyData += `<tw-storydata name="${storyTitle.text}"`;
+    } else {
+      throw new Error("'name' is required attribute. (Add StoryTitle to story.)");
+    }
+
+    // Does start exist?
+    if (story.start !== '') {
+      // Try to get starting passage
+      const startingPassage = story.getPassageByName(story.start);
+      // Does it exist currently?
+      if (startingPassage !== null) {
+        // Add the starting passage
+        storyData += ` startnode="${startingPassage.pid}"`;
+      } else {
+        // Throw error if no starting passage exists
+        throw new Error('Starting passage not found');
+      }
+    } else {
+      // Throw error if no starting passage exists
+      throw new Error('No starting passage found!');
+    }
+
+    // Defaults to 'extwee' if missing.
+    storyData += ` creator="${story.creator}"`;
+
+    // Default to extwee version.
+    storyData += ` creator-version="${story.creatorVersion}"`;
+
+    // Check if IFID exists.
+    if (story.IFID !== '') {
+      // Write the existing IFID
+      storyData += ` ifid="${story.IFID}"`;
+    } else {
+      // Generate a new IFID
+      // Twine 2 uses v4 (random) UUIDs, using only capital letters
+      storyData += ` ifid="${uuidv4().toUpperCase()}"`;
+    }
+
+    // Write existing or default value.
+    storyData += ` zoom="${story.zoom}"`;
+
+    // Write existing or default value.
+    storyData += ` format="${storyFormat.name}"`;
+
+    // Write existing or default value.
+    storyData += ` format-version="${storyFormat.version}"`;
+
+    // Add the default.
+    storyData += ' options hidden>\n';
+
+    // Start the STYLE.
+    storyData += '\t<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">';
+
+    // Get stylesheet passages
+    const stylesheetPassages = story.getPassagesByTag('stylesheet');
+
+    // Concatenate passages
+    stylesheetPassages.forEach((passage) => {
+      // Add text of passages
+      storyData += passage.text;
+      // Remove from story
+      story.removePassage(passage);
+    });
+
+    // Close the STYLE
+    storyData += '</style>\n';
+
+    // Start the SCRIPT
+    storyData += '\t<script role="script" id="twine-user-script" type="text/twine-javascript">';
+
+    // Get stylesheet passages
+    const scriptPassages = story.getPassagesByTag('script');
+
+    // Concatenate passages
+    scriptPassages.forEach((passage) => {
+      // Add text of passages
+      storyData += passage.text;
+      // Remove from story
+      story.removePassage(passage);
+    });
+
+    // Close SCRIPT
+    storyData += '</script>\n';
+
+    // Build the passages
+    story.forEach((passage) => {
+      // Start the passage element
+      storyData += '\t<tw-passagedata';
+
+      /**
+       * pid: (string) Required.
+       *   The Passage ID (PID).
+       */
+      storyData += ` pid="${passage.pid}"`;
+
+      /**
+       * name: (string) Required.
+       *   The name of the passage.
+       */
+      storyData += ` name="${passage.name}"`;
+
+      /**
+       * tags: (string) Optional.
+       *   Any tags for the passage separated by spaces.
+       */
+      if (passage.tags.length > 1) {
+        storyData += ` tags="${passage.tags.join(' ')}" `;
+      } else if (passage.tags.length === 1) {
+        storyData += ` tags="${passage.tags[0]}" `;
+      }
+
+      /**
+       * position: (string) Optional.
+       *   Comma-separated X and Y position of the upper-left of the passage
+       *   when viewed within the Twine 2 editor.
+       */
+      if (Object.prototype.hasOwnProperty.call(passage.metadata, 'position')) {
+        storyData += ` position="${passage.metadata.position}" `;
+      }
+
+      /**
+       * size: (string) Optional.
+       *   Comma-separated width and height of the passage
+       *   when viewed within the Twine 2 editor.
+       */
+      if (Object.prototype.hasOwnProperty.call(passage.metadata, 'size')) {
+        storyData += `size="${passage.metadata.size}" `;
+      }
+
+      storyData += `>${passage.text}</tw-passagedata>\n`;
+    });
+
+    storyData += '</tw-storydata>';
+
+    // Replace the story name in the source file
+    storyFormat.source = storyFormat.source.replace(/{{STORY_NAME}}/g, story.name);
+
+    // Replace the story data
+    storyFormat.source = storyFormat.source.replace('{{STORY_DATA}}', storyData);
+
+    // Combine everything together.
+    outputContents += storyFormat.source;
+
+    try {
+      // Try to write.
+      fs.writeFileSync(file, outputContents);
+    } catch (event) {
+      // Throw error
+      throw new Error('Error: Cannot write HTML file!');
+    }
+  }
+}