extwee 1.6.0 → 2.0.2

package/src/HTMLWriter.js

@@ -1,177 +1,227 @@
-const fs = require("fs");
-const Story = require('./Story.js');
-const StoryFormat = require('./StoryFormat.js');
-/**
- * @class HTMLWriter
- * @module HTMLWriter
- */
-class HTMLWriter {
-	/**
-     * @method HTMLWriter
-     * @constructor
-     */
-    constructor (file, story, storyFormat, css, js) {
-
-        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 cssContent = css || null;
-        let jsContent = js || null;
-
-        this.writeFile(file, story, storyFormat, cssContent, jsContent);
-    }
-
-    writeFile(file, story, storyFormat, cssContent, jsContent) {
-
-        let outputContents = "";
-
-        // Build <tw-storydata>
-        let storyData =
-            '<tw-storydata name="' + story.name + '" ' +
-            'startnode="' + story.getStartingPassage() + '" ' +
-            'creator="' + story.creator + '" ' +
-            'creator-version="' + story.creatorVersion + '" ' +
-            'ifid="' + story.metadata.ifid + '" ' +
-            'zoom="' + story.metadata.zoom + '" ' +
-            'format="' + storyFormat.name + '" ' +
-            'format-version="' + storyFormat.version + '" ' +
-            'options hidden>\n';
-
-        // Build the STYLE
-        storyData += '<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">';
-
-        // Get any passages tagged with 'stylesheet'
-        let stylePassages = story.getStylePassages();
-
-        // CSS passed through from DirectoryReader
-        if(cssContent != null) {
-          storyData += cssContent;
-        }
-
-        // Iterate through the collection and add to storyData
-        for(let content of stylePassages) {
-            storyData += content.text;
-        }
-
-        storyData += '</style>\n';
-
-        // Build the SCRIPT
-        storyData += '<script role="script" id="twine-user-script" type="text/twine-javascript">';
-
-        // Get any passages tagged with 'script'
-        let scriptPassages = story.getScriptPassages();
-
-        // JS passed through from DirectoryReader
-        if(jsContent != null) {
-          storyData += jsContent;
-        }
-
-        // Iterate through the collection and add to storyData
-        for(let content of scriptPassages) {
-            storyData += content.text;
-        }
-
-        storyData += '</script>\n';
-
-        // All the script data has been written.
-        // Delete all 'script'-tagged passages
-        story.deleteAllByTag("script");
-
-        // All the style data has been written.
-        // Delete all 'style'-tagged passages
-        story.deleteAllByTag("stylesheet");
-
-        // Build the passages
-        for(let passage of story.passages) {
-
-            storyData += '<tw-passagedata pid="' + passage.pid + '" name="' + passage.name + '"';
-
-            // Write out any tags
-            if(passage.tags.length > 1) {
-
-                storyData += ' tags="';
-
-                for(let t of passage.tags) {
-
-                    storyData += t + ', ';
-
-                }
-
-                storyData += '" ';
-
-            } else if(passage.tags.length == 1) {
-
-                storyData += ' tags="' + passage.tags[0] + '" ';
-
-            } else {
-
-                storyData += ' tags ';
-
-            }
-
-            // Write out position
-            if(passage.metadata.hasOwnProperty("position")) {
-
-                storyData += 'position="' +
-                    passage.metadata.position + '" ';
-
-            } else {
-
-                // Didn't have a position.
-                // Make one up.
-                storyData += 'position="100,100" ';
-
-            }
-
-            // Write out size
-            if(passage.metadata.hasOwnProperty("size") ) {
-
-                storyData += 'size="' +
-                    passage.metadata.size + '" ';
-
-            } else {
-
-                // Didn't have a size.
-                // Make one up.
-                storyData += 'size="100,100" ';
-
-            }
-
-            storyData += '>' + passage.text + '</tw-passagedata>\n';
-
-        }
-
-        storyData += '</tw-storydata>';
-
-        // Replace the story name in the source file
-        storyFormat.source = storyFormat.source.replace("{{STORY_NAME}}", story.name);
-
-        // Replace the story data
-        storyFormat.source = storyFormat.source.replace("{{STORY_DATA}}", storyData);
-
-        outputContents += storyFormat.source
-
-        try {
-
-          // Try to write
-          fs.writeFileSync(file, outputContents);
-
-        } catch(event) {
-
-          // Throw error
-          throw new Error("Error: Cannot write HTML file!");
-
-        }
-
-    }
-
-}
-
-module.exports = HTMLWriter;
+/**
+ * @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 += `>${HTMLWriter.escape(passage.text)}</tw-passagedata>\n`;
+    });
+
+    storyData += '</tw-storydata>';
+
+    // Replace the story name in the source file
+    storyFormat.source = storyFormat.source.replaceAll(/{{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!');
+    }
+  }
+
+  /**
+   * Escape HTML characters
+   *
+   * @public
+   * @static
+   * @function escape
+   * @param {string} text - Text to escape
+   * @returns {string} Escaped text
+   */
+  static escape (text) {
+    // Throw error if text is not a string
+    if (Object.prototype.toString.call(text) !== '[object String]') {
+      throw new Error('Text argument is not a String');
+    }
+
+    const rules = [
+      ['&', '&amp;'],
+      ['<', '&lt;'],
+      ['>', '&gt;'],
+      ['"', '&quot;'],
+      ["'", '&#x27;'],
+      ['`', '&#x60;']
+    ];
+
+    rules.forEach(([rule, template]) => {
+      text = text.replaceAll(rule, template);
+    });
+
+    return text;
+  }
+}

