extwee 2.0.6 → 2.2.1

package/src/Twine2HTML/parse.js

@@ -0,0 +1,349 @@
+import { parse as HtmlParser } from 'node-html-parser';
+import { Story } from '../Story.js';
+import Passage from '../Passage.js';
+import { decode } from 'html-entities';
+
+/**
+ * Parse Twine 2 HTML into Story object.
+ *
+ * See: Twine 2 HTML Output Specification
+ * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md)
+ * @param {string} content - Twine 2 HTML content to parse.
+ * @returns {Story} Story
+ */
+function parse (content) {
+  // Create new story.
+  const story = new Story();
+
+  // Can only parse string values.
+  if (typeof content !== 'string') {
+    throw new TypeError('Content is not a string!');
+  }
+
+  // Set default start node.
+  let startNode = null;
+
+  // Send to node-html-parser
+  // Enable getting the content of 'script', 'style', and 'pre' elements
+  // Get back a DOM
+  const dom = new HtmlParser(
+    content,
+    {
+      lowerCaseTagName: false,
+      script: true,
+      style: true,
+      pre: true
+    });
+
+  // Pull out the `<tw-storydata>` element.
+  const storyDataElements = dom.getElementsByTagName('tw-storydata');
+
+  // Did we find any elements?
+  if (storyDataElements.length === 0) {
+    // If there is not a single `<tw-storydata>` element, this is not a Twine 2 story!
+    throw new Error('Not Twine 2 HTML content!');
+  }
+
+  // We only parse the first element found.
+  const storyData = storyDataElements[0];
+
+  /**
+   * name: (string) Required.
+   *   The name of the story.
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'name')) {
+    // Set the story name
+    story.name = storyData.attributes.name;
+  } else {
+    // Name is a required field. Warn user.
+    console.warn('Twine 2 HTML must have a name!');
+  }
+
+  /**
+   * 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).
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'ifid')) {
+    // Update story IFID.
+    story.IFID = storyData.attributes.ifid;
+  } else {
+    // Name is a required filed. Warn user.
+    console.warn('Twine 2 HTML must have an IFID!');
+  }
+
+  /**
+   * creator: (string) Optional.
+   *   The name of program used to create the file.
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'creator')) {
+    // Update story creator
+    story.creator = storyData.attributes.creator;
+  }
+
+  /**
+   * creator-version: (string) Optional.
+   *   The version of the program used to create the file.
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'creator-version')) {
+    // Update story creator version
+    story.creatorVersion = storyData.attributes['creator-version'];
+  }
+
+  /**
+   * format: (string) Optional.
+   *   The story format used to create the story.
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'format')) {
+    // Update story format
+    story.format = storyData.attributes.format;
+  }
+
+  /**
+   * format-version: (string) Optional.
+   *   The version of the story format used to create the story.
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'format-version')) {
+    // Update story format version
+    story.formatVersion = storyData.attributes['format-version'];
+  }
+
+  /**
+   * zoom: (string) Optional.
+   *   The decimal level of zoom (i.e. 1.0 is 100% and 1.2 would be 120% zoom level).
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'zoom')) {
+    // Update story zoom
+    story.zoom = Number(Number.parseFloat(storyData.attributes.zoom).toFixed(2));
+  }
+
+  /**
+   * startnode: (string) Optional.
+   *   The PID matching a `<tw-passagedata>` element whose content should be displayed first.
+   */
+  if (Object.prototype.hasOwnProperty.call(storyData.attributes, 'startnode')) {
+    // Take string value and convert to Int
+    startNode = Number.parseInt(storyData.attributes.startnode, 10);
+  } else {
+    // Throw error without start node.
+    throw new Error('Missing startnode in <tw-storydata>!');
+  }
+
+  // Pull out the `<tw-passagedata>` element.
+  const storyPassages = dom.querySelectorAll('tw-passagedata');
+
+  // Move through the passages
+  for (const passage in storyPassages) {
+    // Get the passage attributes
+    const attr = storyPassages[passage].attributes;
+    // Get the passage text
+    const text = storyPassages[passage].rawText;
+
+    /**
+     * position: (string) Optional.
+     *   Comma-separated X and Y position of the upper-left
+     *   of the passage when viewed within the Twine 2 editor.
+     */
+    // Set a default position.
+    let position = null;
+    // Does position exist?
+    if (Object.prototype.hasOwnProperty.call(attr, 'position')) {
+      // Update position.
+      position = attr.position;
+    }
+
+    /**
+     * size: (string) Optional.
+     *   Comma-separated width and height of the
+     *   passage when viewed within the Twine 2 editor.
+     */
+    // Set a default size.
+    let size = null;
+    // Does size exist?
+    if (Object.prototype.hasOwnProperty.call(attr, 'size')) {
+      // Update size.
+      size = attr.size;
+    }
+
+    /**
+     * name: (string) Required.
+     *   The name of the passage.
+     *
+     *   https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md#passages
+     */
+    // Create a default value
+    let name = null;
+    // Does name exist?
+    if (Object.prototype.hasOwnProperty.call(attr, 'name')) {
+      // Escape the name
+      name = escapeMetacharacters(attr.name);
+    } else {
+      throw new Error('Cannot parse passage data without name!');
+    }
+
+    // Create empty tag array.
+    let tags = [];
+    // Does the tags attribute exist?
+    if (Object.prototype.hasOwnProperty.call(attr, 'tags')) {
+      // Escape any tags
+      // (Attributes can, themselves, be empty strings.)
+      if (attr.tags.length > 0 && attr.tags !== '""') {
+        // Escape the tags
+        tags = escapeMetacharacters(attr.tags);
+        // Split by spaces into an array
+        tags = tags.split(' ');
+      }
+
+      // Remove any empty strings.
+      tags = tags.filter(tag => tag !== '');
+    }
+
+    // Create metadata for passage.
+    const metadata = {};
+
+    // Does position exist?
+    if (position !== null) {
+      // Add the property to metadata
+      metadata.position = position;
+    }
+
+    // Does size exist?
+    if (size !== null) {
+      // Add the property to metadata
+      metadata.size = size;
+    }
+
+    /**
+     * pid: (string) Required.
+     *   The Passage ID (PID).
+     *   (Note: This is subject to change during editing with Twine 2.)
+     *
+     *   https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md#passages
+     */
+    // Create a default PID
+    let pid = -1;
+    // Does pid exist?
+    if (Object.prototype.hasOwnProperty.call(attr, 'pid')) {
+      // Parse string into int
+      // Update PID
+      pid = Number.parseInt(attr.pid, 10);
+    } else {
+      console.warn('Passages are required to have PID. Will not add!');
+    }
+
+    // Check the current PID against startNode number.
+    if (pid === startNode) {
+      // These match.
+      // Save the passage name.
+      story.start = name;
+    }
+
+    // If passage is missing name and PID (required attributes),
+    //  they are not added.
+    if (name !== null && pid !== -1) {
+      // Add a new Passage into an array
+      story.addPassage(
+        new Passage(
+          decode(name),
+          decode(text),
+          tags.map(tag => decode(tag)),
+          metadata
+        )
+      );
+    }
+  }
+
+  // There was an invalid startNode.
+  if (story.start === '') {
+    throw new Error('startNode does not exist within passages!');
+  }
+
+  // Look for the style element
+  const styleElement = dom.querySelector('#twine-user-stylesheet');
+
+  // Does the style element exist?
+  if (styleElement !== null) {
+    // Check if there is any content.
+    if (styleElement.rawText.length > 0) {
+      // Update stylesheet passage
+      story.addPassage(new Passage(
+        'UserStylesheet',
+        styleElement.rawText,
+        ['stylesheet'])
+      );
+    }
+  }
+
+  // Look for the script element
+  const scriptElement = dom.querySelector('#twine-user-script');
+
+  // Does the script element exist?
+  if (scriptElement !== null) {
+    // Check if there is any content.
+    if (scriptElement.rawText.length > 0) {
+      story.addPassage(new Passage(
+        'UserScript',
+        scriptElement.rawText,
+        ['script'])
+      );
+    }
+  }
+
+  // Look for all <tw-tag> elements.
+  const twTags = dom.querySelectorAll('tw-tag');
+
+  // Parse through the entries.
+  twTags.forEach((tags) => {
+    // Parse each tag element
+    const attributes = tags.attributes;
+
+    // Create default value for name
+    let name = '';
+
+    // Create default value for color
+    let color = '';
+
+    // Check for name
+    if (Object.prototype.hasOwnProperty.call(attributes, 'name')) {
+      name = attributes.name;
+    }
+
+    // Check for color
+    if (Object.prototype.hasOwnProperty.call(attributes, 'color')) {
+      color = attributes.color;
+    }
+
+    // If both are not empty strings, use them.
+    if (name !== '' && color !== '') {
+      // Add name and color to the object
+      story.tagColors[name] = color;
+    }
+  });
+
+  // Return the parsed story.
+  return story;
+}
+
+/**
+ * Try to escape Twine 2 meta-characters.
+ * @param {string} result - Text to parse.
+ * @returns {string} Escaped characters.
+ */
+function escapeMetacharacters (result) {
+  // Replace any single backslash, \, with two of them, \\.
+  result = result.replace(/\\/g, '\\');
+  // Double-escape escaped {
+  result = result.replace(/\\\{/g, '\\\\{');
+  // Double-escape escaped }
+  result = result.replace(/\\\}/g, '\\\\}');
+  // Double-escape escaped [
+  result = result.replace(/\\\[/g, '\\\\[');
+  // Double-escape escaped ]
+  result = result.replace(/\\\]/g, '\\\\]');
+
+  return result;
+}
+
+export { parse, escapeMetacharacters };
+export default parse;

