extwee 2.2.6 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/.github/workflows/dependabot-automerge.yml +23 -0
  2. package/.github/workflows/nodejs.yml +4 -1
  3. package/README.md +9 -0
  4. package/SECURITY.md +1 -1
  5. package/build/extwee.web.min.js +2 -0
  6. package/build/extwee.web.min.js.LICENSE.txt +1 -0
  7. package/extwee.config.json +6 -0
  8. package/extwee.config.md +67 -0
  9. package/package.json +22 -22
  10. package/src/CLI/CommandLineProcessing.js +196 -0
  11. package/src/CLI/ProcessConfig/loadStoryFormat.js +102 -0
  12. package/src/CLI/ProcessConfig/readDirectories.js +46 -0
  13. package/src/CLI/ProcessConfig.js +175 -0
  14. package/src/CLI/isDirectory.js +27 -0
  15. package/src/CLI/isFile.js +28 -0
  16. package/src/Config/parser.js +30 -8
  17. package/src/Passage.js +17 -2
  18. package/src/Story.js +92 -1
  19. package/src/extwee.js +20 -195
  20. package/test/Config/Config.test.js +40 -10
  21. package/test/Config/files/full.json +8 -0
  22. package/test/Config/files/valid.json +4 -3
  23. package/test/Config/isDirectory.test.js +44 -0
  24. package/test/Config/isFile.test.js +50 -0
  25. package/test/Config/loadStoryFormat.test.js +101 -0
  26. package/test/Config/readDirectories.test.js +68 -0
  27. package/test/Objects/Passage.test.js +5 -0
  28. package/test/Objects/Story.test.js +131 -0
  29. package/test/TWS/Parse.test.js +0 -22
  30. package/test/Web/window.Extwee.test.js +85 -0
  31. package/types/Story.d.ts +25 -0
  32. package/types/index.d.ts +4 -2
  33. package/types/src/CLI/CommandLineProcessing.d.ts +8 -0
  34. package/types/src/CLI/ProcessConfig/loadStoryFormat.d.ts +20 -0
  35. package/types/src/CLI/ProcessConfig/readDirectories.d.ts +9 -0
  36. package/types/src/CLI/ProcessConfig.d.ts +12 -0
  37. package/types/src/CLI/isDirectory.d.ts +1 -0
  38. package/types/src/CLI/isFile.d.ts +1 -0
  39. package/types/src/Config/parser.d.ts +6 -0
  40. package/types/src/Config/reader.d.ts +11 -0
  41. package/types/src/IFID/generate.d.ts +14 -0
  42. package/types/src/JSON/parse.d.ts +44 -1
  43. package/types/src/Passage.d.ts +49 -4
  44. package/types/src/Story.d.ts +110 -16
  45. package/types/src/StoryFormat/compile.d.ts +8 -0
  46. package/types/src/StoryFormat/parse.d.ts +46 -3
  47. package/types/src/StoryFormat.d.ts +69 -38
  48. package/types/src/TWS/parse.d.ts +3 -3
  49. package/types/src/Twee/parse.d.ts +3 -4
  50. package/types/src/Twine1HTML/compile.d.ts +3 -1
  51. package/types/src/Twine1HTML/parse.d.ts +3 -4
  52. package/types/src/Twine2ArchiveHTML/compile.d.ts +8 -0
  53. package/types/src/Twine2ArchiveHTML/parse.d.ts +31 -1
  54. package/types/src/Twine2HTML/compile.d.ts +7 -2
  55. package/types/src/Twine2HTML/parse.d.ts +12 -9
  56. package/index.html +0 -22
  57. package/test/TWS/TWSParser/Example1.tws +0 -150
