extwee 2.2.5 → 2.3.0

package/src/CLI/ProcessConfig.js

@@ -0,0 +1,175 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { isFile } from './isFile.js';
+import {
+  parseTwine2HTML,
+  parseTwee,
+  parseStoryFormat,
+  parseTwine1HTML,
+  compileTwine2HTML
+} from '../../index.js';
+import { loadStoryFormat } from './ProcessConfig/loadStoryFormat.js';
+
+// Look for the config file in the current directory.
+const configFile = 'extwee.config.json';
+
+/**
+ * Check if the config file exists.
+ * @function ConfigFilePresent
+ * @description This function checks if the config file exists in the current directory.
+ * If the config file does not exist, the function will return false.
+ * If the config file exists, the function will return true.
+ * The config file is used to store configuration options for the Extwee CLI.
+ * @returns {boolean} - true if the config file exists, false otherwise.
+ */
+export const ConfigFilePresent = () => {
+    // Check if the config file exists.
+    return isFile(configFile);
+}
+
+/**
+ * Processes the config file, if present.
+ * @function ConfigFileProcessing
+ * @description This function processes the config file.
+ * It checks if the config file exists and if it does, it reads the config file.
+ * If the config file does not exist, the function will exit the process with an error message.
+ * The config file is used to store configuration options for the Extwee CLI.
+ * @returns {void}
+ * @throws {Error} - If the config file does not exist or if there is an error parsing the config file.
+ */
+export function ConfigFileProcessing() {
+  // Check if the config file exists.
+  const configFileExists = isFile(configFile);
+
+  // If the config file does not exist, exit the process.
+  if (configFileExists === false) {
+    console.error(`Error: ${configFile} does not exist.`);
+    // Exit the process.
+    process.exit(1);
+  }
+
+  // If the config file exists, read it.
+  let configFileContents = {};
+  // If the config file exists and no command-line arguments are passed, read the config file.
+  
+  // Read the config file.
+  const configFileData = readFileSync(configFile, 'utf-8');
+
+  // Parse the config file.
+  try {
+      configFileContents = JSON.parse(configFileData);
+      console.log(`Using config file: ${configFile}`, configFileContents);
+  } catch (e) {
+      // There was an error parsing the config file.
+      console.error(`Error parsing ${configFile}: ${e}`);
+      // Exit the process.
+      process.exit(1);
+  }
+
+  // First, we need to know the mode (compile or decompile).
+
+  // Does the config file the "mode" property?
+  if (configFileContents.mode === undefined) {
+    // The config file does not have a "mode" property.
+    console.error(`Error: ${configFile} does not have a "mode" property.`);
+    // Exit the process.
+    process.exit(1);
+  }
+
+  // Check if the mode is valid.
+  if (configFileContents.mode !== 'compile' && configFileContents.mode !== 'decompile') {
+    // The mode is not valid.
+    console.error(`Error: ${configFile} has an invalid "mode" property. Must be "compile" or "decompile".`);
+    // Exit the process.
+    process.exit(1);
+  }
+
+  // Check if the "input" property is present.
+  if (configFileContents.input === undefined) {
+    // The config file does not have an "input" property.
+    console.error(`Error: ${configFile} does not have an "input" property.`);
+    // Exit the process.
+    process.exit(1);
+  }
+
+  // Check if the "output" property is present.
+  if (configFileContents.output === undefined) {
+    // The config file does not have an "input" property.
+    console.error(`Error: ${configFile} does not have an "output" property.`);
+    // Exit the process.
+    process.exit(1);
+  }
+
+  // Check if de-compile mode is enabled.
+  const isDecompileMode = (configFileContents.mode === "decompile");
+
+  // Check if compile mode is enabled.
+  const isCompileMode = (configFileContents.mode === "compile");
+
+  // Check if Twine 1 is enabled.
+  const isTwine1Mode = (configFileContents.twine1Project === true);
+
+  // Check if story-format-version is present.
+  if (configFileContents.storyFormatVersion === undefined) {
+    // If not present, assume "latest" version.
+    configFileContents.storyFormatVersion = 'latest';
+  }
+
+  // Check if Twine 2 is enabled.
+  // By default, Twine 2 is enabled and only disabled if Twine 1 is enabled.
+  // This is because Twine 2 is the default mode for Extwee.
+  const isTwine2Mode = (isTwine1Mode === false ? true : false);
+
+  // De-compile Twine 2 HTML into Twee 3 branch.
+  if (isTwine2Mode === true && isDecompileMode === true) {
+      // Read the input HTML file.
+      const inputHTML = readFileSync(configFileContents.input, 'utf-8');
+  
+      // Parse the input HTML file into Story object.
+      const storyObject = parseTwine2HTML(inputHTML);
+  
+      // Write the output file from Story as Twee 3.
+      writeFileSync(configFileContents.output, storyObject.toTwee());
+  
+      // Exit the process.
+      return;
+    }
+  
+  // Compile Twee 3 into Twine 2 HTML branch.
+  if (isTwine2Mode === true && isCompileMode === true) {
+    // Read the input file.
+    const inputTwee = readFileSync(configFileContents.input, 'utf-8');
+
+    // Parse the input file.
+    const story = parseTwee(inputTwee);
+
+    // Read the story format file.
+    const inputStoryFormat = loadStoryFormat(configFileContents.storyFormatName, configFileContents.storyFormatVersion);
+
+    // Parse the story format file.
+    const parsedStoryFormat = parseStoryFormat(inputStoryFormat);
+
+    // Compile the story.
+    const Twine2HTML = compileTwine2HTML(story, parsedStoryFormat);
+
+    // Write the output file.
+    writeFileSync(configFileContents.output, Twine2HTML);
+
+    // Exit the process.
+    return;
+  }
+
+  // De-compile Twine 1 HTML into Twee 3 branch.
+  if (isTwine1Mode === true && isDecompileMode === true) {
+    // Read the input HTML file.
+    const inputHTML = readFileSync(configFileContents.input, 'utf-8');
+
+    // Parse the input HTML file into Story object.
+    const storyObject = parseTwine1HTML(inputHTML);
+
+    // Write the output file from Story as Twee 3.
+    writeFileSync(configFileContents.output, storyObject.toTwee());
+
+    return;
+  }
+
+}

