extwee 2.2.1 → 2.2.3

package/src/Story.js

@@ -1,16 +1,50 @@
 import Passage from './Passage.js';
-import { v4 as uuidv4 } from 'uuid';
+import { generate as generateIFID } from './IFID/generate.js';
 import { encode } from 'html-entities';
 
 const creatorName = 'extwee';
-const creatorVersion = '2.2.1';
-
+const creatorVersion = '2.2.3';
+
+/**
+ * Story class.
+ * @class
+ * @classdesc Represents a Twine story.
+ * @property {string} name - Name of the story.
+ * @property {string} IFID - Interactive Fiction ID (IFID) of Story.
+ * @property {string} start - Name of start passage.
+ * @property {string} format - Story format of Story.
+ * @property {string} formatVersion - Story format version of Story.
+ * @property {number} zoom - Zoom level.
+ * @property {Array} passages - Array of Passage objects. @see {@link Passage}
+ * @property {string} creator - Program used to create Story.
+ * @property {string} creatorVersion - Version used to create Story.
+ * @property {object} metadata - Metadata of Story.
+ * @property {object} tagColors - Tag Colors
+ * @method {number} addPassage - Add a passage to the story and returns the new length of the passages array.
+ * @method {number} removePassageByName - Remove a passage from the story by name and returns the new length of the passages array.
+ * @method {Array} getPassagesByTag - Find passages by tag.
+ * @method {Array} getPassageByName - Find passage by name.
+ * @method {number} size - Size (number of passages).
+ * @method {string} toJSON - Export Story as JSON representation.
+ * @method {string} toTwee - Return Twee representation.
+ * @method {string} toTwine2HTML - Return Twine 2 HTML representation.
+ * @method {string} toTwine1HTML - Return Twine 1 HTML representation.
+ * @example
+ * const story = new Story('My Story');
+ * story.IFID = '12345678-1234-5678-1234-567812345678';
+ * story.start = 'Start';
+ * story.format = 'SugarCube';
+ * story.formatVersion = '2.31.0';
+ * story.zoom = 1;
+ * story.creator = 'extwee';
+ * story.creatorVersion = '2.2.1';
+ */
 class Story {
   /**
    * Internal name of story
    * @private
    */
-  #_name = '';
+  #_name = 'Untitled Story';
 
   /**
    * Internal start
@@ -37,8 +71,9 @@ class Story {
 
   /**
    * Internal zoom level
+   * Default is 1 (100%)
    */
-  #_zoom = 0;
+  #_zoom = 1;
 
   /**
    * Passages
@@ -74,12 +109,16 @@ class Story {
    * Creates a story.
    * @param {string} name - Name of the story.
    */
-  constructor (name = '') {
+  constructor (name = 'Untitled Story') {
     // Every story has a name.
     this.name = name;
+    
     // Store the creator.
     this.#_creator = creatorName;
+    
+    // Store the creator version.
     this.#_creatorVersion = creatorVersion;
+    
     // Set metadata to an object.
     this.#_metadata = {};
   }
@@ -119,13 +158,13 @@ class Story {
   }
 
   /**
-   * Interactive Fiction ID (IFID) of Story
+   * Interactive Fiction ID (IFID) of Story.
    * @returns {string} IFID
    */
   get IFID () { return this.#_IFID; }
 
   /**
-   * @param {string} i - Replacement IFID
+   * @param {string} i - Replacement IFID.
    */
   set IFID (i) {
     if (typeof i === 'string') {
@@ -255,10 +294,38 @@ class Story {
     }
   }
 
+  /**
+   * Passages in Story.
+   * @returns {Array} Passages
+   * @property {Array} passages - Passages
+  */
+  get passages () { return this.#_passages; }
+
+  /**
+   * Set passages in Story.
+   * @param {Array} p - Replacement passages
+   * @property {Array} passages - Passages
+   * @throws {Error} Passages must be an Array!
+   * @throws {Error} Passages must be an Array of Passage objects!
+   */
+  set passages (p) {
+    if (Array.isArray(p)) {
+      if (p.every((passage) => passage instanceof Passage)) {
+        this.#_passages = p;
+      } else {
+        throw new Error('Passages must be an Array of Passage objects!');
+      }
+    } else {
+      throw new Error('Passages must be an Array!');
+    }
+  }
+
   /**
    * Add a passage to the story.
-   * `StoryData` will override story metadata and `StoryTitle` will override story name.
+   * Passing `StoryData` will override story metadata and `StoryTitle` will override story name.
+   * @method addPassage
    * @param {Passage} p - Passage to add to Story.
+   * @returns {number} Return new length of passages array.
    */
   addPassage (p) {
     // Check if passed argument is a Passage.
@@ -271,9 +338,9 @@ class Story {
     // If it does, we ignore it and return.
     if (this.getPassageByName(p.name) !== null) {
       // Warn user
-      console.warn('Ignored passage with same name as existing one!');
+      console.warn(`Warning: A passage with the name "${p.name}" already exists!`);
       //
-      return;
+      return this.#_passages.length;
     }
 
     // Parse StoryData.
@@ -317,7 +384,7 @@ class Story {
       }
 
       // Don't add StoryData to passages.
-      return;
+      return this.#_passages.length;
     }
 
     // Parse StoryTitle.
@@ -326,24 +393,28 @@ class Story {
       // Set internal name based on StoryTitle.
       this.name = p.text;
       // Once we override story.name, return.
-      return;
+      return this.#_passages.length;
     }
 
     // This is not StoryData or StoryTitle.
     // Push the passage to the array.
-    this.#_passages.push(p);
+    return this.#_passages.push(p);
   }
 
   /**
    * Remove a passage from the story by name.
-   * @param {string} name - Passage name to remove
+   * @method removePassageByName
+   * @param {string} name - Passage name to remove.
+   * @returns {number} Return new length of passages array.
    */
   removePassageByName (name) {
     this.#_passages = this.#_passages.filter(passage => passage.name !== name);
+    return this.#_passages.length;
   }
 
   /**
    * Find passages by tag.
+   * @method getPassagesByTag
    * @param {string} t - Passage name to search for
    * @returns {Array} Return array of passages
    */
@@ -357,6 +428,7 @@ class Story {
 
   /**
    * Find passage by name.
+   * @method getPassageByName
    * @param {string} name - Passage name to search for
    * @returns {Passage | null} Return passage or null
    */
@@ -369,32 +441,16 @@ class Story {
 
   /**
    * Size (number of passages).
+   * @method size
    * @returns {number} Return number of passages
    */
   size () {
     return this.#_passages.length;
   }
 
-  /**
-   * forEach-style iterator of passages in Story.
-   * @param {Function} callback - Callback function
-   */
-  forEachPassage (callback) {
-    // Check if argument is a function.
-    if (typeof callback !== 'function') {
-      // Throw error
-      throw new Error('Callback must be a function!');
-    }
-
-    // Use internal forEach.
-    this.#_passages.forEach((element, index) => {
-      // Call callback function with element and index.
-      callback(element, index);
-    });
-  }
-
   /**
    * Export Story as JSON representation.
+   * @method toJSON
    * @returns {string} JSON string.
    */
   toJSON () {
@@ -414,7 +470,7 @@ class Story {
     };
 
     // For each passage, convert into simple object.
-    this.forEachPassage((p) => {
+    this.passages.forEach((p) => {
       s.passages.push({
         name: p.name,
         tags: p.tags,
@@ -432,6 +488,8 @@ class Story {
    *
    * See: Twee 3 Specification
    * (https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
+   * 
+   * @method toTwee
    * @returns {string} Twee String
    */
   toTwee () {
@@ -444,37 +502,57 @@ class Story {
     /**
      * ifid: (string) Required. Maps to <tw-storydata ifid>.
      */
-    // Is there an IFID?
-    if (this.IFID === '') {
+    // Test if IFID is in UUID format.
+    if (this.IFID.match(/^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/) === null) {
       // Generate a new IFID for this work.
-      // Twine 2 uses v4 (random) UUIDs, using only capital letters.
-      metadata.ifid = uuidv4().toUpperCase();
+      metadata.ifid = generateIFID();
+
+      // Write the existing IFID.
+      console.warn('Warning: IFID is not in UUIDv4 format! A new IFID was generated.');
     } else {
-      // Use existing (non-default) value.
+      // Write the IFID.
       metadata.ifid = this.IFID;
     }
 
     /**
      * format: (string) Optional. Maps to <tw-storydata format>.
-     */
-    metadata.format = this.format;
+    */
+    // Does format exist?
+    if (this.format !== '') {
+      // Write the existing format.
+      metadata.format = this.format;
+    }
 
     /**
      * format-version: (string) Optional. Maps to <tw-storydata format-version>.
      */
-    metadata['format-version'] = this.formatVersion;
+    // Does formatVersion exist?
+    if (this.formatVersion !== '') {
+      // Write the existing formatVersion.
+      metadata['format-version'] = this.formatVersion;
+    }
 
     /**
      * zoom: (decimal) Optional. Maps to <tw-storydata zoom>.
      */
-    metadata.zoom = this.zoom;
+    // Does zoom exist?
+    if (this.zoom !== 0) {
+      // Write the existing zoom.
+      metadata.zoom = this.zoom;
+    }
 
     /**
      * start: (string) Optional.
      * Maps to <tw-passagedata name> of the node whose pid matches <tw-storydata startnode>.
+     * 
+     * If there is no start value, the "Start" passage is assumed to be the starting passage.
      */
-    metadata.start = this.start;
-
+    // Does start exist?
+    if (this.start !== '') {
+      // Write the existing start.
+      metadata.start = this.start;
+    }
+   
     /**
      * tag-colors: (object of tag(string):color(string) pairs) Optional.
      * Pairs map to <tw-tag> nodes as <tw-tag name>:<tw-tag color>.
@@ -500,7 +578,7 @@ class Story {
     outputContents += '\n\n';
 
     // For each passage, append it to the output.
-    this.forEachPassage((passage) => {
+    this.passages.forEach((passage) => {
       outputContents += passage.toTwee();
     });
 
@@ -513,108 +591,185 @@ class Story {
    *
    * See: Twine 2 HTML Output
    * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md)
+   * 
+   *  The only required attributes are `name` and `ifid` of the `<tw-storydata>` element. All others are optional.
+   * 
+   * The `<tw-storydata>` element may have any number of optional attributes, which are:
+   * - `startnode`: (integer) Optional. The PID of the starting passage.
+   * - `creator`: (string) Optional. The name of the program that created the story.
+   * - `creator-version`: (string) Optional. The version of the program that created the story.
+   * - `zoom`: (decimal) Optional. The zoom level of the story.
+   * - `format`: (string) Optional. The format of the story.
+   * - `format-version`: (string) Optional. The version of the format of the story.
+   * 
+   * @method toTwine2HTML
    * @returns {string} Twine 2 HTML string
    */
   toTwine2HTML () {
-    // Prepare HTML content.
+    // Get the passages.
+    // Make a local copy, as we might be modifying it.
+    let passages = this.passages;
+
+    // Twine 2 HTML starts with a <tw-storydata> element.
+    // See: Twine 2 HTML Output
+
+    // name: (string) Required. The name of the story.
+    //
+    // Maps to <tw-storydata name>.
+    //
     let storyData = `<tw-storydata name="${ encode( this.name ) }"`;
-    // Passage Identification (PID) counter.
-    // (Twine 2 starts with 1, so we mirror that.)
-    let PIDcounter = 1;
 
-    // Does start exist?
-    if (this.start === '') {
-      // We can't create a Twine 2 HTML file without a starting passage.
-      throw new Error('No starting passage!');
+    // 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).
+    //
+    // Maps to <tw-storydata ifid>.
+    //
+    // Check if IFID exists.
+    if (this.IFID !== '') {
+      // Write the existing IFID.
+      storyData += ` ifid="${ this.IFID }"`;
+    } else {
+      // Generate a new IFID.
+      // Twine 2 uses v4 (random) UUIDs, using only capital letters.
+      storyData += ` ifid="${ generateIFID() }"`;
     }
 
-    // Try to find starting passage.
-    // If it doesn't exist, we throw an error.
-    if (this.getPassageByName(this.start) === null) {
-      // We can't create a Twine 2 HTML file without a starting passage.
-      throw new Error('Starting passage not found');
-    }
+    // 'Start' passage (if there is not a 'start' value set).
+    let startPassagePID = null;
+
+    // Passage Identification (PID) counter.
+    // (Twine 2 starts with 1, so we mirror that.)
+    let PIDcounter = 1;
 
     // Set initial PID value.
     let startPID = 1;
+
     // We have to do a bit of nonsense here.
     // Twine 2 HTML cares about PID values.
-    this.forEachPassage((p) => {
+    passages.forEach((p) => {
       // Have we found the starting passage?
       if (p.name === this.start) {
         // If so, set the PID based on index.
         startPID = PIDcounter;
       }
+
+      // Have we found the 'Start' passage?
+      if (p.name === 'Start') {
+        // If so, set the PID based on index.
+        startPassagePID = PIDcounter;
+      }
+
       // Increase and keep looking.
       PIDcounter++;
     });
 
-    // Set starting passage PID.
-    storyData += ` startnode="${startPID}"`;
-
-    // Defaults to 'extwee' if missing.
-    storyData += ` creator="${ encode( this.creator ) }"`;
-
-    // Default to extwee version.
-    storyData += ` creator-version="${this.creatorVersion}"`;
+    // startnode: (integer) Optional.
+    //
+    // Maps to <tw-storydata startnode>.
+    //
+    // Check if startnode exists.
+    if(this.start !== '') {
+      // Set starting passage PID.
+      storyData += ` startnode="${startPID}"`;
+    }
 
-    // Check if IFID exists.
-    if (this.IFID !== '') {
-      // Write the existing IFID.
-      storyData += ` ifid="${this.IFID}"`;
-    } else {
-      // Generate a new IFID.
-      // Twine 2 uses v4 (random) UUIDs, using only capital letters.
-      storyData += ` ifid="${uuidv4().toUpperCase()}"`;
+    /**
+     * If we came from Twee or another source, we might not have a start value.
+     * 
+     * We might, however, have a passage with the name "Start".
+     */
+    if(this.start === '' && startPassagePID !== null) {
+      // Set starting passage PID.
+      storyData += ` startnode="${startPassagePID}"`;
+    }
+    
+    // creator: (string) Optional. The name of the program that created the story.
+    // Maps to <tw-storydata creator>.
+    if(this.creator !== '') {
+      // Write existing creator.
+      storyData += ` creator="${ encode( this.creator ) }"`;
     }
 
-    // Write existing or default value.
-    storyData += ` zoom="${this.zoom}"`;
+    // creator-version: (string) Optional. The version of the program that created the story.
+    // Maps to <tw-storydata creator-version>.
+    if(this.creatorVersion !== '') {
+       // Default to extwee version.
+      storyData += ` creator-version="${this.creatorVersion}"`;
+    }
 
-    // Write existing or default value.
-    storyData += ` format="${ encode(this.#_format) }"`;
+    // zoom: (decimal) Optional. The zoom level of the story.
+    // Maps to <tw-storydata zoom>.
+    if(this.zoom !== 1) {
+      // Write existing or default value.
+      storyData += ` zoom="${this.zoom}"`;
+    }
 
-    // Write existing or default value.
-    storyData += ` format-version="${this.#_formatVersion}"`;
+    // format: (string) Optional. The format of the story.
+    // Maps to <tw-storydata format>.
+    if(this.format !== '') {
+      // Write existing or default value.
+      storyData += ` format="${this.format}"`;
+    }
+   
+    // format-version: (string) Optional. The version of the format of the story.
+    // Maps to <tw-storydata format-version>.
+    if(this.formatVersion !== '') {
+      // Write existing or default value.
+      storyData += ` format-version="${this.formatVersion}"`;
+    }
 
     // Add the default attributes.
     storyData += ' options hidden>\n';
 
-    // Start the STYLE.
-    storyData += '\t<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">';
+    // Filter out passages with tag of 'stylesheet'.
+    const stylesheetPassages = passages.filter((passage) => passage.tags.includes('stylesheet'));
 
-    // Get stylesheet passages.
-    const stylesheetPassages = this.getPassagesByTag('stylesheet');
+    // Remove stylesheet passages from the main array.
+    passages = passages.filter(p => !p.tags.includes('stylesheet'));
 
-    // Concatenate passages.
-    stylesheetPassages.forEach((passage) => {
-      // Add text of passages.
-      storyData += passage.text;
-    });
+    // Were there any stylesheet passages?
+    if (stylesheetPassages.length > 0) {
+      // Start the STYLE.
+      storyData += '\t<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">';
 
-    // Close the STYLE.
-    storyData += '</style>\n';
+      // Concatenate passages.
+      stylesheetPassages.forEach((passage) => {
+        // Add text of passages.
+        storyData += passage.text;
+      });
 
-    // Start the SCRIPT.
-    storyData += '\t<script role="script" id="twine-user-script" type="text/twine-javascript">';
+      // Close the STYLE.
+      storyData += '</style>\n';
+    }
 
-    // Get stylesheet passages.
-    const scriptPassages = this.getPassagesByTag('script');
+    // Filter out passages with tag of 'script'.
+    const scriptPassages = passages.filter((passage) => passage.tags.includes('script'));
 
-    // Concatenate passages.
-    scriptPassages.forEach((passage) => {
-      // Add text of passages.
-      storyData += passage.text;
-    });
+    // Remove script passages from the main array.
+    passages = passages.filter(p => !p.tags.includes('script'));
 
-    // Close SCRIPT.
-    storyData += '</script>\n';
+    // Were there any script passages?
+    if (scriptPassages.length > 0) {
+      // Start the SCRIPT.
+      storyData += '\t<script role="script" id="twine-user-script" type="text/twine-javascript">';
+
+      // Concatenate passages.
+      scriptPassages.forEach((passage) => {
+        // Add text of passages.
+        storyData += passage.text;
+      });
+
+      // Close SCRIPT.
+      storyData += '</script>\n';
+    }
 
     // Reset the PID counter.
     PIDcounter = 1;
 
     // Build the passages HTML.
-    this.forEachPassage((passage) => {
+    this.passages.forEach((passage) => {
       // Append each passage element using the PID counter.
       storyData += passage.toTwine2HTML(PIDcounter);
       // Increase counter inside loop.
@@ -633,6 +788,8 @@ class Story {
    *
    * See: Twine 1 HTML Output
    * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md)
+   * 
+   * @method toTwine1HTML
    * @returns {string} Twine 1 HTML string.
    */
   toTwine1HTML () {
@@ -640,7 +797,7 @@ class Story {
     let outputContents = '';
 
     // Process passages (if any).
-    this.forEachPassage((p) => {
+    this.passages.forEach((p) => {
       // Output HTML output per passage.
       outputContents += `\t${p.toTwine1HTML()}`;
     });
@@ -648,6 +805,8 @@ class Story {
     // Return Twine 1 HTML content.
     return outputContents;
   }
+
+ 
 }
 
 export { Story, creatorName, creatorVersion };