package/src/extwee.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+/**
+ * @file CLI for Extwee
+ * @author Dan Cox
+ */
+
+// Import functions we need.
+import {
+  parseTwine2HTML,
+  parseTwee,
+  parseStoryFormat,
+  parseTwine1HTML,
+  compileTwine2HTML,
+  compileTwine1HTML
+} from '../index.js';
+
+// Import fs.
+import { readFileSync, writeFileSync, statSync } from 'node:fs';
+
+// Import Commander.
+import { Command, InvalidArgumentError } from 'commander';
+
+// Create a new Command.
+const program = new Command();
+
+/*
+ * 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.
+ */
+const isFile = (path) => {
+  // set default.
+  let result = false;
+
+  try {
+    // Attempt tp get stats.
+    const stats = statSync(path);
+
+    // Return if path is a file.
+    result = stats.isFile();
+  } catch (e) {
+    // There was an error, so return false.
+    result = false;
+  }
+
+  // Return either the default (false) or the result (true).
+  return result;
+};
+
+program
+  .name('extwee')
+  .description('CLI for Extwee')
+  .version('2.2.0', '-v, -V, --version', 'Output the current version')
+  .option('-c, --compile', 'Compile input into output')
+  .option('-d, --decompile', 'De-compile input into output')
+  .option('-t1, --twine1', 'Enable Twine 1 processing')
+  .option('-name <storyFormatName>', 'Name of the Twine 1 story format (needed for `code.js` inclusion)')
+  .option('-codejs <codeJSFile>', 'Twine 1 code.js file for use with Twine 1 HTML', (value) => {
+    // Does the input file exist?
+    if (isFile(value) === false) {
+      // We cannot do anything without valid input.
+      throw new InvalidArgumentError(`Twine 1 code.js ${value} does not exist.`);
+    }
+
+    return value;
+  })
+  .option('-engine <engineFile>', 'Twine 1 engine.js file for use with Twine 1 HTML', (value) => {
+    // Does the input file exist?
+    if (isFile(value) === false) {
+      // We cannot do anything without valid input.
+      throw new InvalidArgumentError(`Twine 1 engine.js ${value} does not exist.`);
+    }
+
+    return value;
+  })
+  .option('-header <headerFile>', 'Twine 1 header.html file for use with Twine 1 HTML', (value) => {
+    // Does the input file exist?
+    if (isFile(value) === false) {
+      // We cannot do anything without valid input.
+      throw new InvalidArgumentError(`Twine 1 header.html ${value} does not exist.`);
+    }
+
+    return value;
+  })
+  .option('-s <storyformat>, --storyformat <storyformat>', 'Path to story format file for Twine 2', (value) => {
+    // Does the input file exist?
+    if (isFile(value) === false) {
+      // We cannot do anything without valid input.
+      throw new InvalidArgumentError(`Story format ${value} does not exist.`);
+    }
+
+    return value;
+  })
+  .option('-i <inputFile>, --input <inputFile>', 'Path to input file', (value) => {
+    // Does the input file exist?
+    if (isFile(value) === false) {
+      // We cannot do anything without valid input.
+      throw new InvalidArgumentError(`Input file ${value} does not exist.`);
+    }
+
+    return value;
+  })
+  .option('-o <outputFile>, --output <outputFile>', 'Path to output file');
+
+// Parse the passed arguments.
+program.parse(process.argv);
+
+// Create object of passed arguments parsed by Commander.
+const options = program.opts();
+
+/*
+ * Prepare some (soon to be) global variables.
+ */
+// Check if Twine 1 is enabled.
+const isTwine1Mode = (options.twine1 === true);
+
+// Check if Twine 2 is enabled.
+const isTwine2Mode = (isTwine1Mode === false);
+
+// Check if de-compile mode is enabled.
+const isDecompileMode = (options.decompile === true);
+
+// Check if compile mode is enabled.
+const isCompileMode = (options.compile === true);
+
+// De-compile Twine 2 HTML into Twee 3 branch.
+// If -d is passed, -i and -o are required.
+if (isTwine2Mode === true && isDecompileMode === true) {
+  // Read the input HTML file.
+  const inputHTML = readFileSync(options.i, 'utf-8');
+
+  // Parse the input HTML file into Story object.
+  const storyObject = parseTwine2HTML(inputHTML);
+
+  // Write the output file from Story as Twee 3.
+  writeFileSync(options.o, storyObject.toTwee());
+
+  // Exit the process.
+  process.exit();
+}
+
+// Compile Twee 3 into Twine 2 HTML branch.
+// If -c is passed, -i, -o, and -s are required.
+if (isTwine2Mode === true && isCompileMode === true) {
+  // Read the input file.
+  const inputTwee = readFileSync(options.i, 'utf-8');
+
+  // Parse the input file.
+  const story = parseTwee(inputTwee);
+
+  // Read the story format file.
+  const inputStoryFormat = readFileSync(options.s, 'utf-8');
+
+  // Parse the story format file.
+  const parsedStoryFormat = parseStoryFormat(inputStoryFormat);
+
+  // Compile the story.
+  const Twine2HTML = compileTwine2HTML(story, parsedStoryFormat);
+
+  // Write the output file.
+  writeFileSync(options.o, Twine2HTML);
+
+  // Exit the process.
+  process.exit();
+}
+
+// Compile Twee 3 into Twine 1 HTML branch.
+// Twine 1 compilation is complicated, so we have to check for all the required options.
+// * options.engine (from Twine 1 itself)
+// * options.header (from Twine 1 story format)
+// * options.name (from Twine 1 story format)
+// * options.codejs (from Twine 1 story format)
+if (isTwine1Mode === true && isCompileMode === true) {
+  // Read the input file.
+  const inputTwee = readFileSync(options.i, 'utf-8');
+
+  // Parse the input file.
+  const story = parseTwee(inputTwee);
+
+  // Does the engine file exist?
+  const Twine1HTML = compileTwine1HTML(story, options.engine, options.header, options.name, options.codejs);
+
+  // Write the output file.
+  writeFileSync(options.o, Twine1HTML);
+
+  // Exit the process.
+  process.exit();
+}
+
+// De-compile Twine 1 HTML into Twee 3 branch.
+if (isTwine1Mode === true && isDecompileMode === true) {
+  // Read the input HTML file.
+  const inputHTML = readFileSync(options.i, 'utf-8');
+
+  // Parse the input HTML file into Story object.
+  const storyObject = parseTwine1HTML(inputHTML);
+
+  // Write the output file from Story as Twee 3.
+  writeFileSync(options.o, storyObject.toTwee());
+
+  // Exit the process.
+  process.exit();
+}