package/src/Passage.js

@@ -1,20 +1,202 @@
-/**
- * @class Passage
- * @module Passage
- */
-class Passage {
-	/**
-     * @method Passage
-     * @constructor
-     */
-    constructor (name = "", tags = [], metadata = {}, text = "", pid = 1) {
-        this.name = name;
-        this.tags = tags;
-        this.metadata = metadata;
-        this.text = text;
-        this.pid = pid;
-    }
-
-}
-
-module.exports = Passage;
+/**
+ * @class Passage
+ * @module Passage
+ */
+export default class Passage {
+  /**
+   * Name of the Passage
+   *
+   * @private
+   */
+  #_name = null;
+
+  /**
+   * Internal array of tags
+   *
+   * @private
+   */
+  #_tags = [];
+
+  /**
+   * Internal metadata of passage
+   *
+   * @private
+   */
+  #_metadata = {};
+
+  /**
+   * Internal text of the passage
+   *
+   * @private
+   */
+  #_text = '';
+
+  /**
+   * Internal PID of passage
+   *
+   * @private
+   */
+  #_pid = -1;
+
+  /**
+   * @function Passage
+   * @class
+   * @param {string} name - Name
+   * @param {string} text - Content
+   * @param {Array} tags - Tags
+   * @param {object} metadata - Metadata
+   * @param {number} pid - Passage ID (PID)
+   */
+  constructor (name = '', text = '', tags = [], metadata = {}, pid = -1) {
+    // Set name
+    this.name = name;
+
+    // Set tags
+    this.tags = tags;
+
+    // Set metadata
+    this.metadata = metadata;
+
+    // Sets text
+    this.text = text;
+
+    // Sets pid
+    this.pid = pid;
+  }
+
+  /**
+   * Name
+   *
+   * @public
+   * @memberof Passage
+   * @returns {string} Name
+   */
+  get name () { return this.#_name; }
+
+  /**
+   * @param {string} s - Name to replace
+   */
+  set name (s) {
+    if (typeof s === 'string') {
+      this.#_name = s;
+    } else {
+      throw new Error('Name must be a String!');
+    }
+  }
+
+  /**
+   * Tags
+   *
+   * @public
+   * @memberof Passage
+   * @returns {Array} Tags
+   */
+  get tags () { return this.#_tags; }
+
+  /**
+   * @param {Array} t - Replacement array
+   */
+  set tags (t) {
+    // Test if tags is an array
+    if (Array.isArray(t)) {
+      this.#_tags = t;
+    } else {
+      throw new Error('Tags must be an array!');
+    }
+  }
+
+  /**
+   * Metadata
+   *
+   * @public
+   * @memberof Passage
+   * @returns {object} Metadata
+   */
+  get metadata () { return this.#_metadata; }
+
+  /**
+   * @param {object} m - Replacement object
+   */
+  set metadata (m) {
+    // Test if metadata was an object
+    if (typeof m === 'object') {
+      this.#_metadata = m;
+    } else {
+      throw new Error('Metadata should be an object literal!');
+    }
+  }
+
+  /**
+   * Text
+   *
+   * @public
+   * @memberof Passage
+   * @returns {string} Text
+   */
+  get text () { return this.#_text; }
+
+  /**
+   * @param {string} t - Replacement text
+   */
+  set text (t) {
+    // Test if text is a String
+    if (typeof t === 'string') {
+      this.#_text = t;
+    } else {
+      throw new Error('Text should be a String!');
+    }
+  }
+
+  /**
+   * Passage ID (PID)
+   *
+   * @public
+   * @memberof Passage
+   * @returns {number} Passage ID (PID)
+   */
+  get pid () { return this.#_pid; }
+
+  /**
+   * @param {number} p - Replacement PID
+   */
+  set pid (p) {
+    // Test if PID is a number
+    if (Number.isInteger(p)) {
+      this.#_pid = p;
+    } else {
+      throw new Error('PID should be a number!');
+    }
+  }
+
+  /**
+   * Return a String representation
+   *
+   * @public
+   * @memberof Passage
+   * @returns {string} String form of passage
+   */
+  toString () {
+    // Start empty string.
+    let content = '';
+    // Write the name
+    content += `:: ${this.name}`;
+
+    // Test if it has any tags
+    if (this.tags.length > 0) {
+      // Write output of tags
+      content += ` [${this.tags.join(' ')}]`;
+    }
+
+    // Check if any properties exist
+    if (Object.keys(this.metadata).length > 0) {
+      // Write out a space and then passage metadata
+      content += ` ${JSON.stringify(this.metadata)}`;
+    }
+
+    // Add newline, text, and two newlines
+    content += `\n${this.text}\n\n`;
+
+    // Return string.
+    return content;
+  }
+}