@@ -1,8 +1,51 @@
1
1
  /**
2
2
  * Parse JSON representation into Story.
3
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-jsonoutput-doc.md Twine 2 JSON Specification}
3
4
  * @function parse
4
5
  * @param {string} jsonString - JSON string to convert to Story.
6
+ * @throws {Error} - Invalid JSON!
5
7
  * @returns {Story} Story object.
8
+ * @example
9
+ * const jsonString = `{
10
+ * "name": "My Story",
11
+ * "start": "First Passage",
12
+ * "ifid": "A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6",
13
+ * "format": "SugarCube",
14
+ * "formatVersion": "2.31.0",
15
+ * "creator": "Twine",
16
+ * "creatorVersion": "2.3.9",
17
+ * "zoom": 1,
18
+ * "passages": [
19
+ * {
20
+ * "name": "First Passage",
21
+ * "tags": "",
22
+ * "metadata": "",
23
+ * "text": "This is the first passage."
24
+ * },
25
+ * ]
26
+ * }`;
27
+ * const story = parse(jsonString);
28
+ * console.log(story);
29
+ * // => Story {
30
+ * // name: 'My Story',
31
+ * // start: 'First Passage',
32
+ * // IFID: 'A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6',
33
+ * // format: 'SugarCube',
34
+ * // formatVersion: '2.31.0',
35
+ * // creator: 'Twine',
36
+ * // creatorVersion: '2.3.9',
37
+ * // zoom: 1,
38
+ * // tagColors: {},
39
+ * // metadata: {},
40
+ * // passages: [
41
+ * // Passage {
42
+ * // name: 'First Passage',
43
+ * // tags: '',
44
+ * // metadata: '',
45
+ * // text: 'This is the first passage.'
46
+ * // }
47
+ * // ]
48
+ * // }
6
49
  */
7
50
  export function parse(jsonString: string): Story;