package/test/CLI/CLI.test.js

@@ -0,0 +1,49 @@
+import shell from 'shelljs';
+
+// We could get this from process,
+//  but since we are using shelljs,
+//  we ask for the pwd() instead of cwd().
+const currentPath = shell.pwd().stdout;
+const testFilePath = currentPath + '/test/CLI/files';
+
+describe('CLI', () => {
+  // Remove the test files, if they exist.
+  beforeAll(() => {
+    // Test for files beginning with "test." in the output directory.
+    if (shell.ls('-A', `${testFilePath}/output/`).length > 0) {
+      // Remove the files.
+      shell.rm(`${testFilePath}/output/*`);
+    }
+  });
+
+  it('Twine 2 - de-compile: Twine 2 HTML into Twee 3', () => {
+    shell.exec(`node ${currentPath}/src/extwee.js -d -i ${testFilePath}/input.html -o ${testFilePath}/output/test.twee`);
+    expect(shell.test('-e', `${testFilePath}/output/test.twee`)).toBe(true);
+  });
+
+  it('Twine 2 - compile: Twee 3 + StoryFormat into Twine 2 HTML', () => {
+    shell.exec(`node ${currentPath}/src/extwee.js -c -i ${testFilePath}/example6.twee -s ${testFilePath}/harlowe.js -o ${testFilePath}/output/test2.html`);
+    expect(shell.test('-e', `${testFilePath}/output/test2.html`)).toBe(true);
+  });
+
+  it('Twine 1 - compile: Twee 3 + Twine 1 engine.js + Twine 1 code.js + Twine 1 header.html', () => {
+    shell.exec(`node ${currentPath}/src/extwee.js -t1 -c -i ${testFilePath}/example6.twee -o ${testFilePath}/output/test3.html -codejs ${testFilePath}/twine1/code.js -engine ${testFilePath}/twine1/engine.js -header ${testFilePath}/twine1/header.html -name Test`);
+    expect(shell.test('-e', `${testFilePath}/output/test3.html`)).toBe(true);
+  });
+
+  it('Twine 1 - de-compile: Twine 1 HTML into Twee 3', () => {
+    shell.exec(`node ${currentPath}/src/extwee.js -t1 -d -i ${testFilePath}/twine1Test.html -o ${testFilePath}/output/test.twee`);
+    expect(shell.test('-e', `${testFilePath}/output/test.twee`)).toBe(true);
+  });
+
+  // Remove the test files, if they exist.
+  afterAll(() => {
+    // Test for files in the output directory.
+    if (shell.ls('-A', `${testFilePath}/output/`).length > 0) {
+      // Remove the files.
+      shell.rm(`${testFilePath}/output/*`);
+    }
+    // Create one file to prevent git from ignoring the folder.
+    shell.touch(`${testFilePath}/output/test.twee`);
+  });
+});

package/test/CLI/files/example.json

@@ -0,0 +1 @@
+{"name":"Test","tagColors":{"r":"red"},"ifid":"dd","start":"Start","formatVersion":"1.0","metadata":{"some":"thing"},"format":"Snowman","creator":"extwee","creatorVersion":"2.2.0","zoom":1,"passages":[{"name":"Start","tags":["tag1"],"metadata":{"s":"e"},"text":"Word"}]}

package/test/CLI/files/example6.twee

@@ -0,0 +1,22 @@
+:: StoryData
+{
+   "ifid": "D674C58C-DEFA-4F70-B7A2-27742230C0FC",
+   "format": "SugarCube",
+   "format-version": "2.28.2",
+   "start": "Start",
+   "tag-colors": {
+     "bar": "green",
+     "foo": "red",
+     "qaz": "blue"
+   },
+   "zoom": 0.25
+}
+
+:: StoryTitle
+twineExample
+
+:: Start [tag tags] {"position": "200,200", "size": "100,100"}
+Content
+
+:: Style1 [stylesheet]
+body {background-color: green;}