extwee 2.3.10 → 2.3.12

package/docs/install/npm.md

@@ -1,16 +0,0 @@
-# NPM
-
-While general compilation and de-compilation is possible using the CLI, more advanced usage patterns can be enabled through the API.
-
-By installing `extwee`, developers can directly access its objects, parsers, and compilation functionality.
-
-## Example
-
-```javascript
-import { Story, Passage } from 'extwee';
-
-// Create the story.
-const example = new Story( 'Example' );
-// Add a new passage.
-example.addPassage(new Passage( 'Test', 'Some Text') );
-```

package/docs/install/npx.md

@@ -1,79 +0,0 @@
-# NPX
-
-Extwee can be used via NPX (node package execution) without being added to a local project. When used this way, precede all uses with "npx".
-
-## NPX Example
-
-```bash
-npx extwee -c -i <tweeFile> -s <storyFormat> -o <Twine2HTML>
-```
-
-## Config File Usage
-
-When used via NPX, Extwee will also look for a local file, `extwee.config.json`.
-
-The configuration file supports some, but not all, possible actions using command-line arguments.
-
-### Defining `mode`
-
-The most important option is `mode`. This **MUST BE** either `compile` or `decompile`.
-
-```json
-{
-    "mode": "decompile"
-}
-```
-
-### Defining `input` and `output`
-
-To process files, the `input` and `output` properties **MUST BE** defined using either an absolute or relative path.
-
-```json
-{
-    "mode": "compile",
-    "input": "index.twee",
-    "output": "index.html"
-}
-```
-
-### Defining `story-format`
-
-If using the `"mode": "compile"` option, the `story-format` property **MUST BE** defined. This should be the name of a directory in the relative `./story-formats` directory.
-
-For example, if using Harlowe, the path would be `./story-formats/harlowe` and the key-value pair would be `"story-format": "harlowe"`.
-
-```json
-{
-    "mode": "compile",
-    "input": "index.twee",
-    "output": "index.html",
-    "story-format": "harlowe"
-}
-```
-
-#### Defining optional `story-format-version`
-
-The Story Format Archive retrieves story formats based on its version in a sub-directory structure:
-
-```file
-story-formats/
-├── harlowe/
-│   ├── 2.3.0/
-│       └── format.js
-│   ├── 2.4.0/
-│       └── format.js
-```
-
-This can be specified, such as `3.2.0`, or the default `latest`, can be used.
-
-```json
-{
-    "mode": "compile",
-    "input": "index.twee",
-    "output": "index.html",
-    "story-format": "harlowe",
-    "story-format-version": "3.2.0"
-}
-```
-
-If only the story format name is specified, and it can be found in the local `story-formats` directory, it will search for a corresponding `format.js` file.

package/docs/objects/passage.md

@@ -1,47 +0,0 @@
-# Passage
-
-The smallest unit in Twine is a *passage*.
-
-## Properties
-
-When using the Extwee API, a **Passage** object holds four properties:
-
-- name ( string ) Name of the passage.
-- text ( string ) Content of the passage.
-- tags ( array(string) ) Array of tags associated with the passage.
-- Metadata ( object ) Key-value pairs associated with the passage.
-
-### Property Example
-
-```javascript
-import { Passage } from 'extwee';
-
-// Create a single passage.
-const example = new Passage('Example', 'Some text');
-
-// Output current passage text.
-console.log( example.text );
-```
-
-## Methods
-
-Each passage is capable of producing multiple formats of its internal data:
-
-- `toTwee()`: Converts passage data into Twee 3.
-- `toJSON()`: Converts passage data into Twine 2 JSON.
-- `toTwine2HTML()`: Converts passage data into Twine 2 HTML.
-- `toTwine1HTML()`: Converts passage data into Twine 1 HTML.
-
-### Method Example
-
-```javascript
-import { Passage } from 'extwee';
-
-// Create a single passage.
-const example = new Passage('Example', 'Some text');
-
-// Convert to Twee 3.
-console.log( example.toTwee() );
-```
-
-**Note:** While each passage can create different representations of its data, each conversion is considered partial without the corresponding story metadata or story format to create the playable form.

