Merge branch 'master' into issue/rename-inklecate.js

Author: smwhr

README.md

@@ -42,14 +42,14 @@ If you frequently need to update your story, pasting the content into `story.js`
 Once the server is running, use the [other boilerplate](https://github.com/y-lohse/inkjs/blob/master/templates/browser_with_server) and place your story content inside `story.json`. Behind the scenes, the only difference is that we load the JSON file via ajax before creating the story:
 
 ```javascript
-fetch("story.json")
-  .then(function (response) {
-    return response.text();
-  })
-  .then(function (storyContent) {
-    story = new inkjs.Story(storyContent);
-    continueStory();
-  });
+fetch('story.json')
+	.then(function (response) {
+		return response.text();
+	})
+	.then(function (storyContent) {
+		story = new inkjs.Story(storyContent);
+		continueStory();
+	});
 ```
 
 ## Using node.js
@@ -65,14 +65,14 @@ Require the module: `var Story = require('inkjs').Story;`.
 You can load the json file using a simple call to `require`:
 
 ```javascript
-var json = require("./ink_file.json");
+var json = require('./ink_file.json');
 ```
 
 You can also load it using `fs`. In that case, please note that inklecate outputs a json file encoded **with** BOM, and node isn't very good at handling that.
 
 ```javascript
-var fs = require("fs");
-var json = fs.readFileSync("./ink_file.json", "UTF-8").replace(/^\uFEFF/, ""); //strips the BOM
+var fs = require('fs');
+var json = fs.readFileSync('./ink_file.json', 'UTF-8').replace(/^\uFEFF/, ''); //strips the BOM
 ```
 
 ### Starting a story
@@ -92,15 +92,15 @@ From there on, you can follow [the official documentation](https://github.com/in
 
 There are a few very minor API differences between ink C# and inkjs:
 
-### [Getting and setting ink variables](https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#settinggetting-ink-variables).
+### [Getting and setting ink variables](https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#settinggetting-ink-variables)
 
 On platforms that do not support [ES2015 Proxies](https://kangax.github.io/compat-table/es6/) (basically node.js v5, IE 11, Safari 9 and everything below), you can't directly read and write variables to the story state. Instead you will have to use the `$` function:
 
 ```javascript
-_inkStory.variablesState.$("player_health", 100);
+_inkStory.variablesState.$('player_health', 100);
 //instead of _inkStory.variablesState["player_health"] = 100;
 
-var health = _inkStory.variablesState.$("player_health");
+var health = _inkStory.variablesState.$('player_health');
 //instead of var health = _inkStory.variablesState["player_health"];
 ```
 
@@ -109,14 +109,14 @@ var health = _inkStory.variablesState.$("player_health");
 `EvaluateFunction()` lets you evaluate an ink function from within your javascript. The "normal" call is the same than in C#:
 
 ```javascript
-var result = EvaluateFunction("my_ink_function", ["arg1", "arg2"]);
+var result = EvaluateFunction('my_ink_function', ['arg1', 'arg2']);
 //result is the return value of my_ink_function("arg1", "arg2")
 ```
 
 However, if you also wish to retrieve the text that `my_ink_function` output, you need to call it like this:
 
 ```javascript
-var result = EvaluateFunction("my_ink_function", ["arg1", "arg2"], true);
+var result = EvaluateFunction('my_ink_function', ['arg1', 'arg2'], true);
 //now result is an object with two properties:
 // result.returned is the return value of my_ink_function("arg1", "arg2")
 // result.output is the text that was written to the output while the function was evaluated
@@ -125,6 +125,7 @@ var result = EvaluateFunction("my_ink_function", ["arg1", "arg2"], true);
 ## Compiler
 
 ### inkjs-compiler.js
+
 ```shell
 $ node inkjs-compiler.js -h
 
@@ -137,15 +138,19 @@ Usage: inkjs-compiler <options> <ink file>
 ```
 
 ### online compiler
+
 ```javascript
-const story  = (new inkjs.Compiler(`Hello World`)).Compile()
+const story = new inkjs.Compiler(`Hello World`).Compile();
 // story is an inkjs.Story that can be played right away
 
 const jsonBytecode = story.ToJson();
 // the generated json can be further re-used
 ```
 
+You can use this in combination with [Webpack and TypeScript](docs/working-with-typescript-and-webpack.md).
+
 ### Differences with the C# Compiler
+
 See [Differences with the C# Compiler](docs/compiler-differences.md).
 
 ## Compatibility table

docs/compiler-differences.md

@@ -5,15 +5,16 @@
 The C# compiler is intented to always be used on a file system and thus the question of how files are included follow a classic pattern.  
 Nevertheless, when using the compiler inside a browser, the concept of "file" is a blurry one.   
 Inkjs provides 2 file handlers :
-* A POSIX file handler : similar to the one used in the C# compiler that will look for files in folders
-* A JSON file handler : expects a JSON object of the form
+* A JSON file handler : it is included by default : it expects a JSON object representing all the files of the project of the form :
 ```
 {
     "filename1.ink": "INCLUDE filename2.ink",
     "filename2.ink": "This content is included",
 }
 ```
 
+* A POSIX file handler : delivered as a separate `inkjs-full-posixhandler.js` file that must be included/required : similar to the one used in the C# compiler that will look for files in folders.
+
 ## Float and ints
 
 As the JSON format and javascript in general do not differentiate between float and integers, the inkjs runtime is known to behave differently from the C# runtime when dealing with floating point operations.

docs/working-with-typescript-and-webpack.md

@@ -0,0 +1,64 @@
+# Working with TypeScript and Webpack
+
+Version 2.1.0 introduces support for handling ink files directly without having to convert them to JSON first.
+
+This guide explains how to adjust projects using TypeScript and Webpack (common when working with React) to make use of this.
+
+## Webpack
+
+In Webpack 5, static resources are loaded with [Asset Modules](https://webpack.js.org/guides/asset-modules/).
+
+Here we load `.ink` files and inline their content into the script. This is most useful for programs which unconditionally use a single Ink file.
+
+```javascript
+rules: [
+	{
+		test: /\.ink$/i,
+		type: 'asset/source',
+	},
+	// ... and then the rest of your rules
+];
+```
+
+We can then `import` (or `require`) the ink file and compile it.
+
+```typescript
+import * as Inkjs from 'inkjs';
+import data from '../assets/myStory.ink';
+
+const inkStory = new Inkjs.Compiler(data).Compile();
+```
+
+If you are working in JavaScript, then that is all you need.
+
+### TypeScript
+
+If you are working in TypeScript then you will probably see an error message like:
+
+> Cannot find module '../assets/myStory.ink' or its corresponding type declarations.
+
+You need to declare your types for the `.ink` file. This is done using a [Declaration File](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html).
+
+Create one, such as `global.d.ts` in the top level of your source code, which reads like this:
+
+```typescript
+declare module '*.ink' {
+	const value: string;
+	export default value;
+}
+```
+
+This says that when you import an `.ink` file, you will get a string.
+
+This should work, but you might need to adjust your `tsconfig.json` file to tell it where to find `global.d.ts`:
+
+```json
+{
+  compiler: {
+  ...
+  },
+  include: ["path/to/global.d.ts"]
+}
+```
+
+Credit to [felixmosh's Stackoverflow answer](https://stackoverflow.com/a/66176397/19068) for providing my reference for this TypeScript.

ink.d.ts

@@ -1,12 +1,16 @@
 import { Story, InkList } from './engine/Story'
 import { Compiler } from './compiler/Compiler'
 import { CompilerOptions } from './compiler/CompilerOptions'
+import { PosixFileHandler } from './compiler/FileHandler/PosixFileHandler'
+import { JsonFileHandler } from './compiler/FileHandler/JsonFileHandler'
 
 declare interface Inkjs {
     Story: typeof Story
     InkList: typeof InkList
     Compiler: typeof Compiler
     CompilerOptions: typeof CompilerOptions
+    PosixFileHandler: typeof PosixFileHandler
+    JsonFileHandler: typeof JsonFileHandler
 }
 
 declare let inkjs: Inkjs