package/src/CLI/isDirectory.js

@@ -0,0 +1,27 @@
+import { statSync } from 'node:fs';
+
+/*
+ * Check if a passed option is a valid directory.
+ * @function isDirectory
+ * @description Check if a directory exists.
+ * @param {string} path - Path to directory.
+ * @returns {boolean} True if directory exists, false if not.
+ */
+export const isDirectory = (path) => {
+  // set default.
+  let result = false;
+
+  try {
+    // Attempt t0 get stats.
+    const stats = statSync(path);
+
+    // Return if path is a directory.
+    result = stats.isDirectory();
+  } catch (e) {
+    // If there was an error, log it.
+    console.error(`Error: ${e}`);
+  }
+
+  // Return either the default (false) or the result (true).
+  return result;
+};

package/src/CLI/isFile.js

@@ -0,0 +1,28 @@
+// Import fs.
+import { statSync } from 'node:fs';
+
+/*
+ * Check if a passed option is a valid file.
+ * @function isFile
+ * @description Check if a file exists.
+ * @param {string} path - Path to file.
+ * @returns {boolean} True if file exists, false if not.
+ */
+export const isFile = (path) => {
+  // set default.
+  let result = false;
+
+  try {
+    // Attempt t0 get stats.
+    const stats = statSync(path);
+
+    // Return if path is a file.
+    result = stats.isFile();
+  } catch (e) {
+    // If there was an error, log it.
+    console.error(`Error: ${e}`);
+  }
+
+  // Return either the default (false) or the result (true).
+  return result;
+};

