extwee 2.2.0 → 2.2.1

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+    // Change this to match your project
+    "include": ["src/**/*"],
+    "compilerOptions": {
+      // Tells TypeScript to read JS files, as
+      // normally they are ignored as source files
+      "allowJs": true,
+      // Generate d.ts files
+      "declaration": true,
+      // This compiler run should
+      // only output d.ts files
+      "emitDeclarationOnly": true,
+      // Types should go into this directory.
+      // Removing this would place the .d.ts files
+      // next to the .js files
+      "outDir": "types",
+      // go to js file when using IDE functions like
+      // "Go to Definition" in VSCode
+      "declarationMap": true
+    }
+}

package/types/index.d.ts

@@ -0,0 +1,14 @@
+import { parse as parseTwee } from './src/Twee/parse.js';
+import { parse as parseJSON } from './src/JSON/parse.js';
+import { parse as parseTWS } from './src/TWS/parse.js';
+import { parse as parseStoryFormat } from './src/StoryFormat/parse.js';
+import { parse as parseTwine1HTML } from './src/Twine1HTML/parse.js';
+import { parse as parseTwine2HTML } from './src/Twine2HTML/parse.js';
+import { parse as parseTwine2ArchiveHTML } from './src/Twine2ArchiveHTML/parse.js';
+import { compile as compileTwine1HTML } from './src/Twine1HTML/compile.js';
+import { compile as compileTwine2HTML } from './src/Twine2HTML/compile.js';
+import { compile as compileTwine2ArchiveHTML } from './src/Twine2ArchiveHTML/compile.js';
+import Story from './src/Story.js';
+import Passage from './src/Passage.js';
+import StoryFormat from './src/StoryFormat.js';
+export { parseTwee, parseJSON, parseTWS, parseStoryFormat, parseTwine1HTML, parseTwine2HTML, parseTwine2ArchiveHTML, compileTwine1HTML, compileTwine2HTML, compileTwine2ArchiveHTML, Story, Passage, StoryFormat };

package/types/src/JSON/parse.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parse JSON representation into Story.
+ * @function parse
+ * @param {string} jsonString - JSON string to convert to Story.
+ * @returns {Story} Story object.
+ */
+export function parse(jsonString: string): Story;
+import Story from '../Story.js';

package/types/src/Passage.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A passage is the smallest unit of a Twine story.
+ */
+export default class Passage {
+    /**
+     * Create a passage.
+     * @param {string} name - Name
+     * @param {string} text - Content
+     * @param {Array} tags - Tags
+     * @param {object} metadata - Metadata
+     */
+    constructor(name?: string, text?: string, tags?: any[], metadata?: object);
+    /**
+     * @param {string} s - Name to replace
+     */
+    set name(s: string);
+    /**
+     * Name
+     * @returns {string} Name
+     */
+    get name(): string;
+    /**
+     * @param {Array} t - Replacement array
+     */
+    set tags(t: any[]);
+    /**
+     * Tags
+     * @returns {Array} Tags
+     */
+    get tags(): any[];
+    /**
+     * @param {object} m - Replacement object
+     */
+    set metadata(m: any);
+    /**
+     * Metadata
+     * @returns {object} Metadata
+     */
+    get metadata(): any;
+    /**
+     * @param {string} t - Replacement text
+     */
+    set text(t: string);
+    /**
+     * Text
+     * @returns {string} Text
+     */
+    get text(): string;
+    /**
+     * Return a Twee representation.
+     * @returns {string} String form of passage.
+     */
+    toTwee(): string;
+    /**
+     * Return JSON representation.
+     * @returns {string} JSON string.
+     */
+    toJSON(): string;
+    /**
+     * Return Twine 2 HTML representation.
+     * (Default Passage ID is 1.)
+     * @param {number} pid - Passage ID (PID) to record in HTML.
+     * @returns {string} Twine 2 HTML string.
+     */
+    toTwine2HTML(pid?: number): string;
+    /**
+     * Return Twine 1 HTML representation.
+     * @returns {string} Twine 1 HTML string.
+     */
+    toTwine1HTML(): string;
+    #private;
+}

package/types/src/Story.d.ts

