extwee 2.2.6 → 2.3.1

package/src/CLI/ProcessConfig/loadStoryFormat.js

@@ -0,0 +1,102 @@
+import { isDirectory } from "../isDirectory.js";
+import { isFile } from "../isFile.js";
+import { readDirectories } from "./readDirectories.js";
+import { readFileSync } from "node:fs";
+
+/**
+ * Load the story format from the story-formats directory.
+ * @function loadStoryFormat
+ * @description This function loads the story format from the story-formats directory.
+ * It checks if the story-formats directory exists, if the named story format exists,
+ * if the version directory exists, and if the format.js file exists.
+ * If any of these checks fail, the function will exit the process with an error message.
+ * If all checks pass, the function will return the contents of the format.js file.
+ * @param {string} storyFormatName - The name of the story format.
+ * @param {string} storyFormatVersion - The version of the story format.
+ * @returns {string} - The contents of the format.js file.
+ * @throws {Error} - If the story-formats directory does not exist, if the named story format does not exist,
+ * if the version directory does not exist, or if the format.js file does not exist.
+ * @example
+ * // Load the story format from the story-formats directory.
+ * const storyFormat = loadStoryFormat('Harlowe', '3.2.0');
+ * console.log(storyFormat);
+ * // Output: The contents of the format.js file.
+ */
+export function loadStoryFormat(storyFormatName, storyFormatVersion) {
+    // If the story-formats directory does not exist, throw error.
+    if (isDirectory('story-formats') === false) {
+        throw new Error(`Error: story-formats directory does not exist. Consider running 'npx sfa-get' to download the latest story formats.`);
+    }
+
+    // Does the named story format exist in the story-formats directory?
+    const isStoryFormatDir = isDirectory(`story-formats/${storyFormatName}`);
+    
+    // If the story format directory does not exist, throw error.
+    if (isStoryFormatDir === false) {
+        throw new Error(`Error: story format ${storyFormatName} does not exist in the story-formats directory.`);
+    }
+
+    let filepath = `story-formats/${storyFormatName}/format.js`;
+
+    // If the story format version is 'latest', check if the format.js file exists.
+    // If the format.js file does not exist, check if there are version directories.
+    // If there are version directories, get the latest version and set the filepath to that version directory and format.js file.
+    // If the format.js file exists, return its contents.
+
+    // Check if storyFormatVersion is "latest"
+    if (storyFormatVersion === 'latest' && isFile(filepath) === false) {
+        // Read the directories in the story format directory.
+        // The directories are expected to be version directories.
+        let directories = readDirectories(`story-formats/${storyFormatName}`);
+
+        console.log("!!! directories", directories);
+
+        // Check if there are any version directories.
+        if (directories.length === 0) {
+            // If there are no version directories, throw error.
+            throw new Error(`Error: story format ${storyFormatName} does not have any version directories.`);
+        }
+            
+        // Sort the directories in descending order.
+        directories.sort((a, b) => {
+            return b.localeCompare(a, undefined, { numeric: true });
+        });
+
+        // Get the latest version directory.
+        // The latest version is the last directory in the sorted list.
+        const latestVersion = directories[0];
+        
+        // Set the filepath to the latest version directory.
+        filepath = `story-formats/${storyFormatName}/${latestVersion}/format.js`;
+
+        // Is there a 'format.js' file in the version directory?
+        let isFormatFile = isFile(filepath);
+
+        // If the format.js file does not exist, exit the process.
+        if (isFormatFile === false) {
+            throw new Error(`Error: story format ${storyFormatName} version ${storyFormatVersion} does not have a format.js file.`);
+        }
+    }
+
+    // If the story format version is not 'latest', check if version directories exists.
+    if(storyFormatVersion !== 'latest') {
+        // Does the named story format have a version directory?
+        const isVersionDir = isDirectory(`story-formats/${storyFormatName}/${storyFormatVersion}`);
+        
+        // If the version directory does not exist, throw error.
+        if (isVersionDir === false) {
+            throw new Error(`Error: story format ${storyFormatName} version ${storyFormatVersion} does not exist in the story-formats directory.`);
+        }
+
+        // Set an initial path based on the version.
+        filepath = `story-formats/${storyFormatName}/${storyFormatVersion}/format.js`;
+        
+        // If the format.js file does not exist, throw error.
+        if (isFile(filepath) === false) {
+            throw new Error(`Error: story format ${storyFormatName} version ${storyFormatVersion} does not have a format.js file.`);
+        }
+    }
+
+    // If the format.js file exists, read and return its contents.
+    return readFileSync(filepath, 'utf-8');
+}

package/src/CLI/ProcessConfig/readDirectories.js

@@ -0,0 +1,46 @@
+import { readdirSync } from 'node:fs';
+import { isDirectory } from '../isDirectory.js';
+
+/**
+ * Read the contents of a directory and returns all directories.
+ * @function readDirectories
+ * @description This function reads the contents of a directory and returns a list of directories.
+ * @param {string} directory - The path to the directory to read.
+ * @returns {Array<string>} - An array of directories in the directory.
+ * @throws {Error} - If the directory does not exist or if there is an error reading the directory.
+ */
+export function readDirectories(directory) {
+
+    // Create default response.
+    let results = [];
+
+    // Check if the directory exists.
+    const isDir = isDirectory(directory);
+    // If the directory does not exist, return an empty array
+    //  and log an error message.
+    if (isDir == false) {
+        console.error(`Error: Directory ${directory} does not exist.`);
+    }
+
+    // Read the directory and return the list of files.
+    try {
+        results = readdirSync(directory);
+    } catch (error) {
+        console.error(`Error reading directory ${directory}:`, error);
+        results = [];
+    }
+
+    // Check if results is an array.
+    // This should not happen, but for some reason it can.
+    if (!Array.isArray(results)) {
+        results = [];
+    }
+
+    // Filter the list to only include directories.
+    const directoriesOnly = results.filter((item) => {
+        return isDirectory(`${directory}/${item}`);
+    });
+
+    // Return the list of directories.
+    return directoriesOnly;
+}

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.6';
+const creatorVersion = '2.3.1';
 
 /**
  * Story class.
@@ -22,6 +24,8 @@ const creatorVersion = '2.2.6';
  * @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;