package/src/Config/parser.js

@@ -12,8 +12,11 @@ export function parser(obj) {
     // Extracted results.
     let results = {
         StoryFormat: null,
-        StoryTitle: null,
-        StoryVersion: null
+        Input: null,
+        Output: null,
+        Mode: null,
+        Twine1Project: false,
+        StoryFormatVersion: null
     };
     
     // Does the object contain 'StoryFormat'?
@@ -21,14 +24,33 @@ export function parser(obj) {
         results.StoryFormat = obj['story-format'];
     }
 
-    // Does the object contain 'StoryTitle'?
-    if (Object.hasOwnProperty.call(obj, 'story-title')) {
-        results.StoryTitle = obj['story-title'];
+    // Does the object contain 'StoryFormatVersion'?
+    if (Object.hasOwnProperty.call(obj, 'story-format-version')) {
+        results.StoryFormatVersion = obj['story-format-version'];
+    } else {
+        results.StoryFormatVersion = "latest";
     }
 
-    // Does the object contain 'StoryVersion'?
-    if (Object.hasOwnProperty.call(obj, 'story-version')) {
-        results.StoryVersion = obj['story-version'];
+    // Does the object contain 'mode'?
+    if (Object.hasOwnProperty.call(obj, 'mode')) {
+        results.Mode = obj['mode'];
+    }
+
+    // Does the object contain 'input'?
+    if (Object.hasOwnProperty.call(obj, 'input')) {
+        results.Input = obj['input'];
+    }
+
+    // Does the object contain 'output'?
+    if (Object.hasOwnProperty.call(obj, 'output')) {
+        results.Output = obj['output'];
+    }
+
+    // Does the object contain 'twine1-project'?
+    if (Object.hasOwnProperty.call(obj, 'twine1-project')) {
+        results.Twine1Project = obj['twine1-project'];
+    } else {
+        results.Twine1Project = false;
     }
 
     // Return the extracted results.

package/src/Passage.js

@@ -190,8 +190,23 @@ export default class Passage {
       content += ` ${JSON.stringify(this.metadata)}`;
     }
 
-    // Add newline, text, and two newlines.
-    content += `\n${this.text}\n\n`;
+    // Split the text into lines.
+    const lines = this.text.split('\n');
+
+    // For each line, check if it begins with a double-colon.
+    for (let i = 0; i < lines.length; i++) {
+      // Check if the line begins with a double-colon.
+      if (lines[i].startsWith('::')) {
+        // Escape the double-colon.
+        lines[i] = `\\${lines[i]}`;
+      }
+    }
+
+    // Rejoin the lines.
+    const output = lines.join('\n');
+
+    // Add newline and text.
+    content += `\n${output}\n\n`;
 
     // Return string.
     return content;

package/src/Story.js

@@ -2,10 +2,12 @@ import Passage from './Passage.js';
 import { generate as generateIFID } from './IFID/generate.js';
 import { encode } from 'html-entities';
 
+// Set the creator name.
+// This is used to identify the program that created the story.
 const creatorName = 'extwee';
 
 // Set the creator version.
-const creatorVersion = '2.2.5';
+const creatorVersion = '2.3.0';
 
 /**
  * Story class.
@@ -22,6 +24,8 @@ const creatorVersion = '2.2.5';
  * @property {string} creatorVersion - Version used to create Story.
  * @property {object} metadata - Metadata of Story.
  * @property {object} tagColors - Tag Colors
+ * @property {string} storyJavaScript - Story JavaScript
+ * @property {string} storyStylesheet - Story Stylesheet
  * @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.
@@ -107,6 +111,18 @@ class Story {
    */
   #_tagColors = {};
 
+  /**
+   * Story JavaScript
+   * @private
+   */
+  #_storyJavaScript = '';
+
+  /**
+   * Story Stylesheet
+   * @private
+   */
+  #_storyStylesheet = '';
+
   /**
    * Creates a story.
    * @param {string} name - Name of the story.
@@ -322,6 +338,45 @@ class Story {
     }
   }
 
+  /**
+   * Story stylesheet data can be set as a passage, property value, or both.
+   * @returns {string} storyStylesheet
+   */
+  get storyStylesheet () {
+    return this.#_storyStylesheet;
+  }
+
+  /**
+   * @param {string} s - Replacement story stylesheet
+   */
+  set storyStylesheet (s) {
+    if (typeof s === 'string') {
+      this.#_storyStylesheet = s;
+    } else {
+      throw new Error('Story stylesheet must be a string!');
+    }
+  }
+
+  /** 
+   * Get story JavaScript.
+   * @returns {string} storyJavaScript
+   */
+  get storyJavaScript () {
+    return this.#_storyJavaScript;
+  }
+
+  /**
+   * Set story JavaScript.
+   * @param {string} s - Replacement story JavaScript
+   */
+  set storyJavaScript (s) {
+    if (typeof s === 'string') {
+      this.#_storyJavaScript = s;
+    } else {
+      throw new Error('Story JavaScript must be a string!');
+    }
+  }
+
   /**
    * Add a passage to the story.
    * Passing `StoryData` will override story metadata and `StoryTitle` will override story name.
@@ -484,6 +539,8 @@ class Story {
       creator: this.creator,
       creatorVersion: this.creatorVersion,
       zoom: this.zoom,
+      style: this.storyStylesheet,
+      script: this.storyJavaScript,
       passages: []
     };
 
@@ -595,6 +652,16 @@ class Story {
     // Add two newlines.
     outputContents += '\n\n';
 
+    // Write out the story stylesheet, if any.
+    if (this.#_storyStylesheet.length > 0) {
+      outputContents += ':: StoryStylesheet [stylesheet]\n' + this.#_storyStylesheet + '\n\n';
+    }
+
+    // Write out the story JavaScript, if any.
+    if (this.#_storyJavaScript.length > 0) {
+      outputContents += ':: StoryJavaScript [script]\n' + this.#_storyJavaScript + '\n\n';
+    }
+
     // For each passage, append it to the output.
     this.passages.forEach((passage) => {
       outputContents += passage.toTwee();
@@ -620,6 +687,10 @@ class Story {
    * - `format`: (string) Optional. The format of the story.
    * - `format-version`: (string) Optional. The version of the format of the story.
    * 
+   * Because story stylesheet data can be represented as a passage, property value, or both, all approaches are encoded.
+   * 
+   * Because story JavaScript can be represented as a passage, property value, or both, all approaches are encoded.
+   * 
    * @method toTwine2HTML
    * @returns {string} Twine 2 HTML string
    */
@@ -728,6 +799,9 @@ class Story {
     // Add the default attributes.
     storyData += ' options hidden>\n';
 
+    // We may have passages with tags of 'stylesheet', story stylesheet data, both, or none.
+
+    // Step 1: Add all passages with tag of 'stylesheet' to the stylesheet element.
     // Filter out passages with tag of 'stylesheet'.
     const stylesheetPassages = passages.filter((passage) => passage.tags.includes('stylesheet'));
 
@@ -749,6 +823,16 @@ class Story {
       storyData += '</style>\n';
     }
 
+    // Step 2: Check if the internal stylesheet data is empty.
+    // If it is not empty, add it to the stylesheet element.
+    if (this.#_storyStylesheet.length > 0) {
+      // Add the internal stylesheet.
+      storyData += `\t<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">${this.#_storyStylesheet}</style>\n`;
+    }
+
+    // We may have passages with tags of 'script', story JavaScript data, both, or none.
+
+    // Step 1: Add all passages with tag of 'script' to the script element.
     // Filter out passages with tag of 'script'.
     const scriptPassages = passages.filter((passage) => passage.tags.includes('script'));
 
@@ -770,6 +854,13 @@ class Story {
       storyData += '</script>\n';
     }
 
+    // Step 2: Check if the internal JavaScript data is empty.
+    // If it is not empty, add it to the script element.
+    if (this.#_storyJavaScript.length > 0) {
+      // Add the internal JavaScript.
+      storyData += `\t<script role="script" id="twine-user-script" type="text/twine-javascript">${this.#_storyJavaScript}</script>\n`;
+    }
+
     // Reset the PID counter.
     PIDcounter = 1;
 
@@ -781,6 +872,15 @@ class Story {
       PIDcounter++;
     });
 
+    // Generate <tw-tag> elements for each tag, if any.
+    const tagList = Object.keys(this.tagColors);
+
+    // For each tag, generate a <tw-tag> element.
+    tagList.forEach((tag) => {
+      // Add the <tw-tag> element.
+      storyData += `\t<tw-tag name="${tag}" color="${this.tagColors[tag]}"></tw-tag>\n`;
+    });
+
     // Close the HTML element.
     storyData += '</tw-storydata>';
 

package/src/StoryFormat/compile.js

@@ -0,0 +1,19 @@
+import StoryFormat from '../StoryFormat.js';
+
+/**
+ * Compiles a {@link StoryFormat} object into a JSONP string for writing to a `format.js` file.
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
+ * @param {StoryFormat} storyFormat Story format object to compile.
+ * @returns {string} JSONP string.
+ */
+function compile (storyFormat) {
+    // Test if storyFormat is a StoryFormat object.
+    if (!(storyFormat instanceof StoryFormat)) {
+        throw new TypeError('Error: Incoming object is not a storyFormat object');
+    }
+
+    // Create a JSONP string wrapped with the function window.StoryFormat.
+    return `window.storyFormat(${JSON.stringify(storyFormat)})`;
+}
+
+export { compile };

package/src/StoryFormat.js

@@ -1,3 +1,5 @@
+import { valid } from 'semver';
+
 /**
  * StoryFormat representing a Twine 2 story format.
  * 
@@ -85,6 +87,19 @@ export default class StoryFormat {
    */
   #_source = '';
 
+  // Constructor with all parameters.
+  constructor(name = 'Untitled Story Format', version = '', description = '', author = '', image = '', url = '', license = '', proofing = false, source = '') {
+    this.name = name;
+    this.version = version;
+    this.description = description;
+    this.author = author;
+    this.image = image;
+    this.url = url;
+    this.license = license;
+    this.proofing = proofing;
+    this.source = source;
+  }
+
   /**
    * Name
    * @returns {string} Name.
@@ -246,4 +261,40 @@ export default class StoryFormat {
   toString() {
     return JSON.stringify(this, null, "\t");
   }
+
+  /**
+   * Produces a JSON representation of the story format object.
+   * @method toJSON
+   * @returns {object} - A JSON representation of the story format.
+   */
+  toJSON() {
+    // name: (string) Optional. The name of the story format. (Omitting the name will lead to an Untitled Story Format.)
+    // Set a default name.
+    let name = "Untitled Story Format";
+
+    // Check if the story format is not an empty string.
+    if (this.name.length > 0) {
+      // Update the name.
+      name = this.name;
+    }
+
+    // version: (string) Required, and semantic version-style formatting (x.y.z, e.g., 1.2.1) of the version is also required.
+
+    // Check if the version is valid. If not, throw an error.
+    if (!valid(this.version)) {
+      throw new TypeError('ERROR: Version must be a valid semantic version!');
+    }
+
+    return JSON.stringify({
+      name,
+      version: this.version,
+      description: this.description,
+      author: this.author,
+      image: this.image,
+      url: this.url,
+      license: this.license,
+      proofing: this.proofing,
+      source: this.source
+    });
+  }
 }