package/docs/objects/story.md

@@ -1,69 +0,0 @@
-# Story
-
-A *story* is a collection of [passages](/guide/passage.md) with its own metadata.
-
-## Properties
-
-Depending on the incoming format or creation method, many possible properties can be populated.
-
-- name ( string ) Name of the story.
-- start ( string ) Starting passage for Twine 2 HTML or Twee 3.
-- IFID ( string ) When converting to multiple formats, a new IFID will be generated if it does not exist.
-- format ( string ) Name of the story format for Twine 2 HTML.
-- formatVersion ( string ) Semantic version of the named story format for Twine 2 HTML or Twee 3.
-- zoom ( float ) Zoom level for Twine 2 HTML or Twee 3.
-- passages ( array(Passage) ) Collection of internal passages.
-- creator ( string ) Name of story creation tool. (Defaults to "Extwee").
-- creatorVersion ( string ) Semantic version of named creation tool.
-- metadata ( object ) Key-value pairs of metadata values.
-- tagColors ( object ) Key-value pairs of tags and their named colors.
-
-## Creation Example
-
-```javascript
-import { Story } from 'extwee';
-
-// Create a story.
-const example = new Story('Example');
-
-// Show story name
-console.log ( example.name );
-```
-
-**Note:** All properties have protections. Attempting to assign the wrong type will result in an error.
-
-## Passage Methods
-
-As collections of passages, each **Story** has multiple methods for accessing and mutating its data:
-
-- `addPassage(Passage)`: Adds a new passage to the collection. (In Twine, passage names must be unique. Extwee will produce a console warning and ignore any repeating names.)
-- `removePassageByName(string)`: Looks for an removes a passage based on its name. If the passage does not exist, nothing happens.
-- `getPassagesByTags(string)`: Returns an array of any passages containing a particular tag value.
-- `getPassageByName(string)`: Returns either `null`` or the named passage.
-- `size()`: Returns the number of passages in the collection.
-
-## Passage Creation Example
-
-```javascript
-import { Story, Passage } from 'extwee';
-
-// Create the story.
-const example = new Story( 'Example' );
-// Add a new passage.
-example.addPassage(new Passage( 'Test', 'Some Text') );
-
-// Confirm size change.
-// (Should produce 1).
-console.log ( example.size() );
-```
-
-**Note:** It is not possible to directly access and act on the *passages* property. All actions must take place through available methods.
-
-Like passages, each **Story** can generate multiple formats based on its data:
-
-- `toTwee()`: Convert the story, its properties, and all its passages into Twee 3.
-- `toJSON()`: Converts the story, its properties, and all its passages into Twine 2 JSON.
-- `toTwine1HTML()`: Converts the story, its properties, and all its passages into Twine 1 HTML.
-- `toTwine2HTML()`: Converts the story, its properties, and all its passages into Twine 2 HTML.
-
-**Note:** While stories can create different representations of its data, most conversions are considered partial without the corresponding story format to create the playable form.

package/docs/objects/storyformat.md

@@ -1,27 +0,0 @@
-# Story Format
-
-For a story to be playable in Twine, it must be combined with a *story format*.
-
-In Twine 1, story formats can exist across multiple files:
-
-- `engine.js`: "engine" as included from Twine 1.
-- `header.html`: HTML "header" the Twine 1 HTML will be added into to create published file.
-- `code.js`: While technically optional, most story formats include extra code found in a `code.js` file.
-
-In Twine 2, story formats are single files generally named `format.js`. These are [JSONP files](https://en.wikipedia.org/wiki/JSONP) with JSON data of the story format included within a function call payload.
-
-## Properties
-
-When working with Twine 2 story formats, the associated `parse()` function call be used to create a **StoryFormat** object with the following properties:
-
-- name ( string ) Name of the story format.
-- version ( string ) Semantic version.
-- author ( string ) Author of the story format.
-- description ( string ) Summary of the story format.
-- image ( string ) URL of an image (ideally SVG) acting as its icon in Twine.
-- url ( string ) URL of the directory containing the `format.js` file.
-- license ( string ) License acronym and sometimes version.
-- proofing ( boolean ) (defaults to false). True if the story format is a "proofing" format.
-- source ( string ) Full HTML output of the story format including the two placeholders {{STORY_NAME}} and {{STORY_DATA}}. (The placeholders are not themselves required.)
-
-**Note:** Generally, even when using the Extwee API, it is rare to work with story formats beyond parsing them as part of Twine 1 or Twine 2 HTML compilation.

package/eslint.config.js

@@ -1,28 +0,0 @@
-import globals from "globals";
-import pluginJs from "@eslint/js";
-import jest from "eslint-plugin-jest";
-import jsdoc from 'eslint-plugin-jsdoc';
-
-export default [
-  jsdoc.configs['flat/recommended'],
-  {
-    languageOptions: { 
-        globals: {
-            ...globals.browser,
-            ...globals.node,
-            ...globals.jest
-        }
-    },
-    plugins: {
-        jest: jest,
-        jsdoc: jsdoc
-    },
-    rules: {
-      'jsdoc/require-description': 'warn',
-      'jsdoc/check-tag-names': ['error', {
-        definedTags: ['jest-environment']
-      }]
-    }
-  },
-  pluginJs.configs.recommended,
-];

package/extwee.config.json

@@ -1,6 +0,0 @@
-{
-    "mode": "decompile",
-    "input": "index.html",
-    "output": "index.twee",
-    "story-format": "harlowe"
-}

package/extwee.config.md

@@ -1,67 +0,0 @@
-# Extwee Config File Options
-
-The configuration file supports some, but not all, possible actions using command-line arguments.
-
-## Defining `mode`
-
-The most important option is `mode`. This **MUST BE** either `compile` or `decompile`.
-
-```json
-{
-    "mode": "decompile"
-}
-```
-
-## Defining `input` and `output`
-
-To process files, the `input` and `output` properties **MUST BE** defined using either an absolute or relative path.
-
-```json
-{
-    "mode": "compile",
-    "input": "index.twee",
-    "output": "index.html"
-}
-```
-
-## Defining `story-format`
-
-If using the `"mode": "compile"` option, the `story-format` property **MUST BE** defined. This should be the name of a directory in the relative `./story-formats` directory.
-
-For example, if using Harlowe, the path would be `./story-formats/harlowe` and the key-value pair would be `"story-format": "harlowe"`.
-
-```json
-{
-    "mode": "compile",
-    "input": "index.twee",
-    "output": "index.html",
-    "story-format": "harlowe"
-}
-```
-
-### Defining optional `story-format-version`
-
-The Story Format Archive retrieves story formats based on its version in a sub-directory structure:
-
-```file
-story-formats/
-├── harlowe/
-│   ├── 2.3.0/
-│       └── format.js
-│   ├── 2.4.0/
-│       └── format.js
-```
-
-This can be specified, such as `3.2.0`, or the default `latest`, can be used.
-
-```json
-{
-    "mode": "compile",
-    "input": "index.twee",
-    "output": "index.html",
-    "story-format": "harlowe",
-    "story-format-version": "3.2.0"
-}
-```
-
-If only the story format name is specified, and it can be found in the local `story-formats` directory, it will search for a corresponding `format.js` file.

package/jest.config.json

@@ -1,5 +0,0 @@
-{
-    "bail": 1,
-    "verbose": true,
-    "collectCoverage": true
-}

package/test/CLI/CLI.test.js

@@ -1,49 +0,0 @@
-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 --twine1 -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 --twine1 -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

@@ -1 +0,0 @@
-{"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

@@ -1,22 +0,0 @@
-:: 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;}