@@ -0,0 +1,161 @@
+export default class Story {
+    /**
+     * Creates a story.
+     * @param {string} name - Name of the story.
+     */
+    constructor(name?: string);
+    /**
+     * @param {string} a - Replacement story name
+     */
+    set name(a: string);
+    /**
+     * Each story has a name
+     * @returns {string} Name
+     */
+    get name(): string;
+    /**
+     * @param {object} a - Replacement tag colors
+     */
+    set tagColors(a: any);
+    /**
+     * Tag Colors object (each property is a tag and its color)
+     * @returns {object} tag colors array
+     */
+    get tagColors(): any;
+    /**
+     * @param {string} i - Replacement IFID
+     */
+    set IFID(i: string);
+    /**
+     * Interactive Fiction ID (IFID) of Story
+     * @returns {string} IFID
+     */
+    get IFID(): string;
+    /**
+     * @param {string} s - Replacement start
+     */
+    set start(s: string);
+    /**
+     * Name of start passage.
+     * @returns {string} start
+     */
+    get start(): string;
+    /**
+     * @param {string} f - Replacement format version
+     */
+    set formatVersion(f: string);
+    /**
+     * Story format version of Story.
+     * @returns {string} story format version
+     */
+    get formatVersion(): string;
+    /**
+     * @param {object} o - Replacement metadata
+     */
+    set metadata(o: any);
+    /**
+     * Metadata of Story.
+     * @returns {object} metadata of story
+     */
+    get metadata(): any;
+    /**
+     * @param {string} f - Replacement format
+     */
+    set format(f: string);
+    /**
+     * Story format of Story.
+     * @returns {string} format
+     */
+    get format(): string;
+    /**
+     * @param {string} c - Creator Program of Story
+     */
+    set creator(c: string);
+    /**
+     * Program used to create Story.
+     * @returns {string} Creator Program
+     */
+    get creator(): string;
+    /**
+     * @param {string} c - Version of creator program
+     */
+    set creatorVersion(c: string);
+    /**
+     * Version used to create Story.
+     * @returns {string} Version
+     */
+    get creatorVersion(): string;
+    /**
+     * @param {number} n - Replacement zoom level
+     */
+    set zoom(n: number);
+    /**
+     * Zoom level.
+     * @returns {number} Zoom level
+     */
+    get zoom(): number;
+    /**
+     * Add a passage to the story.
+     * `StoryData` will override story metadata and `StoryTitle` will override story name.
+     * @param {Passage} p - Passage to add to Story.
+     */
+    addPassage(p: Passage): void;
+    /**
+     * Remove a passage from the story by name.
+     * @param {string} name - Passage name to remove
+     */
+    removePassageByName(name: string): void;
+    /**
+     * Find passages by tag.
+     * @param {string} t - Passage name to search for
+     * @returns {Array} Return array of passages
+     */
+    getPassagesByTag(t: string): any[];
+    /**
+     * Find passage by name.
+     * @param {string} name - Passage name to search for
+     * @returns {Passage | null} Return passage or null
+     */
+    getPassageByName(name: string): Passage | null;
+    /**
+     * Size (number of passages).
+     * @returns {number} Return number of passages
+     */
+    size(): number;
+    /**
+     * forEach-style iterator of passages in Story.
+     * @param {Function} callback - Callback function
+     */
+    forEachPassage(callback: Function): void;
+    /**
+     * Export Story as JSON representation.
+     * @returns {string} JSON string.
+     */
+    toJSON(): string;
+    /**
+     * Return Twee representation.
+     *
+     * See: Twee 3 Specification
+     * (https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
+     * @returns {string} Twee String
+     */
+    toTwee(): string;
+    /**
+     * Return Twine 2 HTML.
+     *
+     * See: Twine 2 HTML Output
+     * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md)
+     * @returns {string} Twine 2 HTML string
+     */
+    toTwine2HTML(): string;
+    /**
+     * Return Twine 1 HTML.
+     *
+     * See: Twine 1 HTML Output
+     * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md)
+     * @returns {string} Twine 1 HTML string.
+     */
+    toTwine1HTML(): string;
+    #private;
+}
+import Passage from './Passage.js';

package/types/src/StoryFormat/parse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parse a Story Format file.
+ * @param {string} contents - Content
+ * @returns {StoryFormat} StoryFormat object
+ */
+export function parse(contents: string): StoryFormat;
+import StoryFormat from '../StoryFormat.js';

package/types/src/StoryFormat.d.ts

@@ -0,0 +1,97 @@
+export default class StoryFormat {
+    /**
+     * Create a story format.
+     * @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?: string, version?: string, description?: string, author?: string, image?: string, url?: string, license?: string, proofing?: boolean, source?: string);
+    /**
+     * @param {string} n - Replacement name
+     */
+    set name(n: string);
+    /**
+     * Name
+     * @returns {string} Name
+     */
+    get name(): string;
+    /**
+     * @param {string} n - Replacement version
+     */
+    set version(n: string);
+    /**
+     * Version
+     * @returns {string} Version
+     */
+    get version(): string;
+    /**
+     * @param {string} d - Replacement description
+     */
+    set description(d: string);
+    /**
+     * Description
+     * @returns {string} Description
+     */
+    get description(): string;
+    /**
+     * @param {string} a - Replacement author
+     */
+    set author(a: string);
+    /**
+     * Author
+     * @returns {string} Author
+     */
+    get author(): string;
+    /**
+     * @param {string} i - Replacement image
+     */
+    set image(i: string);
+    /**
+     * Image
+     * @returns {string} Image
+     */
+    get image(): string;
+    /**
+     * @param {string} u - Replacement URL
+     */
+    set url(u: string);
+    /**
+     * URL
+     * @returns {string} URL
+     */
+    get url(): string;
+    /**
+     * @param {string} l - Replacement license
+     */
+    set license(l: string);
+    /**
+     * License
+     * @returns {string} License
+     */
+    get license(): string;
+    /**
+     * @param {boolean} p - Replacement proofing
+     */
+    set proofing(p: boolean);
+    /**
+     * Proofing
+     * @returns {boolean} Proofing
+     */
+    get proofing(): boolean;
+    /**
+     * @param {string} s - Replacement source
+     */
+    set source(s: string);
+    /**
+     * Source
+     * @returns {string} Source
+     */
+    get source(): string;
+    #private;
+}