8
- import Story from '../Story.js';
51
+ import { Story } from '../Story.js';
@@ -1,6 +1,40 @@
1
1
  /**
2
- * A passage is the smallest unit of a Twine story.
3
- */
2
+ * Passage class.
3
+ * @class
4
+ * @classdesc Represents a passage in a Twine story.
5
+ * @property {string} name - Name of the passage.
6
+ * @property {Array} tags - Tags for the passage.
7
+ * @property {object} metadata - Metadata for the passage.
8
+ * @property {string} text - Text content of the passage.
9
+ * @method {string} toTwee - Return a Twee representation.
10
+ * @method {string} toJSON - Return JSON representation.
11
+ * @method {string} toTwine2HTML - Return Twine 2 HTML representation.
12
+ * @method {string} toTwine1HTML - Return Twine 1 HTML representation.
13
+ * @example
14
+ * const p = new Passage('Start', 'This is the start of the story.');
15
+ * console.log(p.toTwee());
16
+ * // :: Start
17
+ * // This is the start of the story.
18
+ * //
19
+ * console.log(p.toJSON());
20
+ * // {"name":"Start","tags":[],"metadata":{},"text":"This is the start of the story."}
21
+ * console.log(p.toTwine2HTML());
22
+ * // <tw-passagedata pid="1" name="Start" tags="" >This is the start of the story.</tw-passagedata>
23
+ * console.log(p.toTwine1HTML());
24
+ * // <div tiddler="Start" tags="" modifier="extwee" twine-position="10,10">This is the start of the story.</div>
25
+ * @example
26
+ * const p = new Passage('Start', 'This is the start of the story.', ['start', 'beginning'], {position: '10,10', size: '100,100'});
27
+ * console.log(p.toTwee());
28
+ * // :: Start [start beginning] {"position":"10,10","size":"100,100"}
29
+ * // This is the start of the story.
30
+ * //
31
+ * console.log(p.toJSON());
32
+ * // {"name":"Start","tags":["start","beginning"],"metadata":{"position":"10,10","size":"100,100"},"text":"This is the start of the story."}
33
+ * console.log(p.toTwine2HTML());
34
+ * // <tw-passagedata pid="1" name="Start" tags="start beginning" position="10,10" size="100,100">This is the start of the story.</tw-passagedata>
35
+ * console.log(p.toTwine1HTML());
36
+ * // <div tiddler="Start" tags="start beginning" modifier="extwee" twine-position="10,10">This is the start of the story.</div>
37
+ */
4
38
  export default class Passage {
5
39
  /**
6
40
  * Create a passage.
@@ -12,6 +46,7 @@ export default class Passage {
12
46
  constructor(name?: string, text?: string, tags?: any[], metadata?: object);
13
47
  /**
14
48
  * @param {string} s - Name to replace
49
+ * @throws {Error} Name must be a String!
15
50
  */
16
51
  set name(s: string);
17
52
  /**
@@ -21,6 +56,7 @@ export default class Passage {
21
56
  get name(): string;
22
57
  /**
23
58
  * @param {Array} t - Replacement array
59
+ * @throws {Error} Tags must be an array!
24
60
  */
25
61
  set tags(t: any[]);
26
62
  /**
@@ -30,15 +66,17 @@ export default class Passage {
30
66
  get tags(): any[];
31
67
  /**
32
68
  * @param {object} m - Replacement object
69
+ * @throws {Error} Metadata must be an object literal!
33
70
  */
34
- set metadata(m: any);
71
+ set metadata(m: object);
35
72
  /**
36
73
  * Metadata
37
74
  * @returns {object} Metadata
38
75
  */
39
- get metadata(): any;
76
+ get metadata(): object;
40
77
  /**
41
78
  * @param {string} t - Replacement text
79
+ * @throws {Error} Text should be a String!
42
80
  */
43
81
  set text(t: string);
44
82
  /**
@@ -48,23 +86,30 @@ export default class Passage {
48
86
  get text(): string;
49
87
  /**
50
88
  * Return a Twee representation.
89
+ *
90
+ * See: https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md
91
+ *
92
+ * @method toTwee
51
93
  * @returns {string} String form of passage.
52
94
  */
53
95
  toTwee(): string;
54
96
  /**
55
97
  * Return JSON representation.
98
+ * @method toJSON
56
99
  * @returns {string} JSON string.
57
100
  */
58
101
  toJSON(): string;
59
102
  /**
60
103
  * Return Twine 2 HTML representation.
61
104
  * (Default Passage ID is 1.)
105
+ * @method toTwine2HTML
62
106
  * @param {number} pid - Passage ID (PID) to record in HTML.
63
107
  * @returns {string} Twine 2 HTML string.
64
108
  */
65
109
  toTwine2HTML(pid?: number): string;
66
110
  /**
67
111
  * Return Twine 1 HTML representation.
112
+ * @method toTwine1HTML
68
113
  * @returns {string} Twine 1 HTML string.
69
114
  */
70
115
  toTwine1HTML(): string;
@@ -1,4 +1,40 @@
1
- export default class Story {
1
+ /**
2
+ * Story class.
3
+ * @class
4
+ * @classdesc Represents a Twine story.
5
+ * @property {string} name - Name of the story.
6
+ * @property {string} IFID - Interactive Fiction ID (IFID) of Story.
7
+ * @property {string} start - Name of start passage.
8
+ * @property {string} format - Story format of Story.
9
+ * @property {string} formatVersion - Story format version of Story.
10
+ * @property {number} zoom - Zoom level.
11
+ * @property {Array} passages - Array of Passage objects. @see {@link Passage}
12
+ * @property {string} creator - Program used to create Story.
13
+ * @property {string} creatorVersion - Version used to create Story.
14
+ * @property {object} metadata - Metadata of Story.
15
+ * @property {object} tagColors - Tag Colors
16
+ * @property {string} storyJavaScript - Story JavaScript
17
+ * @property {string} storyStylesheet - Story Stylesheet
18
+ * @method {number} addPassage - Add a passage to the story and returns the new length of the passages array.
19
+ * @method {number} removePassageByName - Remove a passage from the story by name and returns the new length of the passages array.
20
+ * @method {Array} getPassagesByTag - Find passages by tag.
21
+ * @method {Array} getPassageByName - Find passage by name.
22
+ * @method {number} size - Size (number of passages).
23
+ * @method {string} toJSON - Export Story as JSON representation.
24
+ * @method {string} toTwee - Return Twee representation.
25
+ * @method {string} toTwine2HTML - Return Twine 2 HTML representation.
26
+ * @method {string} toTwine1HTML - Return Twine 1 HTML representation.
27
+ * @example
28
+ * const story = new Story('My Story');
29
+ * story.IFID = '12345678-1234-5678-1234-567812345678';
30
+ * story.start = 'Start';
31
+ * story.format = 'SugarCube';
32
+ * story.formatVersion = '2.31.0';
33
+ * story.zoom = 1;
34
+ * story.creator = 'extwee';
35
+ * story.creatorVersion = '2.2.1';
36
+ */
37
+ export class Story {
2
38
  /**
3
39
  * Creates a story.
4
40
  * @param {string} name - Name of the story.
@@ -16,18 +52,18 @@ export default class Story {
16
52
  /**
17
53
  * @param {object} a - Replacement tag colors
18
54
  */
19
- set tagColors(a: any);
55
+ set tagColors(a: object);
20
56
  /**
21
57
  * Tag Colors object (each property is a tag and its color)
22
58
  * @returns {object} tag colors array
23
59
  */
24
- get tagColors(): any;
60
+ get tagColors(): object;
25
61
  /**
26
- * @param {string} i - Replacement IFID
62
+ * @param {string} i - Replacement IFID.
27
63
  */
28
64
  set IFID(i: string);
29
65
  /**
30
- * Interactive Fiction ID (IFID) of Story
66
+ * Interactive Fiction ID (IFID) of Story.
31
67
  * @returns {string} IFID
32
68
  */
33
69
  get IFID(): string;
@@ -52,12 +88,12 @@ export default class Story {
52
88
  /**
53
89
  * @param {object} o - Replacement metadata
54
90
  */
55
- set metadata(o: any);
91
+ set metadata(o: object);
56
92
  /**
57
93
  * Metadata of Story.
58
94
  * @returns {object} metadata of story
59
95
  */
60
- get metadata(): any;
96
+ get metadata(): object;
61
97
  /**
62
98
  * @param {string} f - Replacement format
63
99
  */
@@ -94,41 +130,77 @@ export default class Story {
94
130
  * @returns {number} Zoom level
95
131
  */
96
132
  get zoom(): number;
133
+ /**
134
+ * Set passages in Story.
135
+ * @param {Array} p - Replacement passages
136
+ * @property {Array} passages - Passages
137
+ * @throws {Error} Passages must be an Array!
138
+ * @throws {Error} Passages must be an Array of Passage objects!
139
+ */
140
+ set passages(p: any[]);
141
+ /**
142
+ * Passages in Story.
143
+ * @returns {Array} Passages
144
+ * @property {Array} passages - Passages
145
+ */
146
+ get passages(): any[];
147
+ /**
148
+ * @param {string} s - Replacement story stylesheet
149
+ */
150
+ set storyStylesheet(s: string);
151
+ /**
152
+ * Story stylesheet data can be set as a passage, property value, or both.
153
+ * @returns {string} storyStylesheet
154
+ */
155
+ get storyStylesheet(): string;
156
+ /**
157
+ * Set story JavaScript.
158
+ * @param {string} s - Replacement story JavaScript
159
+ */
160
+ set storyJavaScript(s: string);
161
+ /**
162
+ * Get story JavaScript.
163
+ * @returns {string} storyJavaScript
164
+ */
165
+ get storyJavaScript(): string;
97
166
  /**
98
167
  * Add a passage to the story.
99
- * `StoryData` will override story metadata and `StoryTitle` will override story name.
168
+ * Passing `StoryData` will override story metadata and `StoryTitle` will override story name.
169
+ * @method addPassage
100
170
  * @param {Passage} p - Passage to add to Story.
171
+ * @returns {number} Return new length of passages array.
101
172
  */
102
- addPassage(p: Passage): void;
173
+ addPassage(p: Passage): number;
103
174
  /**
104
175
  * Remove a passage from the story by name.
105
- * @param {string} name - Passage name to remove
176
+ * @method removePassageByName
177
+ * @param {string} name - Passage name to remove.
178
+ * @returns {number} Return new length of passages array.
106
179
  */
107
- removePassageByName(name: string): void;
180
+ removePassageByName(name: string): number;
108
181
  /**
109
182
  * Find passages by tag.
183
+ * @method getPassagesByTag
110
184
  * @param {string} t - Passage name to search for
111
185
  * @returns {Array} Return array of passages
112
186
  */
113
187
  getPassagesByTag(t: string): any[];
114
188
  /**
115
189
  * Find passage by name.
190
+ * @method getPassageByName
116
191
  * @param {string} name - Passage name to search for
117
192
  * @returns {Passage | null} Return passage or null
118
193
  */
119
194
  getPassageByName(name: string): Passage | null;
120
195
  /**
121
196
  * Size (number of passages).
197
+ * @method size
122
198
  * @returns {number} Return number of passages
123
199
  */
124
200
  size(): number;
125
- /**
126
- * forEach-style iterator of passages in Story.
127
- * @param {Function} callback - Callback function
128
- */
129
- forEachPassage(callback: Function): void;
130
201
  /**
131
202
  * Export Story as JSON representation.
203
+ * @method toJSON
132
204
  * @returns {string} JSON string.
133
205
  */
134
206
  toJSON(): string;
@@ -137,6 +209,8 @@ export default class Story {
137
209
  *
138
210
  * See: Twee 3 Specification
139
211
  * (https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
212
+ *
213
+ * @method toTwee
140
214
  * @returns {string} Twee String
141
215
  */
142
216
  toTwee(): string;
@@ -145,6 +219,22 @@ export default class Story {
145
219
  *
146
220
  * See: Twine 2 HTML Output
147
221
  * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md)
222
+ *
223
+ * The only required attributes are `name` and `ifid` of the `<tw-storydata>` element. All others are optional.
224
+ *
225
+ * The `<tw-storydata>` element may have any number of optional attributes, which are:
226
+ * - `startnode`: (integer) Optional. The PID of the starting passage.
227
+ * - `creator`: (string) Optional. The name of the program that created the story.
228
+ * - `creator-version`: (string) Optional. The version of the program that created the story.
229
+ * - `zoom`: (decimal) Optional. The zoom level of the story.
230
+ * - `format`: (string) Optional. The format of the story.
231
+ * - `format-version`: (string) Optional. The version of the format of the story.
232
+ *
233
+ * Because story stylesheet data can be represented as a passage, property value, or both, all approaches are encoded.
234
+ *
235
+ * Because story JavaScript can be represented as a passage, property value, or both, all approaches are encoded.
236
+ *
237
+ * @method toTwine2HTML
148
238
  * @returns {string} Twine 2 HTML string
149
239
  */
150
240
  toTwine2HTML(): string;
@@ -153,9 +243,13 @@ export default class Story {
153
243
  *
154
244
  * See: Twine 1 HTML Output
155
245
  * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md)
246
+ *
247
+ * @method toTwine1HTML
156
248
  * @returns {string} Twine 1 HTML string.
157
249
  */
158
250
  toTwine1HTML(): string;
159
251
  #private;
160
252
  }
253
+ export const creatorName: "extwee";
254
+ export const creatorVersion: "2.3.0";
161
255
  import Passage from './Passage.js';
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Compiles a {@link StoryFormat} object into a JSONP string for writing to a `format.js` file.
3
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
4
+ * @param {StoryFormat} storyFormat Story format object to compile.
5
+ * @returns {string} JSONP string.
6
+ */
7
+ export function compile(storyFormat: StoryFormat): string;
8
+ import StoryFormat from '../StoryFormat.js';
@@ -1,7 +1,50 @@
1
1
  /**
2
- * Parse a Story Format file.
3
- * @param {string} contents - Content
4
- * @returns {StoryFormat} StoryFormat object
2
+ * Parses story format content into a {@link StoryFormat} object.
3
+ *
4
+ * Story formats are generally JSONP files containing a JSON object with the following properties:
5
+ * - name: (string) Optional. (Omitting the name will lead to an Untitled Story Format.)
6
+ * - version: (string) Required, and semantic version-style formatting (x.y.z, e.g., 1.2.1) of the version is also required.
7
+ * - author: (string) Optional.
8
+ * - description: (string) Optional.
9
+ * - image: (string) Optional.
10
+ * - url: (string) Optional.
11
+ * - license: (string) Optional.
12
+ * - proofing: (boolean) Optional (defaults to false).
13
+ * - source: (string) Required.
14
+ *
15
+ * If existing properties do not match their expected type, a warning will be produced and incoming value will be ignored.
16
+ *
17
+ * This function does "soft parsing." It will not throw an error if a specific property is missing or malformed.
18
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
19
+ * @function parse
20
+ * @param {string} contents - JSONP content.
21
+ * @throws {Error} - Unable to find Twine 2 JSON chunk!
22
+ * @throws {Error} - Unable to parse Twine 2 JSON chunk!
23
+ * @returns {StoryFormat} StoryFormat object.
24
+ * @example
25
+ * const contents = `{
26
+ * "name": "My Story Format",
27
+ * "version": "1.0.0",
28
+ * "author": "Twine",
29
+ * "description": "A story format.",
30
+ * "image": "icon.svg",
31
+ * "url": "https://example.com",
32
+ * "license": "MIT",
33
+ * "proofing": false,
34
+ * "source": "<html></html>"
35
+ * }`;
36
+ * const storyFormat = parse(contents);
37
+ * console.log(storyFormat);
38
+ * // => StoryFormat {
39
+ * // name: 'My Story Format',
40
+ * // version: '1.0.0',
41
+ * // description: 'A story format.',
42
+ * // image: 'icon.svg',
43
+ * // url: 'https://example.com',
44
+ * // license: 'MIT',
45
+ * // proofing: false,
46
+ * // source: '<html></html>'
47
+ * // }
5
48
  */
6
49
  export function parse(contents: string): StoryFormat;
7
50
  import StoryFormat from '../StoryFormat.js';
@@ -1,97 +1,128 @@
1
+ /**
2
+ * StoryFormat representing a Twine 2 story format.
3
+ *
4
+ * This class has type checking on all of its properties.
5
+ * If a property is set to a value of the wrong type, a TypeError will be thrown.
6
+ *
7
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-storyformats-spec.md Twine 2 Story Formats Specification}
8
+ *
9
+ * @class
10
+ * @classdesc A class representing a Twine 2 story format.
11
+ * @property {string} name - The name of the story format.
12
+ * @property {string} version - The semantic version of the story format.
13
+ * @property {string} description - The description of the story format.
14
+ * @property {string} author - The author of the story format.
15
+ * @property {string} image - The image of the story format.
16
+ * @property {string} url - The URL of the story format.
17
+ * @property {string} license - The license of the story format.
18
+ * @property {boolean} proofing - The proofing of the story format.
19
+ * @property {string} source - The source of the story format.
20
+ * @example
21
+ * const sf = new StoryFormat();
22
+ * sf.name = 'New';
23
+ * sf.version = '1.0.0';
24
+ * sf.description = 'New';
25
+ * sf.author = 'New';
26
+ * sf.image = 'New';
27
+ * sf.url = 'New';
28
+ * sf.license = 'New';
29
+ * sf.proofing = true;
30
+ * sf.source = 'New';
31
+ */
1
32
  export default class StoryFormat {
2
- /**
3
- * Create a story format.
4
- * @param {string} name - Name
5
- * @param {string} version - Version
6
- * @param {string} description - Description
7
- * @param {string} author - Author
8
- * @param {string} image - Image
9
- * @param {string} url - URL
10
- * @param {string} license - License
11
- * @param {boolean} proofing - If proofing or not
12
- * @param {string} source - Source
13
- */
14
33
  constructor(name?: string, version?: string, description?: string, author?: string, image?: string, url?: string, license?: string, proofing?: boolean, source?: string);
15
34
  /**
16
- * @param {string} n - Replacement name
35
+ * @param {string} n - Replacement name.
17
36
  */
18
37
  set name(n: string);
19
38
  /**
20
39
  * Name
21
- * @returns {string} Name
40
+ * @returns {string} Name.
22
41
  */
23
42
  get name(): string;
24
43
  /**
25
- * @param {string} n - Replacement version
44
+ * @param {string} n - Replacement version.
26
45
  */
27
46
  set version(n: string);
28
47
  /**
29
- * Version
30
- * @returns {string} Version
48
+ * Version.
49
+ * @returns {string} Version.
31
50
  */
32
51
  get version(): string;
33
52
  /**
34
- * @param {string} d - Replacement description
53
+ * @param {string} d - Replacement description.
35
54
  */
36
55
  set description(d: string);
37
56
  /**
38
- * Description
39
- * @returns {string} Description
57
+ * Description.
58
+ * @returns {string} Description.
40
59
  */
41
60
  get description(): string;
42
61
  /**
43
- * @param {string} a - Replacement author
62
+ * @param {string} a - Replacement author.
44
63
  */
45
64
  set author(a: string);
46
65
  /**
47
- * Author
48
- * @returns {string} Author
66
+ * Author.
67
+ * @returns {string} Author.
49
68
  */
50
69
  get author(): string;
51
70
  /**
52
- * @param {string} i - Replacement image
71
+ * @param {string} i - Replacement image.
53
72
  */
54
73
  set image(i: string);
55
74
  /**
56
- * Image
57
- * @returns {string} Image
75
+ * Image.
76
+ * @returns {string} Image.
58
77
  */
59
78
  get image(): string;
60
79
  /**
61
- * @param {string} u - Replacement URL
80
+ * @param {string} u - Replacement URL.
62
81
  */
63
82
  set url(u: string);
64
83
  /**
65
- * URL
66
- * @returns {string} URL
84
+ * URL.
85
+ * @returns {string} URL.
67
86
  */
68
87
  get url(): string;
69
88
  /**
70
- * @param {string} l - Replacement license
89
+ * @param {string} l - Replacement license.
71
90
  */
72
91
  set license(l: string);
73
92
  /**
74
- * License
75
- * @returns {string} License
93
+ * License.
94
+ * @returns {string} License.
76
95
  */
77
96
  get license(): string;
78
97
  /**
79
- * @param {boolean} p - Replacement proofing
98
+ * @param {boolean} p - Replacement proofing.
80
99
  */
81
100
  set proofing(p: boolean);
82
101
  /**
83
- * Proofing
84
- * @returns {boolean} Proofing
102
+ * Proofing.
103
+ * @returns {boolean} Proofing.
85
104
  */
86
105
  get proofing(): boolean;
87
106
  /**
88
- * @param {string} s - Replacement source
107
+ * @param {string} s - Replacement source.
89
108
  */
90
109
  set source(s: string);
91
110
  /**
92
- * Source
93
- * @returns {string} Source
111
+ * Source.
112
+ * @returns {string} Source.
94
113
  */
95
114
  get source(): string;
115
+ /**
116
+ * Produces a string representation of the story format object.
117
+ * @method toString
118
+ * @returns {string} - A string representation of the story format.
119
+ */
120
+ toString(): string;
121
+ /**
122
+ * Produces a JSON representation of the story format object.
123
+ * @method toJSON
124
+ * @returns {object} - A JSON representation of the story format.
125
+ */
126
+ toJSON(): object;
96
127
  #private;
97
128
  }
@@ -1,10 +1,10 @@
1
1
  /**
2
2
  * Parse TWS file (as Buffer) into Story.
3
3
  * Unless it throws an error, it will return a Story object.
4
- *
5
- * See: Twine 1 TWS Documentation [Approval Pending]
4
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md Twine 1 HTML Documentation}
5
+ * @function parse
6
6
  * @param {Buffer} binaryFileContents - File contents to parse as Buffer.
7
7
  * @returns {Story} Story object.
8
8
  */
9
9
  export function parse(binaryFileContents: Buffer): Story;
10
- import Story from '../Story.js';
10
+ import { Story } from '../Story.js';
@@ -1,10 +1,9 @@
1
1
  /**
2
2
  * Parses Twee 3 text into a Story object.
3
- *
4
- * See: Twee 3 Specification
5
- * (https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md)
3
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md Twee 3 Specification}
4
+ * @function parse
6
5
  * @param {string} fileContents - File contents to parse
7
6
  * @returns {Story} story
8
7
  */
9
8
  export function parse(fileContents: string): Story;
10
- import Story from '../Story.js';
9
+ import { Story } from '../Story.js';
@@ -1,5 +1,7 @@
1
1
  /**
2
2
  * Write a combination of Story object, `engine.js` (from Twine 1), `header.html`, and optional `code.js`.
3
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md Twine 1 HTML Documentation}
4
+ * @function compile
3
5
  * @param {Story} story - Story object to write.
4
6
  * @param {string} engine - Source of `engine.js` file from Twine 1.
5
7
  * @param {string} header - `header.html` content for Twine 1 story format.
@@ -14,4 +16,4 @@ export function compile(story: Story, engine?: string, header?: string, name?: s
14
16
  jquery: string;
15
17
  modernizr: string;
16
18
  }): string;
17
- import Story from '../Story.js';
19
+ import { Story } from '../Story.js';
@@ -1,10 +1,9 @@
1
1
  /**
2
2
  * Parses Twine 1 HTML into a Story object.
3
- *
4
- * See: Twine 1 HTML Output Documentation
5
- * (https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md)
3
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-1-htmloutput-doc.md Twine 1 HTML Documentation}
4
+ * @function parse
6
5
  * @param {string} content - Twine 1 HTML content to parse.
7
6
  * @returns {Story} Story object
8
7
  */
9
8
  export function parse(content: string): Story;
10
- import Story from '../Story.js';
9
+ import { Story } from '../Story.js';
@@ -1,6 +1,14 @@
1
1
  /**
2
2
  * Write array of Story objects into Twine 2 Archive HTML.
3
+ * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-archive-spec.md Twine 2 Archive Specification}
4
+ * @function compile
3
5
  * @param {Array} stories - Array of Story objects.
4
6
  * @returns {string} Twine 2 Archive HTML.
7
+ * @example
8
+ * const story1 = new Story();
9
+ * const story2 = new Story();
10
+ * const stories = [story1, story2];
11
+ * console.log(compile(stories));
12
+ * // => '<tw-storydata name="Untitled" startnode="1" creator="Twine" creator-version="2.3.9" ifid="A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6" zoom="1" format="Harlowe" format-version="3.1.0" options="" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="Untitled Passage" tags="" position="0,0" size="100,100"></tw-passagedata></tw-storydata>\n\n<tw-storydata name="Untitled" startnode="1" creator="Twine" creator-version="2.3.9" ifid="A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6" zoom="1" format="Harlowe" format-version="3.1.0" options="" hidden><style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css"></style><script role="script" id="twine-user-script" type="text/twine-javascript"></script><tw-passagedata pid="1" name="Untitled Passage" tags="" position="0,0" size="100,100"></tw-passagedata></tw-storydata>\n\n'
5
13
  */
6
14
  export function compile(stories: any[]): string;