extwee 1.5.3 → 2.0.0

package/src/StoryFormat.js

@@ -0,0 +1,300 @@
+/**
+ * @class StoryFormat
+ * @module StoryFormat
+ */
+export default class StoryFormat {
+  /**
+   * Internal name
+   *
+   * @private
+   */
+  #_name = '';
+
+  /**
+   * Internal version
+   *
+   * @private
+   */
+  #_version = '';
+
+  /**
+   * Internal description
+   *
+   * @private
+   */
+  #_description = '';
+
+  /**
+   * Internal author
+   *
+   * @private
+   */
+  #_author = '';
+
+  /**
+   * Internal image
+   *
+   * @private
+   */
+  #_image = '';
+
+  /**
+   * Internal URL
+   *
+   * @private
+   */
+  #_url = '';
+
+  /**
+   * Internal license
+   *
+   * @private
+   */
+  #_license = '';
+
+  /**
+   * Internal proofing
+   *
+   * @private
+   */
+  #_proofing = '';
+
+  /**
+   * Internal source
+   *
+   * @private
+   */
+  #_source = '';
+
+  /**
+   * @class
+   * @function StoryFormat
+   * @param {string} name - Name
+   * @param {string} version - Version
+   * @param {string} description - Description
+   * @param {string} author - Author
+   * @param {string} image - Image
+   * @param {string} url - URL
+   * @param {string} license - License
+   * @param {boolean} proofing - If proofing or not
+   * @param {string} source - Source
+   */
+  constructor (
+    name = '',
+    version = '',
+    description = '',
+    author = '',
+    image = '',
+    url = '',
+    license = '',
+    proofing = false,
+    source = ''
+  ) {
+    // Set name
+    this.name = name;
+
+    // Set version
+    this.version = version;
+
+    // Set description
+    this.description = description;
+
+    // Set author
+    this.author = author;
+
+    // Set image
+    this.image = image;
+
+    // Set URL
+    this.url = url;
+
+    // Set license
+    this.license = license;
+
+    // Set proofing
+    this.proofing = proofing;
+
+    // Set source
+    this.source = source;
+  }
+
+  /**
+   * Name
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} Name
+   */
+  get name () { return this.#_name; }
+
+  /**
+   * @param {string} n - Replacement name
+   */
+  set name (n) {
+    if (typeof n === 'string') {
+      this.#_name = n;
+    } else {
+      throw new Error('Name must be a string!');
+    }
+  }
+
+  /**
+   * Version
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} Version
+   */
+  get version () { return this.#_version; }
+
+  /**
+   * @param {string} n - Replacement version
+   */
+  set version (n) {
+    if (typeof n === 'string') {
+      this.#_version = n;
+    } else {
+      throw new Error('Version must be a string!');
+    }
+  }
+
+  /**
+   * Description
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} Description
+   */
+  get description () { return this.#_description; }
+
+  /**
+   * @param {string} d - Replacement description
+   */
+  set description (d) {
+    if (typeof d === 'string') {
+      this.#_description = d;
+    } else {
+      throw new Error('Description must be a string!');
+    }
+  }
+
+  /**
+   * Author
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} Author
+   */
+  get author () { return this.#_author; }
+
+  /**
+   * @param {string} a - Replacement author
+   */
+  set author (a) {
+    if (typeof a === 'string') {
+      this.#_author = a;
+    } else {
+      throw new Error('Author must be a string!');
+    }
+  }
+
+  /**
+   * Image
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} Image
+   */
+  get image () { return this.#_image; }
+
+  /**
+   * @param {string} i - Replacement image
+   */
+  set image (i) {
+    if (typeof i === 'string') {
+      this.#_image = i;
+    } else {
+      throw new Error('Image must be a string!');
+    }
+  }
+
+  /**
+   * URL
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} URL
+   */
+  get url () { return this.#_url; }
+
+  /**
+   * @param {string} u - Replacement URL
+   */
+  set url (u) {
+    if (typeof u === 'string') {
+      this.#_url = u;
+    } else {
+      throw new Error('URL must be a string!');
+    }
+  }
+
+  /**
+   * License
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} License
+   */
+  get license () { return this.#_license; }
+
+  /**
+   * @param {string} l - Replacement license
+   */
+  set license (l) {
+    if (typeof l === 'string') {
+      this.#_license = l;
+    } else {
+      throw new Error('License must be a string!');
+    }
+  }
+
+  /**
+   * Proofing
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {boolean} Proofing
+   */
+  get proofing () { return this.#_proofing; }
+
+  /**
+   * @param {boolean} p - Replacement proofing
+   */
+  set proofing (p) {
+    if (typeof p === 'boolean') {
+      this.#_proofing = p;
+    } else {
+      throw new Error('Proofing must be a Boolean!');
+    }
+  }
+
+  /**
+   * Source
+   *
+   * @public
+   * @memberof StoryFormat
+   * @returns {string} Source
+   */
+  get source () { return this.#_source; }
+
+  /**
+   * @param {string} s - Replacement source
+   */
+  set source (s) {
+    if (typeof s === 'string') {
+      this.#_source = s;
+    } else {
+      throw new Error('Source must be a String!');
+    }
+  }
+}

package/src/StoryFormatParser.js

@@ -0,0 +1,142 @@
+import StoryFormat from './StoryFormat.js';
+import semver from 'semver';
+/**
+ * @class StoryFormatParser
+ * @module StoryFormatParser
+ */
+export default class StoryFormatParser {
+  /**
+   * Parse a Story Format file
+   *
+   * @public
+   * @static
+   * @memberof StoryFormatParser
+   * @function parse
+   * @param {string} contents - Content
+   * @returns {StoryFormat} StoryFormat object
+   */
+  static parse (contents) {
+    // Harlowe has malformed JSON, so we have to test for it
+    const harlowePosition = contents.indexOf('harlowe');
+
+    if (harlowePosition !== -1) {
+      // The 'setup' property is malformed
+      const setupPosition = contents.lastIndexOf(',"setup": function');
+      contents = contents.slice(0, setupPosition) + '}';
+    }
+
+    // Find the start of story format or -1, if not found
+    const openingCurlyBracketPosition = contents.indexOf('{');
+    // Find the end of story format or -1, if not found
+    const closingCurlyBracketPosition = contents.lastIndexOf('}');
+
+    // Look for JSON among the story format
+    // If either is -1, this is not valid JSON
+    if (openingCurlyBracketPosition === -1 || closingCurlyBracketPosition === -1) {
+      // Either start or end curly brackets were now found!
+      throw new Error('Unable to find Twine2 JSON chunk!');
+    } else {
+      // Slice out the JSON based on curly brackets
+      contents = contents.slice(openingCurlyBracketPosition, closingCurlyBracketPosition + 1);
+    }
+
+    // Create an object literal
+    let jsonContent = {};
+
+    try {
+      jsonContent = JSON.parse(contents);
+    } catch (event) {
+      throw new Error('Unable to parse Twine2 JSON chunk!');
+    }
+
+    /**
+     * The following keys are found in most or all story formats:
+     * - name: (string) Optional. Name of the story format.
+     *      (Omitting the name will lead to an Untitled Story Format.)
+     * - version: (string) Required, and semantic version-style formatting
+     *      (x.y.z, e.g., 1.2.1) of the version is also required.
+     * - author: (string) Optional.
+     * - description: (string) Optional.
+     * - image: (string) Optional. The filename of an image (ideally SVG)
+     *      served from the same directory as the format.js file.
+     * - url: (string) Optional. The URL of the directory containing the format.js file.
+     * - license: (string) Optional.
+     * - proofing: (boolean) Optional (defaults to false). True if the story format
+     *      is a "proofing" format. The distinction is relevant only in the Twine 2 UI.
+     * - source: (string) Required. Full HTML output of the story format.
+     * (See: https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md)
+     */
+
+    // Name is optional, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'name')) {
+      // Use the default name
+      jsonContent.name = 'Untitled Story Format';
+    }
+
+    // Author is optional, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'author')) {
+      // Use the default author
+      jsonContent.author = '';
+    }
+
+    // Description is optional, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'description')) {
+      // Use the default description
+      jsonContent.description = '';
+    }
+
+    // Image is optional, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'image')) {
+      // Use the default image
+      jsonContent.image = '';
+    }
+
+    // URL is optional, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'url')) {
+      // Use the default url
+      jsonContent.url = '';
+    }
+
+    // License is optional, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'license')) {
+      // Use the default license
+      jsonContent.license = '';
+    }
+
+    // Proofing is optional, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'proofing')) {
+      // Use the default proofing
+      jsonContent.proofing = false;
+    }
+
+    // Version is required, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'version')) {
+      // Throw error
+      throw new Error('Processed story format does not have required version property!');
+    }
+
+    // Test if version is semantic-style, which is required
+    if (semver.valid(jsonContent.version) === null) {
+      throw new Error('Processed story format\'s version is not a valid semantic value!');
+    }
+
+    // Source is required, so we have to test for it
+    if (!Object.prototype.hasOwnProperty.call(jsonContent, 'source')) {
+      // Throw error
+      throw new Error('Processed story format does not have required source property!');
+    }
+
+    // Pass all values to the constructor and return the result
+    return new StoryFormat(
+      jsonContent.name,
+      jsonContent.version,
+      jsonContent.description,
+      jsonContent.author,
+      jsonContent.image,
+      jsonContent.url,
+      jsonContent.license,
+      jsonContent.proofing,
+      jsonContent.source
+    );
+  }
+}

package/src/TweeParser.js

@@ -0,0 +1,166 @@
+import Passage from './Passage.js';
+import Story from './Story.js';
+/**
+ * @class TweeParser
+ * @module TweeParser
+ */
+export default class TweeParser {
+  /**
+   * Parse Twee
+   *
+   * @public
+   * @static
+   * @function parse
+   * @param {string} fileContents - File contents to parse
+   * @returns {Story} story
+   */
+  static parse (fileContents) {
+    // Create Story.
+    const story = new Story();
+
+    // Check if argument is a string
+    const isString = (x) => {
+      return Object.prototype.toString.call(x) === '[object String]';
+    };
+
+    // Throw error if fileContents is empty
+    if (!isString(fileContents)) {
+      throw new Error('Contents not a String');
+    }
+
+    let adjusted = '';
+
+    // Check if there are extra content in the files
+    // If so, cut it all out for the parser
+    if (fileContents[0] !== ':' && fileContents[1] !== ':') {
+      adjusted = fileContents.slice(fileContents.indexOf('::'), fileContents.length);
+    } else {
+      adjusted = fileContents;
+    }
+
+    // Split the file based on the passage sigil (::) proceeded by a newline
+    const parsingPassages = adjusted.split('\n::');
+
+    // Fix the first result
+    parsingPassages[0] = parsingPassages[0].slice(2, parsingPassages[0].length);
+
+    // Set the initial pid
+    let pid = 1;
+
+    // Iterate through the passages
+    parsingPassages.forEach((passage) => {
+      // Set default values
+      let tags = '';
+      let metadata = '';
+      let text = '';
+      let name = '';
+
+      // Header is everything to the first newline
+      let header = passage.slice(0, passage.indexOf('\n'));
+      // Text is everything else
+      // (Also eat the leading newline character.)
+      // (And trim any remaining whitespace.)
+      text = passage.substring(header.length + 1, passage.length).trim();
+
+      // Test for metadata
+      const openingCurlyBracketPosition = header.lastIndexOf('{');
+      const closingCurlyBracketPosition = header.lastIndexOf('}');
+
+      if (openingCurlyBracketPosition !== -1 && closingCurlyBracketPosition !== -1) {
+        // Save the text metadata
+        metadata = header.slice(openingCurlyBracketPosition, closingCurlyBracketPosition + 1);
+
+        // Remove the metadata from the header
+        header = header.substring(0, openingCurlyBracketPosition) + header.substring(closingCurlyBracketPosition + 1);
+      }
+
+      // There was passage metadata
+      if (metadata.length > 0) {
+        // Try to parse the metadata
+        try {
+          metadata = JSON.parse(metadata);
+        } catch (event) {
+        }
+      } else {
+        // There wasn't any metadata, so set default
+        metadata = {};
+      }
+
+      // Test for tags
+      const openingSquareBracketPosition = header.lastIndexOf('[');
+      const closingSquareBracketPosition = header.lastIndexOf(']');
+
+      if (openingSquareBracketPosition !== -1 && closingSquareBracketPosition !== -1) {
+        tags = header.slice(openingSquareBracketPosition, closingSquareBracketPosition + 1);
+
+        // Remove the tags from the header
+        header = header.substring(0, openingSquareBracketPosition) + header.substring(closingSquareBracketPosition + 1);
+      }
+
+      // Parse tags
+      if (tags.length > 0) {
+        // Eat the opening and closing square brackets
+        tags = tags.substring(1, tags.length - 1);
+
+        // Set empty default
+        let tagsArray = [];
+
+        // Test if tags is not single, empty string
+        if (!(tags === '')) {
+          tagsArray = tags.split(' ');
+        }
+
+        // There are multiple tags
+        if (tagsArray.length > 1) {
+        // Create future array
+          const futureTagArray = [];
+
+          // Move through entries
+          // Add a trimmed version into future array
+          tagsArray.forEach((tag) => { futureTagArray.push(tag.trim()); });
+
+          // Set the tags back to the future array
+          tags = futureTagArray;
+        } else if (tagsArray.length === 1) {
+          // There was only one tag
+          // Store it
+          const temp = tags;
+
+          // Switch tags over to an array
+          tags = [];
+          // Push the single entry
+          tags.push(temp);
+        } else {
+        // Make sure tags is set to empty array if no tags were found
+          tags = [];
+        }
+      } else {
+        // There were no tags, so set it to an empty array;
+        tags = [];
+      }
+
+      // Filter out any empty string tags
+      tags = tags.filter(tag => tag !== '');
+
+      // Trim any remaining whitespace
+      header = header.trim();
+
+      // Check if there is a name left
+      if (header.length > 0) {
+        name = header;
+      } else {
+        // No name left. Something went wrong. Blame user.
+        throw new Error('Malformed passage header!');
+      }
+
+      // addPassage() method does all the work
+      story.addPassage(new Passage(name, text, tags, metadata, pid));
+
+      // Increase pid
+      pid++;
+    });
+
+    // Return Story.
+    return story;
+  }
+}

package/src/TweeWriter.js

@@ -0,0 +1,98 @@
+/**
+ * @external Story
+ * @see Story.js
+ * @external Passage
+ * @see Passage.js
+ */
+
+import fs from 'fs';
+import Story from './Story.js';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * @class TweeWriter
+ * @module TweeWriter
+ */
+export default class TweeWriter {
+  /**
+   * Write to a file using a Story object
+   *
+   * @static
+   * @param {Story} story - Story format to write
+   * @param {string} file - File to write to
+   * @returns {void}
+   */
+  static write (story, file) {
+    if (!(story instanceof Story)) {
+      throw new Error('Not a Story object!');
+    }
+
+    // Write the StoryData first.
+    let outputContents = ':: StoryData\n';
+
+    // Create default object.
+    const metadata = {};
+
+    // Is there an IFID?
+    if (story.IFID === '') {
+      // Generate a new IFID for this work.
+      // Twine 2 uses v4 (random) UUIDs, using only capital letters.
+      metadata.ifid = uuidv4().toUpperCase();
+    } else {
+      // Use existing (non-default) value.
+      metadata.ifid = story.IFID;
+    }
+
+    // Is there a format?
+    if (story.format !== '') {
+      // Using existing format
+      metadata.format = story.format;
+    }
+
+    // Is there a formatVersion?
+    if (story.formatVersion !== '') {
+      // Using existing format version
+      metadata['format-version'] = story.formatVersion;
+    }
+
+    // Is there a zoom?
+    if (story.zoom !== 0) {
+      // Using existing zoom.
+      metadata.zoom = story.zoom;
+    }
+
+    // Is there a start?
+    if (story.start !== '') {
+      // Using existing start
+      metadata.start = story.start;
+    }
+
+    // Get number of colors.
+    const numberOfColors = Object.keys(story.tagColors).length;
+    // Are there any colors?
+    if (numberOfColors > 0) {
+      // Add a tag-colors property
+      metadata['tag-colors'] = story.tagColors;
+    }
+
+    // Write out the story metadata.
+    outputContents += `${JSON.stringify(metadata, undefined, 2)}`;
+
+    // Add two newlines.
+    outputContents += '\n\n';
+
+    // For each passage, append it to the output.
+    story.forEach((passage) => {
+      // For each passage, append it to the output.
+      outputContents += passage.toString();
+    });
+
+    try {
+      // Try to write
+      fs.writeFileSync(file, outputContents);
+    } catch (event) {
+      // Throw error
+      throw new Error('Error: Cannot write Twee file!');
+    }
+  }
+}