package/types/src/TWS/parse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parse TWS file (as Buffer) into Story.
+ * Unless it throws an error, it will return a Story object.
+ *
+ * See: Twine 1 TWS Documentation [Approval Pending]
+ * @param {Buffer} binaryFileContents - File contents to parse as Buffer.
+ * @returns {Story} Story object.
+ */
+export function parse(binaryFileContents: Buffer): Story;
+import Story from '../Story.js';

package/types/src/Twee/parse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parses Twee 3 text into a Story object.
+ *
+ * See: Twee 3 Specification
+ * (https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
+ * @param {string} fileContents - File contents to parse
+ * @returns {Story} story
+ */
+export function parse(fileContents: string): Story;
+import Story from '../Story.js';

package/types/src/Twine1HTML/compile.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Write a combination of Story object, `engine.js` (from Twine 1), `header.html`, and optional `code.js`.
+ * @param {Story} story - Story object to write.
+ * @param {string} engine - Source of `engine.js` file from Twine 1.
+ * @param {string} header - `header.html` content for Twine 1 story format.
+ * @param {string} name - Name of the story format (needed for `code.js` inclusion).
+ * @param {string} codeJS - `code.js` content with additional JavaScript.
+ * @param {object} config - Limited configuration object acting in place of `StorySettings`.
+ * @param {string} config.jquery - jQuery source.
+ * @param {string} config.modernizr - Modernizr source.
+ * @returns {string} Twine 1 HTML.
+ */
+export function compile(story: Story, engine?: string, header?: string, name?: string, codeJS?: string, config?: {
+    jquery: string;
+    modernizr: string;
+}): string;
+import Story from '../Story.js';

package/types/src/Twine1HTML/parse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parses Twine 1 HTML into a Story object.
+ *
+ * See: Twine 1 HTML Output Documentation
+ * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md)
+ * @param {string} content - Twine 1 HTML content to parse.
+ * @returns {Story} Story object
+ */
+export function parse(content: string): Story;
+import Story from '../Story.js';

package/types/src/Twine2ArchiveHTML/compile.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Write array of Story objects into Twine 2 Archive HTML.
+ * @param {Array} stories - Array of Story objects.
+ * @returns {string} Twine 2 Archive HTML.
+ */
+export function compile(stories: any[]): string;

package/types/src/Twine2ArchiveHTML/parse.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse HTML for one or more Twine 2 HTML elements and return array of story objects.
+ * @param {string} content - Content to parse for Twine 2 HTML elements.
+ * @returns {Array} Array of stories found in content.
+ */
+export function parse(content: string): any[];

package/types/src/Twine2HTML/compile.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Write a combination of Story + StoryFormat into Twine 2 HTML file.
+ * @param {Story} story - Story object to write.
+ * @param {StoryFormat} storyFormat - StoryFormat to write.
+ * @returns {string} Twine 2 HTML.
+ */
+export function compile(story: Story, storyFormat: StoryFormat): string;
+import Story from '../Story.js';
+import StoryFormat from '../StoryFormat.js';

package/types/src/Twine2HTML/parse.d.ts

@@ -0,0 +1,17 @@
+export default parse;
+/**
+ * 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
+ */
+export function parse(content: string): Story;
+/**
+ * Try to escape Twine 2 meta-characters.
+ * @param {string} result - Text to parse.
+ * @returns {string} Escaped characters.
+ */
+export function escapeMetacharacters(result: string): string;
+import Story from '../Story.js';

package/types/src/extwee.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/web-index.js

@@ -8,7 +8,7 @@ import { parse as parseTWS } from './src/TWS/parse.js';
 import { compile as compileTwine1HTML } from './src/Twine1HTML/compile.js';
 import { compile as compileTwine2HTML } from './src/Twine2HTML/compile.js';
 import { compile as compileTwine2ArchiveHTML } from './src/Twine2ArchiveHTML/compile.js';
-import Story from './src/Story.js';
+import { Story } from './src/Story.js';
 import Passage from './src/Passage.js';
 import StoryFormat from './src/StoryFormat.js';